Introduction

Welcome to the Maxpay documentation!

Below you can find the information and tutorials that will teach you how to use Maxpay hosted payment pages, host to host integration, Payout API and Query on demand API.

To get started with Maxpay you’ll need to sign up at my.maxpay.com.

Hosted payment pages

Overview

Now you can easily receive payments, set up subscriptions and increase your revenue in few clicks. This guide will cover some of the basics of setting up your account, receive payments and using your account.

General

To get started with receiving the payments using Maxpay hosted payment pages you need to:

General settings

Fill up the fields as:

Field Description
Payment page name Name of your payment page, default value is Application
Website url Name of your website for processing
Test success url Test redirect url for successful payments, for unique url value add to payment widget code “success_url”
Live success url Live redirect url for successful payments, for unique url value add to payment widget code “success_url”
Test decline url Test redirect url for declined payments, for unique url value add to payment form code “decline_url”
Live decline url Live redirect url for declined payments, for unique url value add to payment form code “decline_url”
Test callback url Test callback url is for receiving responses from Maxpay
Live callback url Live callback url is for receiving responses from Maxpay.

Create product

You can sell goods by using Maxpay payment flow or either send us the custom products by using custom product API. In section Products to sell you are able to create: fixed, trial or subscription product. Please, use our Guide in Merchant portal with detailed steps of creation.

Payment methods

Here you can manage payment methods available on your payment widget. Just turn on the toggle button for activation. To preselect a payment method on your payment page - add to payment widget code “payment_method” parameter:

Type of payment form Code example
Redirect <input type='hidden' name='payment_method' value='Credit card'>
Pop Up/iFrame data-payment_method="Credit card"

Payment form

Maxpay’s payment form customizer allows you to:

Pop up

Example of Pop up widget:


<div>
    <form class='maxpayPaymentForm'>
        <script src="https://hpp.maxpay.com/client.js"
            class="maxpayScript" 
            data-iframesrc="https://hpp.maxpay.com/hpp"
            data-buttontext="Pay!" 
            data-name="Application" 
            data-key="pkTest_67pcq3B5i8N7utM7WRNM6ZGvxFmHE4W9" 
            data-signature="199d5077dd7be9a8313954bcc7d4fe7ec9b005beab2ef7e00932cc48e3981f87"
            data-uniqueuserid="user123" 
            data-displaybuybutton="true" 
            data-type="popup">
        </script>
    </form>
</div>

Parameters of Pop up widget

Parameter Description
data-buttontext text of the button
data-name name of your payment application
data-key your personal test public key from general settings
data-signature signature of the payment widget, information about a signature generation below
data-uniqueuserid merchant’s unique user ID (unique user ID in merchant’s system)
data-displaybuybutton allows to display or hide the button
data-type data type is popup

Use additional parameters for sending them on Pop widget

Parameter Description
data-uniqueTransactionId this parameter allows to assign a value for the transaction and receive it in callback data, if a value doesn’t pass - Maxpay generates this value by itself
data-productPublicId allows to preselect a product for the payment page, the value is Product ID you can find it in Products to sell section
data-email parameter for sending email value
data-firstname user’s first name
data-lastname user’s last name
data-phone parameter for sending phone value
data-address parameter for sending address value
data-city parameter for sending city value
data-country parameter for sending country value
data-zip parameter for sending zip value
data-success_url parameter for sending success redirect url value
data-decline_url parameter for sending decline redirect url value
data-locale parameter for displaying a language on payment page

iFrame

Example of iFrame widget:


<div>
    <script src="https://hpp.maxpay.com/client.js" 
        class="maxpayScript" 
        data-iframesrc="https://hpp.maxpay.com/hpp"
        data-buttontext="Pay!" 
        data-name="Application" 
        data-key="pkTest_67pcq3B5i8N7utM7WRNM6ZGvxFmHE4W9" 
        data-signature="199d5077dd7be9a8313954bcc7d4fe7ec9b005beab2ef7e00932cc48e3981f87"
        data-uniqueuserid="user123" 
        data-type="integrated" 
        data-width="auto" 
        data-height="auto">
    </script>
    <form class='maxpayPaymentForm'></form>
    <iframe id='maxpay-hpp-199d5077dd7be9a8313954bcc7d4fe7ec9b005beab2ef7e00932cc48e3981f87'></iframe>
</div>

Parameters of iFrame payment widget

Parameter Description
data-buttontext text of the button
data-name name of your payment application
data-key your personal test public key from general settings
data-signature signature of the payment widget. Information about a signature generation below
data-uniqueuserid merchant’s unique user ID (unique user ID in merchant’s system)
data-type data type - integrated
data-width width of the iframe
data-height height of the iframe

Use additional parameters for sending them on iFrame widget

Parameter Description
data-uniqueTransactionId this parameter allows to assign a value for the transaction and receive it in callback data, if a value doesn’t pass - Maxpay generates this value by itself
data-productPublicId allows to preselect a product for the payment page, the value is Product ID you can find it in Products to sell section
data-email parameter for sending email value
data-firstname user’s first name
data-lastname user’s last name
data-phone parameter for sending phone value
data-address parameter for sending address value
data-city parameter for sending city value
data-country parameter for sending country value
data-zip parameter for sending zip value
data-success_url parameter for sending success redirect url value
data-decline_url parameter for sending decline redirect url value
data-locale parameter for displaying a language on payment page

Redirect

Example of Redirect form:


<form action='https://hpp.maxpay.com/hpp' class='redirect_form' method='post'>
    <input type='hidden' name='key' value='pkTest_67pcq3B5i8N7utM7WRNM6ZGvxFmHE4W9'>
    <input type='hidden' name='signature' value='199d5077dd7be9a8313954bcc7d4fe7ec9b005beab2ef7e00932cc48e3981f87'>
    <input type="hidden" name='uniqueUserId' value='user123'>
    <button type='submit'>Pay</button>
</form>

Parameters of Redirect form

Parameter Description
key your personal test public key from general settings
signature signature of the payment widget. Information about a signature generation below
uniqueuserid merchant’s unique user ID (unique user ID in merchant’s system)

Use additional parameters for sending them on Redirect form

Parameter Description
uniqueTransactionId this parameter allows to assign a value for the transaction and receive it in callback data, if a value doesn’t pass - Maxpay generates this value by itself
productPublicId allows to preselect a product for the payment page, the value is Product ID you can find it in Products to sell section
email parameter for sending email value
firstname user’s first name
lastname user’s last name
phone parameter for sending phone value
address parameter for sending address value
city parameter for sending city value
country parameter for sending country value
zip parameter for sending zip value
success_url parameter for sending success redirect url value
decline_url parameter for sending decline redirect url value
locale parameter for displaying a language on payment page

Callback

Example callback:

{
    "transactionId":"hpp1465480732.893mId1274aId0",
    "reference":"SLFF00000000219E76CQ",
    "uniqueUserId":"testUserId",
    "totalAmount":100,
    "currency":"USD",
    "transactionType":"SALE",
    "status":"success",
    "message":"Transaction processed successfully",
    "code":0,
    "productList":
        [
            {
                "productId":"12345",
                "name":"Demo product",
                "amount":100,
                "currency":"USD" 
            }
        ],
    "checkSum":"78705e06b853d0035a03019e1861c6a96d049798820dfd400e5bf874696d6dea" 
}

Callback values

Description of callback fields

PARAMETER DESCRIPTION
transactionId The unique id of the transaction.
reference Unique reference of the transaction in Maxpay system
uniqueUserId The unique id of the user in your system.
totalAmount Total amount of transaction
currency The currency of transaction. ISO3 currencies.
transactionType The type of the transaction.
status Status of the transaction.
code The response code of the transaction. The detailed list could be found in “response codes” section below.
message An explanation message of the transaction. The detailed list could be found in “response codes” section below.
productList Processed product list(may contain array of products with fields) Each product contain fields:
  • productId
  • name
  • amount
  • currency
checkSum Check sum of callback packet

Callback is received to a merchant when in response Maxpay got the code - 200 and body text - OK. In other cases, callback is not received and Maxpay will try periodically to send callback data. The number of attempts are limited.

Examples below describe different cases with callback data receiving:

HTTP Code Body text Description
200 OK Callback is successfully received
500 OK Callback is not received

Notice all callback values take a part in calculation of the checkSum value, more details at section - HPP checkSum calculation in callback response.


Locale for the payment page

Maxpay provides different languages for the payment page.

Look at available languages below:

Language Variables for different locales
English English is default language or "en-US" for US locale.
Russian "ru-RU" or "ru"
German "de-DE"
French "fr-FR"
Portuguese "pt-PT"
Italian "it-IT"
Spanish "es-ES"
Turkish "tr-TR"
Swedish "sv-SE"
Norwegian "no-NO"
Danish "da-DA"
Finnish "fl-FL"
Dutch "nl-NL"
Irish "en-GA"
Polish "pl-PL"

Let’s look at the sample with French locale.

Type of payment form Code example
Redirect <input type='hidden' name='locale' value='fr-FR'>
Pop Up/iFrame data-locale="fr-FR"

Custom product API

In case you would like to make the product selection on your side you have a possibility to pass custom products and avoid ‘ccreate product’ step on Maxpay’s side. “To make this happen simply send the POST request with the “customproduct” parameter. This parameter should contain the valid array of products.

Type of payment form Code example
Redirect <input type='hidden' name='customproduct' value='[{"productId":"ID01","productType":"fixedProduct","productName":"Demo","currency":"USD","amount":1,"productDescription":"Custom product"}]'>
Pop Up/iFrame data-customproduct='[{"productId":"ID01","productType":"fixedProduct","productName":"Demo","currency":"USD","amount":1,"productDescription":"Custom product"}]'

Custom Fixed Product

Example with custom fixed product for Pop Up/iFrame payment form


    data-customproduct='[{"productId":"ID12345","productType":"fixedProduct","productName":"Demo fixed product","currency":"USD","amount":100,"productDescription":"Custom fixed product"}]'

Example with custom fixed product for Redirect payment form


    <input type='hidden' name='customproduct' value='[{"productId":"ID12345","productType":"fixedProduct","productName":"Demo fixed product","currency":"USD","amount":100,"productDescription":"Custom fixed product"}]'>

Parameters for custom fixed product are provided below:

PARAMETER REQUIRED TYPE DESCRIPTION
productId yes string The product ID.
productName yes string The name of the product. Will be displayed on the payment page.
productType yes string fixedProduct - simple one time product
productDescription no string Description of the product. Will be displayed on the payment page.
currency yes string ISo3 the currency of the product. If currency wasn’t passed, the default “EUR” currency will be applied.
amount yes float The price of the product.
discount no float The amount of discount.
discountType no string Discount could be set in percent of original price or in fixed amount. Applicable only for ‘fixed’ and ‘subscription’ type products. Values:
  • amountOff
  • percentOff

Custom Trial Product

Example with custom trial product for Pop Up/iFrame payment form


    data-customproduct='[{"productId":"ID12345","productType":"trialProduct","productName":"Demo trial product","currency":"USD","amount":100,"productDescription":"Custom trial product","trialLength":1,"trialPeriod":"30D", "postTrialProductId":"ID213"}]'

Example with custom trial product for Redirect payment form


    <input type='hidden' name='customproduct' value='[{"productId":"ID12345","productType":"trialProduct","productName":"Demo trial product","currency":"USD","amount":100,"productDescription":"Custom trial product","trialLength":1,"trialPeriod":"30D", "postTrialProductId":"ID213"}]'>

Parameters for custom trial product are provided below:

Request parameters:

PARAMETER REQUIRED TYPE DESCRIPTION
productId yes string The product ID.
productName yes string The name of the product. Will be displayed on the payment page.
productType yes string trialProduct - special trial product which will transform in the indicated product.
productDescription no string Description of the product. Will be displayed on the payment page.
currency yes string ISo3 the currency of the product. If currency wasn’t passed, the default “EUR” currency will be applied.
amount yes float The price of the product.
discount no float The amount of discount.
discountType no string Discount could be set in percent of original price or in fixed amount. Applicable only for ‘fixed’ and ‘subscription’ type products. Values:
  • amountOff
  • percentOff
trialLength yes int The length of trial product, mandatory for trialProduct type.
trialPeriod yes string The period of trial, mandatory for trialProduct type. Values:
  • 24H;
  • 7D;
  • 30D;
  • 365D.
postTrialProductId yes string The ID of post-trial product, mandatory for trialProduct type. The post-trial product shoul be created in merchant portal.

Custom Subscription Product

Example with custom subscription product for Pop Up/iFrame payment form


    data-customproduct='[{"productId":"ID12345","productType":"subscriptionProduct","productName":"Demo subscription product","currency":"USD","amount":100,"productDescription":"Custom subscription product","subscriptionLength":"1","subscriptionPeriod":"7D","subscriptionEndDate":"1735689600"}]'

Example with custom subscription product for Redirect payment form


    <input type='hidden' name='customproduct' value='[{"productId":"ID12345","productType":"subscriptionProduct","productName":"Demo subscription product","currency":"USD","amount":100,"productDescription":"Custom subscription product","subscriptionLength":"1","subscriptionPeriod":"7D","subscriptionEndDate":"1735689600"}]'>

Parameters for custom subscription product are provided below:

Request parameters:

PARAMETER REQUIRED TYPE DESCRIPTION
productId yes string The product ID.
productName yes string The name of the product. Will be displayed on the payment page.
productType yes string The type of product which merchant is planning to sell. Values:
  • fixedProduct - simple one time product;
  • subscriptionProduct - recurring type product;
  • trialProduct - special trial product which will transform in the indicated product.
productDescription no string Description of the product. Will be displayed on the payment page.
currency yes string ISo3 the currency of the product. If currency wasn’t passed, the default “EUR” currency will be applied.
amount yes float The price of the product.
discount no float The amount of discount.
discountType no string Discount could be set in percent of original price or in fixed amount. Applicable only for ‘fixed’ and ‘subscription’ type products. Values:
  • amountOff
  • percentOff
subscriptionLength yes int The length of subscription product.
subscriptionPeriod yes string The period of subscription. Values:
  • 24H;
  • 7D;
  • 30D;
  • 365D.
subscriptionEndDate yes float The end date of subscription
subscriptionBillingCycles no int Amount of available billing cycles
subscriptionTrialPrice no float The price of subscription’s trial period. This price will be charged only during ‘trialStart’, ‘trialEnd’ indicated periods.
subscriptionTrialStart no float The start date of subscription’s trial price.
subscriptionTrialEnd no float The end date of subscription’s trial price.


Example of callback:

{
    "transactionId":"hpp1465480732.893mId1274aId0",
    "reference":"SLFF00000000219E76CQ",
    "uniqueUserId":"testUserId",
    "totalAmount":100,
    "currency":"USD",
    "transactionType":"SALE",
    "status":"success",
    "message":"Transaction processed successfully",
    "code":0,
    "productList":
        [
            {
                "productId":"12345",
                "name":"Demo custom product",
                "amount":100,
                "currency":"USD" 
            }
        ],
    "checkSum":"78705e06b853d0035a03019e1861c6a96d049798820dfd400e5bf874696d6dea" 
}

Callback values

Description of callback fields

PARAMETER DESCRIPTION
transactionId The unique id of the transaction.
reference Unique reference of the transaction in Maxpay system
uniqueUserId The unique id of the user in your system.
totalAmount Total amount of transaction
currency The currency of transaction. ISO 3 currencies.
transactionType The type of the transaction.
status Status of the transaction.
code The response code of the transaction. The detailed list could be found in “response codes” section below.
message An explanation message of the transaction. The detailed list could be found in “response codes” section below.
productList Processed product list(may contain array of products with fields) Each product contain fields:
  • productId
  • name
  • amount
  • currency
checkSum Check sum of callback packet

Callback is received to a merchant when in response Maxpay got the code - 200 and body text - OK. In other cases, callback is not received and Maxpay will try periodically to send callback data. The number of attempts are limited.

Examples below describe different cases with callback data receiving:

HTTP Code Body text Description
200 OK Callback is successfully received
500 OK Callback is not received

Notice all callback values take a part in calculation of the checkSum value, more details at section - HPP checkSum calculation in callback response.


One click feature

One click feature allows to remember customer’s credit card data for next purchases. Instead of your customers enter credit card data again - one click feature provides an option of selecting a credit card or inputting a new one.

  1. Select the Payment forms section and click to edit the current payment form.
  2. Click on the One click checkbox for activating the feature.
  3. For running the one click feature you need to pass the same values of the email and uniqueuserid which were used for the initial payment.


Rebilling feature

Rebilling feature allows to implement rebilling logic on merchant’s side. This feature gives merchants the opportunity to manage rebilling policy on their side and build the billing system as they want.

Example of callback with billToken value:

{
    "transactionId":"hpp1465480732.893mId1274aId0",
    "reference":"SLFF00000000219E76CQ",
    "uniqueUserId":"my-user-123",
    "totalAmount":29.99,
    "currency":"USD",
    "transactionType":"SALE",
    "status":"success",
    "message":"Transaction processed successfully",
    "code":"0",
    "productList": 
        [
            {
                "productId":"my-product-123",
                "name":"Monthly product",
                "amount":29.99,
                "currency":"USD"
            }
        ],
    "billToken":"9293f4vc-47fq-45d4-9eh2-08d29te9d899",
    "checkSum":"78705e06b853d0035a03019e1861c6a96d049798820dfd400e5bf874696d6dea"
}
  1. Select the Payment forms section and click to edit the current payment form.
  2. Click on the Rebilling checkbox for activating the feature.
  3. For rebilling payment - use the value of the billToken which you receive in callback data.

Notice : If customer doesn’t select confirmation checkbox - merchant won’t receive billToken value.

Rebilling API

Rebilling API is the unique way to charge your customers based on your own schedule using credit card tokens. This feature could be activated in the widget’s settings of your application. Please note that if the feature is activated, an additional checkbox will appear on your payment form. If your customer ticks the checkbox, the token will be sent to you in the callback response after the customer makes payment. You can use the parameters below to rebill your customer after receiving the payment token.

Rebilling request with fixed product

Example of fixed product request:

<?php
    array (
        'publicKey' => 'pkTest_56137fd80ffc4a639cf91e81941d1f51',
        'signature' => 'bac1c2876f98149d225da91c85956ece1d695809d2a32fff81459c04ff77580b',
        'rebillToken' => '575955d2-5818-4806-8498-7855f3666259',
        'productId' => 'prodID00001',
        'uniqueUserId' => 'userId0001',
        'amount' => 29.99,
        'productName' => 'Rebilling request with fixed product',
        'currency' => 'USD',
        'productType' => 'fixedProduct',
        'cardHolderName' => 'John Doe',
        'firstName' => 'John',
        'lastName' => 'Doe',
        'email' => 'johndoe@test.com',
        'country' => 'USA',
        'city' => 'New York',
        'address' => 'Fake street 12',
        'zip' => '12100',
        'phone' => '35422211190'
    )
?>

Parameters for rebilling fixed product are provided below:

Request URL: https://hpp.maxpay.com/api/rebilling
Request method: POST.

Request parameters:

PARAMETER REQUIRED DESCRIPTION
publicKey yes The public key of the application. Could be found in the general settings of the application.
signature yes Signature of the payment page. The default value of the signature.
uniqueUserId yes The unique id of the user in your system.
rebillToken yes The unique payment token which is received in callback data after a customer made the initial payment.
productId yes A unique ID of the product. Could be found in the “Product” settings of the application. In case product is created in Maxpay merchant portal you can simply send the ‘productId’, all other parameters Maxpay will handle for you. In case you’re sending the product from your database you should pass the product parameters below.
productName yes Name of the product.
productDescription optional Description of the product.
productType yes fixedProduct - simple one time product
currency optional Default EUR string. ISO3 currencies.
amount yes The price of the product.
discount optional The discount for the product. Applicable only for ‘fixed’ and ‘subscription’ type products.
discountType required if ‘discount’ was set up. Discount could be set in percent of original price or in fixed amount. Applicable only for ‘fixed’ and ‘subscription’ type products. Values:
  • amountOff;
  • percentOff.
cardHolderName optional Name of the carholder.
firstName optional The first name of a customer.
lastName optional The first name of a customer.
email optional Customer’s email address.
country optional Customer’s country name.
city optional Customer’s city name.
address optional Customer’s address.
zip optional Customer’s zip code.
phone optional Customer’s phone number.

Notice : In case that product is created in Maxpay merchant portal you can simply send: publicKey , signature, uniqueUserId, rebillToken, productId - all other parameters Maxpay will handle for you. In case you’re sending the fixed product from your database you should pass the product parameters which are described above.

Rebilling request with trial product

Example of trial product request:

<?php
    array (
        'publicKey' => 'pkTest_56137fd80ffc4a639cf91e81941d1f51',
        'signature' => 'bac1c2876f98149d225da91c85956ece1d695809d2a32fff81459c04ff77580b',
        'rebillToken' => '575955d2-5818-4806-8498-7855f3666259',
        'productId' => 'p_00002',
        'uniqueUserId' => 'userID2101',
        'amount' => 100,
        'productName' => 'Rebilling request with trial product',
        'currency' => 'USD',
        'productType' => 'trialProduct',
        'cardHolderName' => 'John Doe',
        'firstName' => 'John',
        'lastName' => 'Doe',
        'email' => 'johndoe@test.com',
        'country' => 'USA',
        'city' => 'New York',
        'address' => 'Fake street 12',
        'zip' => '12100',
        'phone' => '35422211190'
    )
?>

Parameters for rebilling trial product are provided below:

Request URL: https://hpp.maxpay.com/api/rebilling
Request method: POST.

Request parameters:

PARAMETER REQUIRED DESCRIPTION
publicKey yes The public key of the application. Could be found in the general settings of the application.
signature yes Signature of the payment page. The default value of the signature.
uniqueUserId yes The unique id of the user in your system.
rebillToken yes The unique payment token which is received in callback data after a customer made the initial payment.
productId yes A unique ID of the product. Could be found in the “Product” settings of the application. In case product is created in Maxpay merchant portal you can simply send the ‘productId’, all other parameters Maxpay will handle for you. In case you’re sending the product from your database you should pass the product parameters below.
productName yes The name of the product.
productDescription optional The description of the product.
productType yes trialProduct - recurring type product.
currency optional Default EUR string. ISO3 currencies.
amount yes The price of the product.
discount optional The discount for the product. Applicable only for ‘fixed’ and ‘subscription’ type products.
discountType required if ‘discount’ was set up. Discount could be set in percent of original price or in fixed amount. Applicable only for ‘fixed’ and ‘subscription’ type products. Values:
  • amountOff;
  • percentOff.
trialLength yes Applicable only if the product type is ‘trialProduct’ numeric. The length of the trial product.
trialPeriod yes Applicable only if the product type is ‘trialProduct’ string. The period of trial. Values:
  • 24H;
  • 7D;
  • 30D;
  • 365D.
postTrialProductId yes Applicable only if the product type is ‘trialProduct’ string. The following product will be charged after the trial product will expire . Note: In order to use post trial product it should be created in maxpay merchant portal.
cardHolderName optional Name of the carholder.
firstName optional The first name of a customer.
lastName optional The first name of a customer.
email optional Customer’s email address.
country optional Customer’s country name.
city optional Customer’s city name.
address optional Customer’s address.
zip optional Customer’s zip code.
phone optional Customer’s phone number.

Notice : For quick request just send: publicKey , signature, uniqueUserId, rebillToken, productId - all other parameters Maxpay will handle for you. In case you’re sending the trial product from your database you should pass the product parameters which are described above.

Rebilling request with subscription product

Example of subscription product request:

<?php
    array (
        'publicKey' => 'pkTest_56137fd80ffc4a639cf91e81941d1f51',
        'signature' => 'bac1c2876f98149d225da91c85956ece1d695809d2a32fff81459c04ff77580b',
        'rebillToken' => '575955d2-5818-4806-8498-7855f3666259',
        'productId' => 'prodID0003',
        'uniqueUserId' => 'userID0000213',
        'amount' => 59.90,
        'productName' => 'Rebilling request with subscription product',
        'currency' => 'USD',
        'productType' => 'subscriptionProduct',
        'subscriptionLength' => 1,
        'subscriptionPeriod' => '30D',
        'subscriptionTrialPrice' => 19.99,
        'subscriptionTrialStart' => 1507818328,
        'subscriptionTrialEnd' => 1507818408,
        'subscriptionEndDate' => 1507819408,
        'cardHolderName' => 'John Doe',
        'firstName' => 'John',
        'lastName' => 'Doe',
        'email' => 'johndoe@test.com',
        'country' => 'USA',
        'city' => 'New York',
        'address' => 'Fake street 12',
        'zip' => '12100',
        'phone' => '35422211190'
    )
?>

Parameters for rebilling subscription product are provided below:

Request URL: https://hpp.maxpay.com/api/rebilling
Request method: POST.

Request parameters:

PARAMETER REQUIRED DESCRIPTION
publicKey yes The public key of the application. Could be found in the general settings of the application.
signature yes Signature of the payment page. The default value of the signature.
uniqueUserId yes The unique id of the user in your system.
rebillToken yes The unique payment token which is received in callback data after a customer made the initial payment.
productId yes A unique ID of the product. Could be found in the “Product” settings of the application. In case product is created in Maxpay merchant portal you can simply send the ‘productId’, all other parameters Maxpay will handle for you. In case you’re sending the product from your database you should pass the product parameters below.
productName yes The name of the product.
productDescription optional The description of the product.
productType yes subscriptionProduct - recurring type product.
currency optional Default EUR string. ISO3 currencies.
amount yes The price of the product.
discount optional The discount for the product. Applicable only for ‘fixed’ and ‘subscription’ type products.
discountType required if ‘discount’ was set up. Discount could be set in percent of original price or in fixed amount. Applicable only for ‘fixed’ and ‘subscription’ type products. Values:
  • amountOff;
  • percentOff.
subscriptionLength yes Applicable only if the product type is ‘subscriptionProduct’ numeric. The length of the subscription product.
subscriptionPeriod yes Applicable only if the product type is ‘subscriptionProduct’ string. The period of subscription. Values:
  • 24H;
  • 7D;
  • 30D;
  • 365D.
subscriptionEndDate yes Applicable only if the product type is ‘subscriptionProduct’ float. The end date of the subscription. After this date end user won’t be charged again.
subscriptionTrialPrice optional If the product type is ‘subscriptionProduct’ float. The price of subscription’s trial period. This price will be charged only during ‘trialStart’, ‘trialEnd’ indicated periods.
subscriptionTrialStart optional Applicable only if the product type is ‘subscriptionProduct’ float, micro time ‘true’.
subscriptionTrialEnd optional Applicable only if the product type is ‘subscriptionProduct’ float, micro time ‘true’.
cardHolderName optional Name of the carholder.
firstName optional The first name of a customer.
lastName optional The first name of a customer.
email optional Customer’s email address.
country optional Customer’s country name.
city optional Customer’s city name.
address optional Customer’s address.
zip optional Customer’s zip code.
phone optional Customer’s phone number.

Notice : For quick request just send: publicKey , signature, uniqueUserId, rebillToken, productId - all other parameters Maxpay will handle for you. In case you’re sending the subscription product from your database you should pass the product parameters which are described above.

Example callback:

{
  "requestSuccess": true,
  "payload": {
    "transactionId": "hppR1495179676.5908mId3126aId1335",
    "reference":"SLFF00000000219E76CQ",
    "uniqueUserId": "auto_5vFx6yUvR",
    "totalAmount": 49,
    "currency": "USD",
    "transactionType": "SALE",
    "status": "success",
    "message": "Transaction processed successfully",
    "code": 0,
    "productList": [
      {
        "productId": "p_901ad59b07",
        "name": "Demo product",
        "amount": 49,
        "currency": "USD"
      }
    ],
    "checkSum": "0834aeaaf25ab42168b451eabd9f4c2c450d39d3db57d8a6c939a15000da3e91"
  }
}

Callback values

Description of callback fields

PARAMETER DESCRIPTION
requestSuccess True - if request processed successfully. False - if request is incorrect.
transactionId The unique id of the transaction.
reference Unique reference of the transaction in Maxpay system
uniqueUserId The unique id of the user in your system.
totalAmount Total amount of transaction
currency The currency of transaction. ISO3 currencies.
transactionType The type of the transaction.
status Status of the transaction.
code The response code of the transaction. The detailed list could be found in “response codes” section below.
message An explanation message of the transaction. The detailed list could be found in “response codes” section below.
productList Processed product list(may contain array of products with fields) Each product contain fields:
  • productId
  • name
  • amount
  • currency
checkSum Check sum of callback packet

Callback is received to a merchant when in response Maxpay got the code - 200 and body text - OK. In other cases, callback is not received and Maxpay will try periodically to send callback data. The number of attempts are limited.

Examples below describe different cases with callback data receiving:

HTTP Code Body text Description
200 OK Callback is successfully received
500 OK Callback is not received

*Notice all callback values take a part in calculation of the checkSum value, more details at section - HPP checkSum calculation in callback response.


Cancel subscription API

Example request:

<?php

array (
  'publicKey' => 'pkLive_5617970296ec43c48a2b5446d',
  'transactionId'=> 'hpp1467893228.4626mId571aId0',
  'uniqueUserId' => 'subscriptionfull',
  'signature' => '039539689c72f018ab7beee0389f935f'
)

?>

Cancel subscription API is the way to unsubscribe your customers from rebilling API. This feature could be switched off in the widget’s settings of your application. Also you can use the parameters below to cancel subscription.

Request method: POST.
Request URL: https://hpp.maxpay.com/api/cancel

Request parameters:

PARAMETER REQUIRED DESCRIPTION
publicKey yes The public key of the application. Could be found in the general settings of the application.
transactionId yes The unique id of the transaction.
uniqueUserId yes The unique id of the user in your system.
signature yes Signature of the payment page. Calculation is described below.

Example callback:

{
  "requestSuccess": true,
  "payload": {
    "transactionId": "hppR1485179676.5908mId3126aId1225",
    "message": "Subscription products successfully stopped.",
    "status": "Success",
    "productList": [
      {
        "productId": "p_901ad59",
        "name": "Demo product",
        "amount": 49,
        "currency": "USD"
      }
    ],
    "checkSum": "01b4dbfbcf9e9b84c6f7c46fa88d9857ae1575bb6b37eb88c61061adf174c389"
  }
}

Description of callback fields:

PARAMETER DESCRIPTION
requestSuccess True - if request processed successfully. False - if request is incorrect.
transactionId The unique id of the transaction.
reference Unique reference of the transaction in Maxpay system
message An explanation message of the transaction. The detailed list could be found in “response codes” section below.
status Status of the transaction.
productList Processed product list(may contain array of products with fields) Each product contain fields:
  • productId
  • name
  • amount
  • currency
productId The id of the product.
name The name of the product.
amount The price of the product.
currency The currency of the product. ISO 3 currencies.
checkSum Check sum of callback packet

Callback is received to a merchant when in response Maxpay got the code - 200 and body text - OK. In other cases, callback is not received and Maxpay will try periodically to send callback data. The number of attempts are limited.

Examples below describe different cases with callback data receiving:

HTTP Code Body text Description
200 OK Callback is successfully received
500 OK Callback is not received

Notice all callback values take a part in calculation of the checkSum value, more details at section - HPP checkSum calculation in callback response.


API for canceling post-trial product

API for canceling post-trial product allows to cancel post-trail product via request.

Example request:

<?php

array (
  'publicKey' => 'pkLive_5617970296ec43c48a2b5776d',
  'transactionId'=> 'hpp1501652396.4483mId3125aId1281',
  'signature' => '039539689c72f018ab7beee0389f935f'
)

?>

Request URL: https://hpp.maxpay.com/api/cancel_post_trial
Request method: POST.

Request parameters:

PARAMETER REQUIRED DESCRIPTION
publicKey yes The public key of the application. Could be found in the general settings of the application.
transactionId yes The unique id of the initial transaction.
signature yes Maxpay signature. Calculation is described below.

Example callback:

{
    "requestSuccess": true,
    "payload": {
        "transactionId": "hpp1501652396.4483mId3125aId1281",
        "message": "Post trial canceled for user `auto_2E6LwT8NIQbK1yZZ`",
        "status": "Success",
        "checkSum": "f40e8d4896b2cdb3d9097ad6476f851b2ab5ba18db2f19b6d28c355ca7734f80"
    }
}

Description of callback fields:

PARAMETER DESCRIPTION
transactionId The unique id of the transaction.
message An explanation message of the transaction. The detailed list could be found in “response codes” the section is situated below.
status Status of the transaction.
checkSum Check sum of callback packet

Example callback on repeated request:

{
    "requestSuccess": false,
    "description": "Post-trial 235 is already cancelled"
}

Refund API

Example request:

<?php

array (
  'publicKey' => 'pkLive_5617970296ec43c48a2b5446d',
  'transactionId'=> 'hpp1467893228.4626mId571aId0',
  'signature' => '039539489c72f018ab7baee0389f735f'
)

?>

Refund API allows to issue refunds on your side. Look at the parameters below to send a refund request.

Request URL: https://hpp.maxpay.com/api/refund
Request method: POST.

Request parameters:

PARAMETER REQUIRED DESCRIPTION
publicKey yes The public key of the application. Could be found in the general settings of the application.
transactionId yes The unique id of the transaction.
signature yes Signature of the payment page. Calculation is described below.

Example callback:

{
    "requestSuccess":true,
    "payload":{
        "message":"Refund processed successfully",
        "status":"Success",
        "transactionId":"hppAR1495096440.3937mId3126aId1335",
        "checkSum":"8237d19969c61517c155879c8cf5ce292ce39d948c6bba94364d8c658e4a7f26"
        }
    }

Description of callback fields:

PARAMETER DESCRIPTION
requestSuccess True - if request processed successfully. False - if request is incorrect.
payload Array with data of the transaction.
message An explanation message of the transaction. The detailed list could be found in “response codes” section below.
status Status of the transaction.
transactionId Unique ID of the transaction.
checkSum Check sum of callback packet

Callback is received to a merchant when in response Maxpay got the code - 200 and body text - OK. In other cases, callback is not received and Maxpay will try periodically to send callback data. The number of attempts are limited.

Examples below describe different cases with callback data receiving:

HTTP Code Body text Description
200 OK Callback is successfully received
500 OK Callback is not received

Notice all callback values take a part in calculation of the checkSum parameter, more details at section - HPP checkSum calculation in callback response.


Maxpay.js

The functions below will help you to manipulate with the javascript of payment page and the products created on Maxpay’s side:

HPP signature calculation

When you using Custom product API or additional parameters the process of creating a signature can be resolved in few ways:

1) Using Maxpay GitHub library, which allows you to shape integration code with different parameters and not think about the signature because the library can sign the whole form itself.

2) If you would like to calculate the value of a payment form signature by your own, use the description of the algorithm below:

Sample form for signature calculation


<form method="post" action="https://hpp.maxpay.com/hpp">
    <input type="hidden" name="key" value="pkTest_c4tgzRjQBO4Fa4d7f2OoJkIutFMGiCCC">
    <input type="hidden" name="customproduct" value="[{'productId':'1','productType':'fixedProduct','productName':'Product name','currency':'USD','amount':100}]">
    <input type="hidden" name="signature" value="put_a_signature_value_here">
    <input type="submit" name="Pay" value="Pay">
</form>

The algorithm is provided below:

Example of a signature calculation based on the form above:


<?php

//key - it's Public key from merchant portal (my.maxpay.com -> Payment pages -> General -> API keys).
//The last parameter is Private key from merchant portal (my.maxpay.com -> Payment pages -> General -> API keys).

$resulting = strtolower('customproduct=[{“productId”:“1”,“productType”:“fixedProduct”,“productName”:“Product name”,“currency”:“usd”,“amount”:100}]|key=pkTest_c4tgzRjQBO4Fa4d7f2OoJkIutFMGiCCC|skTest_aKuKHhan1arfwrYBXSUja46ax4qrA111’);
$signature = hash('sha256', $resulting);

?>

Also, take a look at our sample on GitHub. This sample using the class SignatureHelper.

The full logic are available at the link GitHub sample code

HPP checkSum calculation in callback response

PHP algorithm below shows the calculation logic of “checkSum”:


<?php
    $callbackData = array (
        'transactionId' => 'hpp1462257324.5236mId548aId9',
        'reference' => 'SLFF00000000219E76CQ'
        'uniqueUserId' => 'myUserId',
        'totalAmount' => 101,
        'currency' => 'USD',
        'transactionType' => 'SALE',
        'status' => 'success',
        'message' => 'Transaction processed successfully',
        'code' => 0,
        'productList' =>
            array (
                0 =>
                    array (
                        'productId' => 'myProducId2',
                        'name' => 'goods 2',
                        'amount' => 100,
                        'currency' => 'USD',
                    ),
                1 =>
                    array (
                        'productId' => 'myProducId1',
                        'name' => 'goods 1',
                        'amount' => 1,
                        'currency' => 'USD',
                    ),
            ),
        'billToken' => '569ded06-c1c0-4ecb-9b9c-59c1630f6969',
        'customParameters' =>
            array (
                'custom_param1' => 'param value 3',
                'custom_param2' => 'param value 2',
            ),
        'checkSum' => '166ad6f43ab2bcedda422433cb5bf34efd75715185f226bc9720de53ee70a079',
    );
?>

If you need to calculate and compare the value checkSum callback, use the algorithm described below:

Make notice, that all callback values take a part in calculation of the checkSum parameter.

For nested arrays, use the following algorithm to form the key name in a line:

For example, find the formation of the key for the subarray productList, converted to a line, it will be as follows:

If fully translate callback shown in the example into the line we get:

API libraries

For hosted payment page integration you can use our has library on GitHub, where you can find:


Also, Module for Magento 1.9 is available on GitHub

Test mode

Before you are going live, Maxpay team should make sure that your flow works good. Influencing factors on switching from test mode to live mode: 1. Rendering payment form. 2. Callback handling.

Be advised, if you send a phone number trough the payment form you should send it with “+” symbol. If you don’t send a phone number with “+” symbol you will receive a declined payment with reason - General bank decline. This option is available only for test mode and allows to get declined payments.

Test credit cards

Card brand Supporting flow Card number CVV Expiry date
Visa 2D 4111111111111111 123 [3 digits random] MM - [from 01 to 12]; YYYY- 2020 or greater
Mastercard 2D 5555555555554444 123 [3 digits random] MM - [from 01 to 12]; YYYY- 2020 or greater
Visa 3D Secure 4012000300001003 123 [3 digits random] MM - [from 01 to 12]; YYYY- 2020 or greater
Mastercard 3D Secure 5191330000004415 123 [3 digits random] MM - [from 01 to 12]; YYYY- 2020 or greater

Notice: test credit cards are available only for test mode.

Going to live

In order to switch the processing to live mode simply send us your integration for review by clicking on ‘send for review’ button in your ‘application’ section. After that, you should provide a value of live callback url:

  1. Click on the button “Account settings” (upper-right corner of merchant portal).
  2. Select “Firewall” section.
  3. Click on the button “Send new request”.
  4. Input a callback url value in “The callback url” string.
  5. Click on the button “Save”.

The production callback url should be whitelisted on Maxpay side. Necessarily with https protocol, SSL generated by yourself is not valid. Our Integration Team will review your application carefully and get back to you as soon as possible.

Host to host API

Overview

Maxpay gateway workflow is based on the type of Transaction made. Gateway supports 9 types of transaction requests:

Other definitions:

ECI VALUES

MasterCard ECI value VISA ECI value Description
2 5 Card holder was successfully authenticated
1 6 Authentication could not be completed but a proof of authentication attempt was provided – card is not enrolled*
7 7 Card Holder authentication failed/ Authentication could not be completed due to technical or other problems

*There are two possibilities for this stage: the Issuer bank offered the Customer to enroll online and the Customer declined, or the bank did not make the offer.

Access to Maxpay Gateway API

Maxpay live and test host to host API could be reached by the following URLs:

Web Service URL
Live Maxpay Gateway API Service https://gateway.maxpay.com/api/cc
Test Maxpay Gateway API Service https://gateway-sandbox.maxpay.com/api/cc
Gateway API Reference Help https://gateway.maxpay.com/help/cc

Maxpay Gateway supports various transaction flow scenarios, but this document will focus only on the general recommended scenario, described below.

  1. After selecting goods and services, the cardholder presses ‘Buy’ or an equivalent button and proceeds to a page where he can enter or modify delivery information and the payment method. Payment method information may offer various payment methods, like ‘Pay by credit card’ or a similar option. This option should not include card number, expiry date, CVV2/CVC2 or any other card related sensitive information. Because of security risks involved, merchant system should avoid requesting and storing credit card information on the merchant server.

  2. If cardholder selects ‘Pay by credit card’ option, a merchant system must prepare authorization request fields and redirect the cardholder to an ‘Enter credit card information’ page on Maxpay Gateway URL. Alternatively, the merchant system itself may present this page directly to cardholder. This form shall contain all card entry fields and visible/hidden fields relating to the order and merchant as required by the authorization request format.

  3. After receiving the filled-in form by using AUTH/AUTH3D request, Maxpay Gateway validates request information. If the request fails the validation, Gateway sends an error response back to merchant system.

  4. If the provided card number belongs to a card range with a defined cardholder authentication method (AUTH3D), Gateway calls the corresponding authentication module (3D Secure) which performs protocol-specific processing. If cardholder authentication is unsuccessful, Maxpay Gateway returns an error message to the merchant system.

  5. Maxpay Gateway sends an authorization request to the Issuer bank. Upon authorization reception, Gateway prepares and sends a transaction response back to the merchant system. The transaction response contains no credit card information or contains the card number in blinded form only. Gateway sends response messages to the merchant system.

  6. If authorization is successful, the response message will contain the Reference number field, to be used by the merchant system so it can complete or reverse the obtained authorization without the credit card information.

  7. After receiving the online transaction response, the merchant system starts delivery of ordered goods and/or services to the cardholder. At this point, the requested amount is blocked on the cardholder account.

  8. If a merchant would like to make authentication and sale process using one transaction at once, it can choose SALE/SALE3D request which includes AUTH/AUTH3D and SALE transactions consistently.

  9. When the merchant has delivered the goods and services to cardholder, the merchant system sends a SETTLE request (depends on the chosen transaction flow) to complete transaction directly to the Maxpay Gateway using a reference number to refer to the authorization transaction with its corresponding credit card information. The transaction request should include a message authentication code field for verifying the message’s identity.

  10. Maxpay Gateway validates the incoming message and requests financial completion of the transaction from the bank. At this point, the transaction amount is debited from the cardholder account and the merchant account is credited with the appropriate amount. Gateway sends a response back to merchant system within the response document.

  11. If the merchant is unable to fulfill the cardholder order or if the cardholder cancels the order at a stage allowed by the merchant, the merchant system must send a VOID request to cancel the pending transaction or REFUND request for completed transaction. The merchant system sends this message directly to the Maxpay Gateway API.

  12. Gateway validates the incoming message and cancels the pending transaction on the Maxpay Gateway side or requesting to refund for completed transaction from the bank. This may involve transferring funds from the merchant account back to the cardholder account. Gateway sends a reply to the merchant system within the response document.

    On any steps merchant can check the transaction status sending CHECK request to Maxpay Gateway API.

  13. To encrypt a payment card data merchant can send TOKENIZE request to Maxpay Gateway API to encrypt credit card number and get the tokenized data.

Integration flow

Please, follow for the next flow:

Test mode

Before you are going live, Maxpay team should make sure that your flow works good. Influencing factors on switching from test mode to live mode:

Notice: Be advised, for a phone number you should also add “+” symbol. If you don’t send a phone number value with “+” symbol you will receive a declined payment with reason - General bank decline. This option is available only for test mode and allows to get declined payments.

Test credit cards

Card brand Supporting flow Card number CVV Expiry date
Visa 2D 4111111111111111 123 [3 digits random] MM - [from 01 to 12]; YYYY- 2020 or greater
Mastercard 2D 5555555555554444 123 [3 digits random] MM - [from 01 to 12]; YYYY- 2020 or greater
Visa 3D Secure 4012000300001003 123 [3 digits random] MM - [from 01 to 12]; YYYY- 2020 or greater
Mastercard 3D Secure 5191330000004415 123 [3 digits random] MM - [from 01 to 12]; YYYY- 2020 or greater

Please notice, that test credit cards are available only for test mode.

AUTH3D transaction

Sample code of AUTH3D transaction request:

“Content-type: application/json” –data

{
    "api_version":1,
    "merchant_account":"your_merchant_account",
    "merchant_password":"account_password",
    "transaction_unique_id":"auth3d_request001",
    "transaction_type":"AUTH3D",
    "amount":19.99,
    "currency":"USD",
    "card_number":"4012000300001003",
    "card_exp_month":"05",
    "card_exp_year":"2016",
    "cvv": "111",
    "first_name":"John",
    "last_name":"Doe",
    "card_holder":"John Doe",
    "address":"123 Street name.",
    "city":"City Name",
    "zip":"02001",
    "country":"USA",
    "user_phone":"123456789",
    "user_email":"test@test.com",
    "user_ip":"127.0.0.1"
}

Purpose: Interface is used to check ability to follow 3DS flow for the card. The ECI code will be returned to explain the reason (for example in negative case).

In the positive case Merchant can run SALE transaction with pares and reference fields which should be Required transmitted in this type of request.

The possible flow of using AUTH3D and SALE (full cc) transactions is displayed below.

Request parameters:

Parameter Name Type Required Rules Example
api_version float/string yes maxLength: {max: 32} 1
merchant_account string yes minLength: {min: 6}, maxLength: {max: 32} MyAccount_MP_TRX
merchant_password string yes minLength: {min: 6}, maxLength: {max: 32 } Password
transaction_unique_id string yes minLength: {min: 6}, maxLength: {max: 32} trxId1234567890auth3D
transaction_type string yes validTransType, enum: { values: [”AUTH3D”]} AUTH3D
amount float yes float, maxLength: [0 - 9999999999.99] 9.99
currency string yes length: {size: 3}, ISO 4217 (alfa-3) EUR
card_number string yes minLength: {min: 13}, maxLength: {max: 19} only digits, Luhn algorithm 4864369454425300
card_exp_month string yes length: {size: 2}, only digits 05
card_exp_year string yes length: {size: 4}, only digits 2020
cvv string yes minLength: {min: 3}, maxLength: { max: 4 }, only digits 911
first_name string yes minLength: {min: 1}, maxLength: {max: 32} John
last_name string yes minLength: {min: 1}, maxLength: {max: 32} Doe
card_holder string yes minLength: {min: 2}, maxLength: {max: 32} John Doe
address string yes minLength: {min: 2} maxLength: {max: 32} 123 Street
city string yes minLength: { min: 2}, maxLength: {max: 32} New York
state string yes minLength: { min: 1}, maxLength: {max: 32} New York
zip string yes minLength: { min: 2 }, maxLength: {max: 10} 12100
country string yes minLength: { min: 2 }, maxLength: { max: 3 }, ISO 3166-1 alpha-3 USA
user_phone string yes minLength: {min: 7 }, maxLength: { max: 15 } +1-202-555-0000
user_ email string yes minLength: { min: 6 }, maxLength: { max: 255 }, valid email johndoe@test.com
user_ip string yes Ipv4Address 127.0.0.1
merchant_user_id string no maxLength: { max: 32 } UserId1200021
merchant_domain_name string no maxLength: { max: 255 } merchant-site.com
merchant_affiliate_id string no maxLength: { max: 255 } AF_id_7101
merchant_product_name string no maxLength: { max: 255 } Software
descriptor_merchant string no maxLength: { max: 255 } merchant-descriptor.com
descriptor_phone string no maxLength: { max: 255 } 180012345678

Sample code of AUTH3D response in JSON format:

{
  "api_version": 1,
  "merchant_account": "your_merchant_account",
  "sessionid": "81g47d-7avb-59103914-14be75ef73f-136e",
  "transaction_unique_id": "auth3d_request001",
  "token": "5814f79a-c8fc-40c2-8161-4e0u68cc13ed",
  "reference": "A3FF000000439730A8E",
  "timestamp": 1494235313,
  "authcode": "",
  "pareq": "eyJyZWZlcmVuY2UiOiJBM0ZGMDAwMDAwMDM5NzMwQTgwRVhYMDEiLCJ0aW1lIjoxE0LjU1NTh9",
  "acs_url": "https://callback.maxpay.com/emitent/authentication",
  "eci": 5,
  "status": "success",
  "code": 0,
  "message": "Transaction processed successfully"
}

Response parameters:

Parameter Name Type Required Rules Example
api_version float yes maxLength: { max: 32 } 1
merchant_account string yes minLength: { min: 6 }, maxLength: { max: 32 } Testshop.com
sessionid string yes maxLength: { max: 36 } 53ec668b-c838-44b8-86f2-5c678ae9e3fc
transaction_unique_id string yes maxLength: { max: 32 }, minLength: { min: 1 } NwAkrkcPAmEcGzghnBwMeDRpXAPFsINg
token string yes length: { size: 36 } 14848ff0308f8a396041ddde45de5f8ffffa
reference string yes length: { size: 20 } ATFF1235432423
timestamp string yes unix timestamp 1408001694
authcode string yes maxLength: { max: 24 } 1111513
pareq string no maxLength: { max: 65535 } eJxVUctuwjAQ/JWIK1LsvAqNNpZS
acs_url string no maxLength: { max: 255 } https://maxpay.com:9443/PIT/ATS
eci numeric no { 1, 2, 5, 6, 7 } 7
status string yes { SUCCESS, DECLINE, ERROR } SUCCESS
code float yes Returns response code for the transaction Response codes table
message string yes Returns explanation of the response code Response message table

Example of redirect form after AUTH3D:


    <form id="acsform" method="POST" action="<AcsUrl>">
        <input name="PaReq" type="hidden" value="<PaReq>">
        <input name="TermUrl" type="hidden" value="<TermUrl>">
        <input name="MD" type="hidden" value="">
    </form>
    <script type="text/javascript">
        document.getElementById('acsform').submit();
    </script>

If merchant receives a successful response after AUTH3D request the next action is to route a customer for 3D Secure finishing. Parameters of the redirect form are provided below:

Parameter Description
AcsUrl Access Control Server url - url to re-direct the card holder
PaReq Payment authentication request - shows if card is enrolled
TermUrl URL to re-direct the card holder back to your website, also merchant receives PARes value on the TermUrl. Payment Authentication Response (PARes) which is generated by the Issuer, and contains information about the result of the check.

Notice: Supporting of this transaction type depends on acquirer side. Please, clarify the information before implementation of this transaction type. After the AUTH3D transaction has been processed a merchant depending on business requirements has ability but not forced to send the following transactons:

AUTH3D (by token) transaction

Sample code of AUTH3D (by token) request:

“Content-type: application/json” –data

{
    "api_version":1,
    "merchant_account":"your_merchant_account",
    "merchant_password":"account_password",
    "transaction_unique_id":"auth3d_token001",
    "transaction_type":"AUTH3D",
    "amount":19.99,
    "currency":"USD",
    "first_name":"John",
    "last_name":"Doe",
    "card_holder":"John Doe",
    "address":"123 Street name.",
    "city":"City Name",
    "zip":"02001",
    "country":"USA",
    "user_phone":"123456789",
    "user_email":"test@test.com",
    "user_ip":"127.0.0.1",
    "token":"55a28a26-92e8-4026-bdc8-2e2f58a0e038"
}

Purpose: Interface is used to check ability to follow 3DS flow for the card by billing token. In the positive case Merchant can run SALE request. In the negative case ECI code will be returned to explain the reason.

Request parameters:

Parameter Name Type Required Rules Example
api_version float/string yes maxLength: {max: 32} 1
merchant_account string yes minLength: {min: 6}, maxLength: {max: 32} MyAccount_MP_TRX
merchant_password string yes minLength: {min: 6}, maxLength: {max: 32 } Password
transaction_unique_id string yes minLength: {min: 6}, maxLength: {max: 32} trxId1234567890auth3D
transaction_type string yes validTransType, enum: { values: [”AUTH3D”]} AUTH3D
amount float yes float, maxLength: [0 - 9999999999.99] 9.99
currency string yes length: {size: 3}, ISO 4217 (alfa-3) EUR
first_name string yes minLength: {min: 1}, maxLength: {max: 32} John
last_name string yes minLength: {min: 1}, maxLength: {max: 32} Doe
card_holder string yes minLength: {min: 2}, maxLength: {max: 32} John Doe
address string yes minLength: {min: 2} maxLength: {max: 32} 123 Street
city string yes minLength: { min: 2}, maxLength: {max: 32} New York
state string yes minLength: { min: 1}, maxLength: {max: 32} New York
zip string yes minLength: { min: 2 }, maxLength: {max: 10} 12100
country string yes minLength: { min: 2 }, maxLength: { max: 3 }, ISO 3166-1 alpha-3 USA
user_phone string yes minLength: {min: 7 }, maxLength: { max: 15 } +1-202-555-0000
user_ email string yes minLength: { min: 6 }, maxLength: { max: 255 }, valid email johndoe@test.com
user_ip string yes Ipv4Address 127.0.0.1
merchant_user_id string no maxLength: { max: 32 } UserId1200021
merchant_domain_name string no maxLength: { max: 255 } merchant-site.com
merchant_affiliate_id string no maxLength: { max: 255 } AF_id_7101
merchant_product_name string no maxLength: { max: 255 } Software
descriptor_merchant string no maxLength: { max: 255 } merchant-descriptor.com
descriptor_phone string no maxLength: { max: 255 } 180012345678
token string yes length: { size: 36 } 5524fa52-75d8-4c7a-84ec-039d3097ab6f

Sample code of AUTH3D (by token) response in JSON format:

{
  "api_version": 1,
  "merchant_account": "your_merchant_account",
  "sessionid": "81g47d-7avb-59103914-14be75ef73f-136e",
  "transaction_unique_id": "auth3d_token001",
  "token": "5814f79a-c8fc-40c2-8161-4e0u68cc13ed",
  "reference": "A3FF000000439730A8E",
  "timestamp": 1494235313,
  "authcode": "",
  "pareq": "eyJyZWZlcmVuY2UiOiJBM0ZGMDAwMDAwMDM5NzMwQTgwRVhYMDEiLCJ0aW1lIjoxE0jjU1NTF8",
  "acs_url": "https://callback.maxpay.com/emitent/authentication",
  "eci": 5,
  "status": "success",
  "code": 0,
  "message": "Transaction processed successfully"
}

Response parameters:

Parameter Name Type Required Rules Example
api_version float yes maxLength: { max: 32 } 1
merchant_account string yes minLength: { min: 6 }, maxLength: { max: 32 } Testshop.com
sessionid string yes maxLength: { max: 36 } 53ec668b-c838-44b8-86f2-5c678ae9e3fc
transaction_unique_id string yes maxLength: { max: 32 }, minLength: { min: 1 } NwAkrkcPAmEcGzghnBwMeDRpXAPFsINg
token string yes length: { size: 36 } 14848ff0308f8a396041ddde45de5f8ffffa
reference string yes length: { size: 20 } ATFF1235432423
timestamp string yes unix timestamp 1408001694
authcode string yes maxLength: { max: 24 } 1111513
pareq string no maxLength: { max: 65535 } eJxVUctuwjAQ/JWIK1LsvAqNNpZS
acs_url string no maxLength: { max: 255 } https://maxpay.com:9443/PIT/ATS
eci numeric no { 1, 2, 5, 6, 7 } 7
status string yes { SUCCESS, DECLINE, ERROR } SUCCESS
code float yes Returns response code for the transaction Response codes table
message string yes Returns explanation of the response code Response message table

Example of redirect form after AUTH3D:


    <form id="acsform" method="POST" action="<AcsUrl>">
        <input name="PaReq" type="hidden" value="<PaReq>">
        <input name="TermUrl" type="hidden" value="<TermUrl>">
        <input name="MD" type="hidden" value="">
    </form>
    <script type="text/javascript">
        document.getElementById('acsform').submit();
    </script>

If merchant receives a successful response after AUTH3D request the next action is to route a customer for 3D Secure finishing. Parameters of the redirect form are provided below:

Parameter Description
AcsUrl Access Control Server url - url to re-direct the card holder
PaReq Payment authentication request - shows if card is enrolled
TermUrl URL to re-direct the card holder back to your website, also merchant receives PARes value on the TermUrl. Payment Authentication Response (PARes) which is generated by the Issuer, and contains information about the result of the check.

Notice: Supporting of this transaction type depends on acquirer side. Please, clarify the information before implementation of this transaction type. After the AUTH3D transaction has been processed a merchant depending on business requirements has ability but not forced to send the following transactons:

AUTH transaction

Sample code of AUTH transaction request:

“Content-type: application/json” –data

{
    "api_version":1,
    "merchant_account":"your_merchant_account",
    "merchant_password":"account_password",
    "transaction_unique_id":"auth_request001",
    "transaction_type":"AUTH",
    "amount":19.99,
    "currency":"USD",
    "card_number":"4111111111111111",
    "card_exp_month":"05",
    "card_exp_year":"2016",
    "cvv":"111",
    "first_name":"John",
    "last_name":"Doe",
    "card_holder":"John Doe",
    "address":"123 Street name.",
    "city":"City Name",
    "zip":"02001",
    "country":"USA",
    "user_phone":"123456789",
    "user_email":"test@test.com",
    "user_ip":"127.0.0.1"
}

Transaction requests should be performed via HTTP POST method using HTTP headers:

Accept: application/json,
Content-type: application/json.
Request should be sent in JSON format.

Purpose: Interface is used to hold transaction amount on the card holder’s account with full payment card data.

Request parameters:

Parameter Name Type Required Rules Example
api_version float/string yes maxLength: {max: 32} 1
merchant_account string yes minLength: {min: 6}, maxLength: {max: 32} MyAccount_MP_TRX
merchant_password string yes minLength: {min: 6}, maxLength: {max: 32 } Password
transaction_unique_id string yes minLength: {min: 6}, maxLength: {max: 32} trxId1234567890auth
transaction_type string yes validTransType, enum: { values: [”AUTH”]} AUTH
amount float yes float, maxLength: [0 - 9999999999.99] 9.99
currency string yes length: {size: 3}, ISO 4217 (alfa-3) EUR
card_number string yes minLength: {min: 13}, maxLength: {max: 19} only digits, Luhn algorithm 4864369454425300
card_exp_month string yes length: {size: 2}, only digits 05
card_exp_year string yes length: {size: 4}, only digits 2020
cvv string yes minLength: {min: 3}, maxLength: { max: 4 }, only digits 911
first_name string yes minLength: {min: 1}, maxLength: {max: 32} John
last_name string yes minLength: {min: 1}, maxLength: {max: 32} Doe
card_holder string yes minLength: {min: 2}, maxLength: {max: 32} John Doe
address string yes minLength: {min: 2} maxLength: {max: 32} 123 Street
city string yes minLength: { min: 2}, maxLength: {max: 32} New York
state string yes minLength: { min: 1}, maxLength: {max: 32} New York
zip string yes minLength: { min: 2 }, maxLength: {max: 10} 12100
country string yes minLength: { min: 2 }, maxLength: { max: 3 }, ISO 3166-1 alpha-3 USA
user_phone string yes minLength: {min: 7 }, maxLength: { max: 15 } +1-202-555-0000
user_ email string yes minLength: { min: 6 }, maxLength: { max: 255 }, valid email johndoe@test.com
user_ip string yes Ipv4Address 127.0.0.1
merchant_user_id string no maxLength: { max: 32 } UserId1200021
merchant_domain_name string no maxLength: { max: 255 } merchant-site.com
merchant_affiliate_id string no maxLength: { max: 255 } AF_id_7101
merchant_product_name string no maxLength: { max: 255 } Software
descriptor_merchant string no maxLength: { max: 255 } merchant-descriptor.com
descriptor_phone string no maxLength: { max: 255 } 180012345678
pares string no NotEmptyString ABJASDKA+SDKAJ/SGDSAD

Notice: if merchant sent an AUTH3D request before an AUTH, then merchant should also add a PARes for AUTH request.

Sample code of AUTH response in JSON format:

{
    "api_version":1,
    "merchant_account":"your_merchant_account",
    "sessionid":"543e2136-d46c-4d7d-a3b3-075cf9adkl01",
    "transaction_unique_id":"myUniqId1",
    "token":"5524fa52-75d8-4c7a-84ec-039d3097ab6f",
    "reference":"ATFF0000000039FDAEEF",
    "timestamp":1408001694,
    "authcode":"authcode_1544565466.22",
    "status":"success",
    "code":0,
    "message":"transaction processed successfully"
}

Response parameters:

Parameter Name Type Required Rules Example
api_version float yes maxLength: { max: 32 } 1
merchant_account string yes minLength: { min: 6 }, maxLength: { max: 32 } MyAccount_MP_TRX
sessionid string yes maxLength: { max: 36 } 53ec668b-c838-44b8-86f2-5c678ae9e3fc
transaction_unique_id string yes minLength: { min: 1 } maxLength: { max: 32 } trxId1234567890
token string yes length: { size: 36 } 14848ff0308f8a396041ddde45de5f8ffffa
reference string yes length: { size: 20 } ATFF0000000039FDAEEF
timestamp string yes unix timestamp 1408001694
authсode string yes maxLength: { max: 24 } authcode_1544565466.22
status string yes { SUCCESS, DECLINE, ERROR } SUCCESS
code float yes Returns response code for the transaction Response codes table
message string yes Returns explanation of the response code Response messages table

Notice: Supporting of this transaction type depends on acquirer side. Please, clarify the information before implementation of this transaction type. After the AUTH transaction has been processed a merchant have to send the following transactions:

AUTH (by token) transaction

Sample code of AUTH (by token) request:

“Content-type: application/json” –data

{
    "api_version":1,
    "merchant_account":"your_merchant_account",
    "merchant_password":"merchant_password",
    "transaction_unique_id":"auth_with_token001",
    "transaction_type":"AUTH",
    "amount":19.99,
    "currency":"USD",
    "first_name":"John",
    "last_name":"Doe",
    "card_holder":"John Doe",
    "address":"123 Street name.",
    "city":"City Name",
    "zip":"02001",
    "country":"USA",
    "user_phone":"123456789",
    "user_email":"test@test.com",
    "user_ip":"127.0.0.1",
    "token":"5524fa52-75d8-4c7a-84ec-039d3097ab6f"
}

Purpose: Interface is used to hold transaction amount on the card account using billtoken.

Request parameters:

Parameter Name Type Required Rules Example
api_version float/string yes maxLength: {max: 32} 1
merchant_account string yes minLength: {min: 6}, maxLength: {max: 32} MyAccount_MP_TRX
merchant_password string yes minLength: {min: 6}, maxLength: {max: 32 } Password
transaction_unique_id string yes minLength: {min: 6}, maxLength: {max: 32} trxId1234567890auth
transaction_type string yes validTransType, enum: { values: [”AUTH”]} AUTH
amount float yes float, maxLength: [0 - 9999999999.99] 9.99
currency string yes length: {size: 3}, ISO 4217 (alfa-3) EUR
first_name string yes minLength: {min: 1}, maxLength: {max: 32} John
last_name string yes minLength: {min: 1}, maxLength: {max: 32} Doe
card_holder string yes minLength: {min: 2}, maxLength: {max: 32} John Doe
address string yes minLength: {min: 2} maxLength: {max: 32} 123 Street
city string yes minLength: { min: 2}, maxLength: {max: 32} New York
state string yes minLength: { min: 1}, maxLength: {max: 32} New York
zip string yes minLength: { min: 2 }, maxLength: {max: 10} 12100
country string yes minLength: { min: 2 }, maxLength: { max: 3 }, ISO 3166-1 alpha-3 USA
user_phone string yes minLength: {min: 7 }, maxLength: { max: 15 } +1-202-555-0000
user_ email string yes minLength: { min: 6 }, maxLength: { max: 255 }, valid email johndoe@test.com
user_ip string yes Ipv4Address 127.0.0.1
merchant_user_id string no maxLength: { max: 32 } UserId1200021
merchant_domain_name string no maxLength: { max: 255 } merchant-site.com
merchant_affiliate_id string no maxLength: { max: 255 } AF_id_7101
merchant_product_name string no maxLength: { max: 255 } Software
descriptor_merchant string no maxLength: { max: 255 } merchant-descriptor.com
descriptor_phone string no maxLength: { max: 255 } 180012345678
pares string no NotEmptyString ABJASDKA+SDKAJ/SGDSAD
token string yes length: { size: 36 } 5524fa52-75d8-4c7a-84ec-039d3097ab6f

Notice: if merchant sent an AUTH3D request before an AUTH, then merchant should also add a PARes for AUTH request.

Sample code of AUTH (by token) response in JSON format:

{
    "api_version":1,
    "merchant_account":"your_merchant_account",
    "sessionid":"543e2136-d46c-4d7d-a3b3-075cf9af6dea",
    "transaction_unique_id":"auth_with_token001",
    "token":"5524fa52-75d8-4c7a-84ec-039d3097ab6f",
    "reference":" ATFF0000000039FDA11F",
    "timestamp":1408001694,
    "authcode":"authcode_1544565466.22",
    "status":"error",
    "code":3100,
    "message":"Decline"
}

Response parameters:

Parameter Name Type Required Rules Example
api_version float yes maxLength: { max: 32 } 1
merchant_account string yes minLength: { min: 6 }, maxLength: { max: 32 } MyAccount_MP_TRX
sessionid string yes maxLength: { max: 36 } 53ec668b-c838-44b8-86f2-5c678ae9e3fc
transaction_unique_id string yes minLength: { min: 1 } maxLength: { max: 32 } trxId1234567890
token string yes length: { size: 36 } 14848ff0308f8a396041ddde45de5f8ffffa
reference string yes length: { size: 20 } ATFF0000000039FDA11F
timestamp string yes unix timestamp 1408001694
authсode string yes maxLength: { max: 24 } authcode_1544565466.22
status string yes { SUCCESS, DECLINE, ERROR } SUCCESS
code float yes Returns response code for the transaction Response codes table
message string yes Returns explanation of the response code Response messages table

Notice: Supporting of this transaction type depends on acquirer side. Please, clarify the information before implementation of this transaction type. After the AUTH (by token) transaction has been processed a merchant depending on business requirements has ability but not forced to send the following transactions:

SETTLE transaction

Sample code of SETTLE transaction request:

“Content-type: application/json” –data

{
    "api_version":1,
    "merchant_account":"your_merchant_account",
    "merchant_password":"account_password",
    "transaction_unique_id":"settle_request001",
    "transaction_type":"SETTLE",
    "amount":9.99,
    "currency":"USD",
    "reference":"ATFF0000000039FDA11F"
}

Purpose: Interface is used to settle a previously-authorized (using AUTH) transaction.

Request parameters:

Parameter Name Type Required Rules Example
api_version float/string yes maxLength: {max: 32} 1
merchant_account string yes minLength: {min: 6}, maxLength: {max: 32} MyAccount_MP_TRX
merchant_password string yes minLength: {min: 6}, maxLength: {max: 32 } Password
transaction_unique_id string yes minLength: {min: 6}, maxLength: {max: 32} trxId1234567890Settle
transaction_type string yes validTransType, enum: { values: [”SETTLE”]} SETTLE
amount float yes float, maxLength: [0 - 9999999999.99] 9.99
currency string yes length: {size: 3}, ISO 4217 (alfa-3) EUR
reference string yes length: { size: 20 } ATFF0000000039FDA11F
merchant_user_id string no maxLength: { max: 32 } UserId1200021
merchant_domain_name string no maxLength: { max: 255 } merchant-site.com
merchant_affiliate_id string no maxLength: { max: 255 } AF_id_7101
merchant_product_name string no maxLength: { max: 255 } Software
descriptor_merchant string no maxLength: { max: 255 } merchant-descriptor.com
descriptor_phone string no maxLength: { max: 255 } 180012345678

Sample code of SETTLE response in JSON format:

{
    "api_version":1,
    "merchant_account":"your_merchant_account",
    "sessionid":"543e2136-d46c-4d7d-a3b3-075cf9adkl21",
    "transaction_unique_id":"settle_request001",
    "token":"5524fa52-75d8-4c7a-84ec-039d3097ab6f",
    "reference":"STFF0000000039FDAEGG",
    "timestamp":1408001694,
    "authcode":"",
    "status":"success",
    "code":0,
    "message":"transaction processed successfully"
}

Response parameters:

Parameter Name Type Required Rules Example
api_version float yes maxLength: { max: 32 } 1
merchant_account string yes minLength: { min: 6 }, maxLength: { max: 32 } MyAccount_MP_TRX
sessionid string yes maxLength: { max: 36 } 53ec668b-c838-44b8-86f2-5c678ae9e3fc
transaction_unique_id string yes minLength: { min: 1 } maxLength: { max: 32 } trxId1234567890
token string yes length: { size: 36 } 14848ff0308f8a396041ddde45de5f8ffffa
reference string yes length: { size: 20 } ATFF0000000039FDA11F
timestamp string yes unix timestamp 1408001694
authсode string yes maxLength: { max: 24 } authcode_1544565466.22
status string yes { SUCCESS, DECLINE, ERROR } SUCCESS
code float yes Returns response code for the transaction Response codes table
message string yes Returns explanation of the response code Response messages table

Notice: Supporting of this transaction type depends on acquirer side. Please, clarify the information before implementation of this transaction type. After the SETTLE transaction has been processed a merchant depending on business requirements has ability but not forced to send the following transactons:

SALE transaction

Sample code of SALE transaction request:

“Content-type: application/json” –data

{
    "api_version":1,
    "merchant_account":"your_merchant_account",
    "merchant_password":"account_password",
    "transaction_unique_id":"sale_request001",
    "transaction_type":"SALE",
    "amount":10,
    "currency":"USD",
    "card_number":"4111111111111111",
    "card_exp_month":"05",
    "card_exp_year":"2018",
    "cvv":"121",
    "first_name":"John",
    "last_name":"Doe",
    "card_holder":"John Doe",
    "address":"123 Street name.",
    "city":"City Name",
    "zip":"02001",
    "country":"USA",
    "user_phone":"123456789",
    "user_email":"test@test.com",
    "user_ip":"127.0.0.1"
}

Purpose: Interface is used to collect money directly from cardholder account using full payment card data.

Please note that in case of 3ds flow (after AUTH3D has successfully processed) pares and reference fields should be Required transmitted in the request.

Request parameters:

Parameter Name Type Required Rules Example
api_version float/string yes maxLength: {max: 32} 1
merchant_account string yes minLength: {min: 6}, maxLength: {max: 32} MyAccount_MP_TRX
merchant_password string yes minLength: {min: 6}, maxLength: {max: 32 } Password
transaction_unique_id string yes minLength: {min: 6}, maxLength: {max: 32} trxId1234567890sale
transaction_type string yes validTransType, enum: { values: [”SALE”]} SALE
amount float yes float, maxLength: [0 - 9999999999.99] 9.99
currency string yes length: {size: 3}, ISO 4217 (alfa-3) EUR
card_number string yes minLength: {min: 13}, maxLength: {max: 19} only digits, Luhn algorithm 4864369454425300
card_exp_month string yes length: {size: 2}, only digits 05
card_exp_year string yes length: {size: 4}, only digits 2020
cvv string yes minLength: {min: 3}, maxLength: { max: 4 }, only digits 911
first_name string yes minLength: {min: 1}, maxLength: {max: 32} John
last_name string yes minLength: {min: 1}, maxLength: {max: 32} Doe
card_holder string yes minLength: {min: 2}, maxLength: {max: 32} John Doe
address string yes minLength: {min: 2} maxLength: {max: 32} 123 Street
city string yes minLength: { min: 2}, maxLength: {max: 32} New York
state string yes minLength: { min: 1}, maxLength: {max: 32} New York
zip string yes minLength: { min: 2 }, maxLength: {max: 10} 12100
country string yes minLength: { min: 2 }, maxLength: { max: 3 }, ISO 3166-1 alpha-3 USA
user_phone string yes minLength: {min: 7 }, maxLength: { max: 15 } +1-202-555-0000
user_ email string yes minLength: { min: 6 }, maxLength: { max: 255 }, valid email johndoe@test.com
user_ip string yes Ipv4Address 127.0.0.1
merchant_user_id string no maxLength: { max: 32 } UserId1200021
merchant_domain_name string no maxLength: { max: 255 } merchant-site.com
merchant_affiliate_id string no maxLength: { max: 255 } AF_id_7101
merchant_product_name string no maxLength: { max: 255 } Software
descriptor_merchant string no maxLength: { max: 255 } merchant-descriptor.com
descriptor_phone string no maxLength: { max: 255 } 180012345678
pares string no NotEmptyString ABJASDKA+SDKAJ/SGDSAD
reference string no length: { size: 20 } Required for 3Ds flow A3FF000000439730A8E

Example of SALE response in JSON format:

{
    "api_version":1,
    "merchant_account":"your_merchant_account",
    "sessionid":"543e2136-d46c-4d7d-a3b3-075cf9adkl01",
    "transaction_unique_id":"sale_request001",
    "token":"5524fa52-75d8-4c7a-84ec-039d3097ab6f",
    "reference":" SLFF0000000039FDAEAB",
    "timestamp":1408001694,
    "authcode":"",
    "status":"success",
    "code":0,
    "message":"transaction processed successfully"
}

Response parameters:

Parameter Name Type Required Rules Example
api_version float yes maxLength: { max: 32 } 1
merchant_account string yes minLength: { min: 6 }, maxLength: { max: 32 } MyAccount_MP_TRX
sessionid string yes maxLength: { max: 36 } 53ec668b-c838-44b8-86f2-5c678ae9e3fc
transaction_unique_id string yes minLength: { min: 1 } maxLength: { max: 32 } trxId1234567890
token string yes length: { size: 36 } 14848ff0308f8a396041ddde45de5f8ffffa
reference string yes length: { size: 20 } ATFF0000000039FDA11F
timestamp string yes unix timestamp 1408001694
authсode string yes maxLength: { max: 24 } authcode_1544565466.22
status string yes { SUCCESS, DECLINE, ERROR } SUCCESS
code float yes Returns response code for the transaction Response codes table
message string yes Returns explanation of the response code Response messages table

After the SALE transaction has been processed a merchant depending on business requirements has ability but not forced to send the following transactons:

SALE (by token) transaction

Example of SALE (by token) request:

“Content-type: application/json” –data

{
    "api_version":1,
    "merchant_account":"your_merchant_account",
    "merchant_password":"account_password",
    "transaction_unique_id":"sale_token001",
    "transaction_type":"SALE",
    "amount":10,
    "currency":"USD",
    "first_name":"John",
    "last_name":"Doe",
    "card_holder":"John Doe",
    "address":"123 Street name.",
    "city":"City Name",
    "zip":"02001",
    "country":"USA",
    "user_phone":"123456789",
    "user_email":"test@test.com",
    "user_ip":"127.0.0.1",
    "token":"5524fa52-75d8-4c7a-84ec-039d3097ab6f"
}

Purpose: Interface is used to collect money directly from cardholder account using billtoken.

Request parameters:

Parameter Name Type Required Rules Example
api_version float/string yes maxLength: {max: 32} 1
merchant_account string yes minLength: {min: 6}, maxLength: {max: 32} MyAccount_MP_TRX
merchant_password string yes minLength: {min: 6}, maxLength: {max: 32 } Password
transaction_unique_id string yes minLength: {min: 6}, maxLength: {max: 32} trxId1234567890sale
transaction_type string yes validTransType, enum: { values: [”SALE”]} SALE
amount float yes float, maxLength: [0 - 9999999999.99] 9.99
currency string yes length: {size: 3}, ISO 4217 (alfa-3) EUR
first_name string yes minLength: {min: 1}, maxLength: {max: 32} John
last_name string yes minLength: {min: 1}, maxLength: {max: 32} Doe
card_holder string yes minLength: {min: 2}, maxLength: {max: 32} John Doe
address string yes minLength: {min: 2} maxLength: {max: 32} 123 Street
city string yes minLength: { min: 2}, maxLength: {max: 32} New York
state string yes minLength: { min: 1}, maxLength: {max: 32} New York
zip string yes minLength: { min: 2 }, maxLength: {max: 10} 12100
country string yes minLength: { min: 2 }, maxLength: { max: 3 }, ISO 3166-1 alpha-3 USA
user_phone string yes minLength: {min: 7 }, maxLength: { max: 15 } +1-202-555-0000
user_ email string yes minLength: { min: 6 }, maxLength: { max: 255 }, valid email johndoe@test.com
user_ip string yes Ipv4Address 127.0.0.1
merchant_user_id string no maxLength: { max: 32 } UserId1200021
merchant_domain_name string no maxLength: { max: 255 } merchant-site.com
merchant_affiliate_id string no maxLength: { max: 255 } AF_id_7101
merchant_product_name string no maxLength: { max: 255 } Software
descriptor_merchant string no maxLength: { max: 255 } merchant-descriptor.com
token string yes length: { size: 36 } 5524fa52-75d8-4c7a-84ec-039d3097ab6f

Example of SALE (by token) response in JSON format:

{
    "api_version":1,
    "merchant_account":"your_merchant_account",
    "sessionid":"543e2136-d46c-4d7d-a3b3-075cf9adkl21",
    "transaction_unique_id":"sale_token001",
    "token":"5524fa52-75d8-4c7a-84ec-039d3097ab6f",
    "reference":"SLFF0000000039FDAEGG",
    "timestamp":1408001694,
    "authcode":"",
    "status":"success",
    "code":0,
    "message":"transaction processed successfully"
}

Response parameters:

Parameter Name Type Required Rules Example
api_version float yes maxLength: { max: 32 } 1
merchant_account string yes minLength: { min: 6 }, maxLength: { max: 32 } MyAccount_MP_TRX
sessionid string yes maxLength: { max: 36 } 53ec668b-c838-44b8-86f2-5c678ae9e3fc
transaction_unique_id string yes minLength: { min: 1 } maxLength: { max: 32 } trxId1234567890
token string yes length: { size: 36 } 14848ff0308f8a396041ddde45de5f8ffffa
reference string yes length: { size: 20 } ATFF0000000039FDA11F
timestamp string yes unix timestamp 1408001694
authсode string yes maxLength: { max: 24 } authcode_1544565466.22
status string yes { SUCCESS, DECLINE, ERROR } SUCCESS
code float yes Returns response code for the transaction Response codes table
message string yes Returns explanation of the response code Response messages table

After the SALE (by token) transaction has been processed a merchant depending on business requirements has ability but not forced to send the following transactons:

SALE3D transaction

Sample code of SALE3D transaction request:

“Content-type: application/json” –data

{
    "api_version":1,
    "merchant_account":"your_merchant_account",
    "merchant_password":"account_password",
    "transaction_unique_id":"sale3D_request001",
    "transaction_type":"SALE3D",
    "amount":10,
    "currency":"USD",
    "card_number":"5191330000004415",
    "card_exp_month":"05",
    "card_exp_year":"2018",
    "cvv":"121",
    "first_name":"John",
    "last_name":"Doe",
    "card_holder":"John Doe",
    "address":"123 Street name.",
    "city":"City Name",
    "zip":"02001",
    "country":"USA",
    "user_phone":"123456789",
    "user_email":"johndoe@test.com",
    "user_ip":"127.0.0.1",
    "callback_url":"https://test.com/callback",
    "redirect_url":"https://test.com/redirect"
}

Purpose: Interface is used to check ability to follow 3DS flow for the card. The ECI code will be returned to explain the reason (for example in negative case). In the positive case SALE request runs automatically on Maxpay Gateway side. Response on SALE request will be transmitted to Merchant callback URL.

Request parameters:

Parameter Name Type Required Rules Example
api_version float/string yes maxLength: {max: 32} 1
merchant_account string yes minLength: {min: 6}, maxLength: {max: 32} MyAccount_MP_TRX
merchant_password string yes minLength: {min: 6}, maxLength: {max: 32 } Password
transaction_unique_id string yes minLength: {min: 6}, maxLength: {max: 32} trxId1234567890sale3D
transaction_type string yes validTransType, enum: { values: [”SALE3D”]} SALE3D
amount float yes float, maxLength: [0 - 9999999999.99] 9.99
currency string yes length: {size: 3}, ISO 4217 (alfa-3) EUR
card_number string yes minLength: {min: 13}, maxLength: {max: 19} only digits, Luhn algorithm 4864369454425300
card_exp_month string yes length: {size: 2}, only digits 05
card_exp_year string yes length: {size: 4}, only digits 2020
cvv string yes minLength: {min: 3}, maxLength: { max: 4 }, only digits 911
first_name string yes minLength: {min: 1}, maxLength: {max: 32} John
last_name string yes minLength: {min: 1}, maxLength: {max: 32} Doe
card_holder string yes minLength: {min: 2}, maxLength: {max: 32} John Doe
address string yes minLength: {min: 2} maxLength: {max: 32} 123 Street
city string yes minLength: { min: 2}, maxLength: {max: 32} New York
state string yes minLength: { min: 1}, maxLength: {max: 32} New York
zip string yes minLength: { min: 2 }, maxLength: {max: 10} 12100
country string yes minLength: { min: 2 }, maxLength: { max: 3 }, ISO 3166-1 alpha-3 USA
user_phone string yes minLength: {min: 7 }, maxLength: { max: 15 } +1-202-555-0000
user_ email string yes minLength: { min: 6 }, maxLength: { max: 255 }, valid email johndoe@test.com
user_ip string yes Ipv4Address 127.0.0.1
merchant_user_id string no maxLength: { max: 32 } UserId1200021
merchant_domain_name string no maxLength: { max: 255 } merchant-site.com
merchant_affiliate_id string no maxLength: { max: 255 } AF_id_7101
merchant_product_name string no maxLength: { max: 255 } Software
descriptor_merchant string no maxLength: { max: 255 } merchant-descriptor.com
descriptor_phone string no maxLength: { max: 255 } 180012345678
callback_url string yes maxLength: { max: 255 } must have SSL https://testshop.com/success
redirect_url string yes maxLength: { max: 255 } https://merchant-site.com

Example of SALE3D response in JSON format:

{
    "api_version":1,
    "merchant_account":"your_merchant_account",
    "sessionid":"543e2136-d46c-4d7d-a3b3-075cf9adkl21",
    "transaction_unique_id":"sale3D_request001",
    "token":"5524fa52-75d8-4c7a-84ec-039d3097ab6g",
    "reference":"S3FF0000000039FDAEGG",
    "timestamp":1408001694,
    "authcode": "",
    "eci": 5,
    "acs_url": "https://callback.maxpay.com/emitent/authentication",
    "authcode":"",
    "status":"success",
    "code":0,
    "message":"transaction processed successfully"
}

Response parameters:

Parameter Name Type Required Rules Example
api_version float yes maxLength: { max: 32 } 1
merchant_account string yes minLength: { min: 6 }, maxLength: { max: 32 } MyAccount_MP_TRX
sessionid string yes maxLength: { max: 36 } 53ec668b-c838-44b8-86f2-5c678ae9e3fc
transaction_unique_id string yes maxLength: { max: 32 }, minLength: { min: 1 } NwAkrkcPAmEcGzghnBwMeDRpXAPFsINg
token string yes length: { size: 36 } 14848ff0308f8a396041ddde45de5f8ffffa
reference string yes length: { size: 20 } S3FF0000000039FDAEGG
timestamp string yes unix timestamp 1408001694
authcode string yes maxLength: { max: 24 } 1111513
eci float no { 1, 2, 5, 6, 7 } 7
acs_url string no maxLength: { max: 255 } https://maxpay.com:9443/PIT/ATS
status string yes { SUCCESS, DECLINE, ERROR } SUCCESS
code float yes Returns response code for the transaction Response codes table
message string yes Returns explanation of the response code Response message table

Sample code of callback on SALE3D transaction in JSON format:

{
    "token" : "50cb16c0-21a8-ambc-a177-555bbd65a038",
    "reference" : "S3FF000000061A31AGB8",
    "transaction_unique_id" : "sale3D_transaction_001",
    "status" : "success",
    "code" : 0,
    "message" : "Transaction processed successfully",
    "checkSum" : "a124978dc3fbcf3e1d1dd60dd011139a027c3e86111173176f6ca4c0aa6138sd"
}

According to SALE3D flow Maxpay initiates SALE transaction automatically and sends the response to predefined Merchant callback URL. Parameters of callback fields are provided below:

PARAMETER DESCRIPTION
token Token value
reference Unique reference of the transaction in Maxpay system
transaction_unique_id The unique id of the transaction.
status Status of the transaction.
code The response code of the transaction. The detailed list could be found in “response codes” section below.
message An explanation message of the transaction. The detailed list could be found in “response codes” section below.
checkSum Check sum of callback packet

Callback is received to a merchant when in response Maxpay got the code - 200 and body text - OK. In other cases, callback is not received and Maxpay will try periodically to send callback data. The number of attempts are limited.

Examples below describe different cases with callback data receiving:

HTTP Code Body text Description
200 OK Callback is successfully received
500 OK Callback is not received

Notice: Supporting of this transaction type depends on acquirer side. Please, clarify the information before implementation of this transaction type. After the SALE3D transaction has been processed a merchant depending on business requirements has ability to send the following transactons:

SALE3D (by token) transaction

Sample code of SALE3D (by token) request:

“Content-type: application/json” –data

{
    "api_version":1,
    "merchant_account":"your_merchant_account",
    "merchant_password":"account_password",
    "transaction_unique_id":"sale3D_token001",
    "transaction_type":"SALE3D",
    "amount":10,
    "currency":"USD",
    "first_name":"John",
    "last_name":"Doe",
    "card_holder":"John Doe",
    "address":"123 Street name.",
    "city":"City Name",
    "zip":"02001",
    "country":"USA",
    "user_phone":"123456789",
    "user_email":"johndoe@test.com",
    "user_ip":"127.0.0.1",
    "token":"5524fa52-75d8-4c7a-84ec-039d3097ab6g",
    "callback_url":"https://test.com/callback",
    "redirect_url":"https://test.com/redirect"
}

Purpose: Interface is used to check ability to follow 3DS flow for the card by billing. The ECI code will be returned to explain the reason (for example in negative case). In the positive case SALE request runs automatically on Maxpay Gateway side. Response on SALE request will be transmitted to Merchant callback URL.

Request parameters:

Parameter Name Type Required Rules Example
api_version float/string yes maxLength: {max: 32} 1
merchant_account string yes minLength: {min: 6}, maxLength: {max: 32} MyAccount_MP_TRX
merchant_password string yes minLength: {min: 6}, maxLength: {max: 32 } Password
transaction_unique_id string yes minLength: {min: 6}, maxLength: {max: 32} trxId1234567890sale3D
transaction_type string yes validTransType, enum: { values: [”SALE3D”]} SALE3D
amount float yes float, maxLength: [0 - 9999999999.99] 9.99
currency string yes length: {size: 3}, ISO 4217 (alfa-3) EUR
first_name string yes minLength: {min: 1}, maxLength: {max: 32} John
last_name string yes minLength: {min: 1}, maxLength: {max: 32} Doe
card_holder string yes minLength: {min: 2}, maxLength: {max: 32} John Doe
address string yes minLength: {min: 2} maxLength: {max: 32} 123 Street
city string yes minLength: { min: 2}, maxLength: {max: 32} New York
state string yes minLength: { min: 1}, maxLength: {max: 32} New York
zip string yes minLength: { min: 2 }, maxLength: {max: 10} 12100
country string yes minLength: { min: 2 }, maxLength: { max: 3 }, ISO 3166-1 alpha-3 USA
user_phone string yes minLength: {min: 7 }, maxLength: { max: 15 } +1-202-555-0000
user_ email string yes minLength: { min: 6 }, maxLength: { max: 255 }, valid email johndoe@test.com
user_ip string yes Ipv4Address 127.0.0.1
merchant_user_id string no maxLength: { max: 32 } UserId1200021
merchant_domain_name string no maxLength: { max: 255 } merchant-site.com
merchant_affiliate_id string no maxLength: { max: 255 } AF_id_7101
merchant_product_name string no maxLength: { max: 255 } Software
descriptor_merchant string no maxLength: { max: 255 } merchant-descriptor.com
descriptor_phone string no maxLength: { max: 255 } 180012345678
token string yes length: { size: 36 } 5524fa52-75d8-4c7a-84ec-039d3097ab6g
callback_url string yes maxLength: { max: 255 } must have SSL https://testshop.com/success
redirect_url string yes maxLength: { max: 255 } https://merchant-site.com

Example of SALE3D (by token) response in JSON format:

{
    "api_version":1,
    "merchant_account":"your_merchant_account",
    "sessionid":"543e2136-d46c-4d7d-a3b3-075cf9adkl21",
    "transaction_unique_id":"sale3D_token001",
    "token":"5524fa52-75d8-4c7a-84ec-039d3097ab6g",
    "reference":" S3FF0000000039FDAEGH",
    "timestamp":1408001694,
    "authcode": "",
    "eci": 5,
    "acs_url": "https://callback.maxpay.com/emitent/authentication",
    "authcode":"",
    "status":"success",
    "code":0,
    "message":"transaction processed successfully"
}

Response parameters:

Parameter Name Type Required Rules Example
api_version float yes maxLength: { max: 32 } 1
merchant_account string yes minLength: { min: 6 }, maxLength: { max: 32 } MyAccount_MP_TRX
sessionid string yes maxLength: { max: 36 } 53ec668b-c838-44b8-86f2-5c678ae9e3fc
transaction_unique_id string yes maxLength: { max: 32 }, minLength: { min: 1 } NwAkrkcPAmEcGzghnBwMeDRpXAPFsINg
token string yes length: { size: 36 } 14848ff0308f8a396041ddde45de5f8ffffa
reference string yes length: { size: 20 } S3FF0000000039FDAEGG
timestamp string yes unix timestamp 1408001694
authcode string yes maxLength: { max: 24 } 1111513
eci float no { 1, 2, 5, 6, 7 } 7
acs_url string no maxLength: { max: 255 } https://maxpay.com:9443/PIT/ATS
status string yes { SUCCESS, DECLINE, ERROR } SUCCESS
code float yes Returns response code for the transaction Response codes table
message string yes Returns explanation of the response code Response message table

Sample code of callback on SALE3D transaction in JSON format:

{
    "token" : "50cb16c0-21a8-ambc-a177-555bbd65a038",
    "reference" : "S3FF000000061A31AGB8",
    "transaction_unique_id" : "sale3D_transaction_001",
    "status" : "success",
    "code" : 0,
    "message" : "Transaction processed successfully",
    "checkSum" : "a124978dc3fbcf3e1d1dd60dd011139a027c3e86111173176f6ca4c0aa6138sd"
}

According to SALE3D flow Maxpay initiates SALE transaction automatically and sends the response to predefined Merchant callback URL. Parameters of callback fields are provided below:

PARAMETER DESCRIPTION
token Token value
reference Unique reference of the transaction in Maxpay system
transaction_unique_id The unique id of the transaction.
status Status of the transaction.
code The response code of the transaction. The detailed list could be found in “response codes” section below.
message An explanation message of the transaction. The detailed list could be found in “response codes” section below.
checkSum Check sum of callback packet

Callback is received to a merchant when in response Maxpay got the code - 200 and body text - OK. In other cases, callback is not received and Maxpay will try periodically to send callback data. The number of attempts are limited.

Examples below describe different cases with callback data receiving:

HTTP Code Body text Description
200 OK Callback is successfully received
500 OK Callback is not received

Notice: Supporting of this transaction type depends on acquirer side. Please, clarify the information before implementation of this transaction type. After the SALE3D transaction has been processed a merchant depending on business requirements has ability to send the following transactons:

REFUND transaction

Sample code of REFUND request:

“Content-type: application/json” –data

{
    "api_version":1,
    "merchant_account":"your_merchant_account",
    "merchant_password":"account_password",
    "transaction_unique_id":"refund_request001",
    "transaction_type":"REFUND",
    "amount":10,
    "currency":"USD",
    "reference":"SLFF0000000039FDAEGG"
}

Purpose: Interface is used to refund a previously settled transaction.

Request parameters:

Parameter Name Type Required Rules Example
api_version float/string yes maxLength: {max: 32} 1
merchant_account string yes minLength: {min: 6}, maxLength: {max: 32} MyAccount_MP_TRX
merchant_password string yes minLength: {min: 6}, maxLength: {max: 32 } Password
transaction_unique_id string yes minLength: {min: 6}, maxLength: {max: 32} trxId1234567890refund
transaction_type string yes validTransType, enum: { values: [”REFUND”]} REFUND
amount float yes float, maxLength: [0 - 9999999999.99] 9.99
currency string yes length: {size: 3}, ISO 4217 (alfa-3) EUR
reference string yes length: { size: 20 } SLFF0000000039FDA11F reference of SALE, SALE3D or SETTLE transaction
merchant_user_id string no maxLength: { max: 32 } UserId1200021
descriptor_merchant string no maxLength: { max: 255 } merchant-descriptor.com
descriptor_phone string no maxLength: { max: 255 } 180012345678

Sample code of REFUND response in JSON format:

{
    "api_version":1,
    "merchant_account":"your_merchant_account",
    "sessionid":"543e2136-d46c-4d7d-a3b3-075cf9adkl21",
    "transaction_unique_id":"refund_request001",
    "token":"5524fa52-75d8-4c7a-84ec-039d3097ab6f",
    "reference":"RFF0000000039FDAEGG",
    "timestamp":1408001694,
    "authcode":"",
    "status":"success",
    "code":0,
    "message":"transaction processed successfully"
}

Response parameters:

Parameter Name Type Required Rules Example
api_version float yes maxLength: { max: 32 } 1
merchant_account string yes minLength: { min: 6 }, maxLength: { max: 32 } MyAccount_MP_TRX
sessionid string yes maxLength: { max: 36 } 53ec668b-c838-44b8-86f2-5c678ae9e3fc
transaction_unique_id string yes minLength: { min: 1 } maxLength: { max: 32 } trxId1234567890
token string yes length: { size: 36 } 14848ff0308f8a396041ddde45de5f8ffffa
reference string yes length: { size: 20 } ATFF0000000039FDA11F
timestamp string yes unix timestamp 1408001694
authсode string yes maxLength: { max: 24 } authcode_1544565466.22
status string yes { SUCCESS, DECLINE, ERROR } SUCCESS
code float yes Returns response code for the transaction Response codes table
message string yes Returns explanation of the response code Response messages table

After the REFUND transaction has been processed a merchant depending on business requirements has ability but not forced to send the following transactons:

VOID transaction

Sample code of VOID request:

“Content-type: application/json” –data

{
    "api_version":1,
    "merchant_account":"your_merchant_account",
    "merchant_password":"account_password",
    "transaction_unique_id":"void_request001",
    "transaction_type":"VOID",
    "reference":"ATFF0000000039FDAEGG"
}

Purpose: Interface is used to to back out of a transaction before it is settled or credited.

Request parameters:

Parameter Name Type Required Rules Example
api_version float yes maxLength: { max: 32 } 1
merchant_account string yes minLength: { min: 6 } maxLength: { max: 32 } Testshop.com
merchant_password string yes minLength: { min: 6 } maxLength: { max: 32 } testpassword
transaction_unique_id string yes minLength: { min: 1 } maxLength: { max: 32 } NwAkrkcPAmEcGzghnBwMeDRpXAPFsINg
transaction_type string yes validTransType, enum: { values: [”VOID”]} VOID
reference string yes length: { size: 20 } 14848ff0308f8a396041ddde45de5f8ffffa
merchant_user_id string no maxLength: { max: 32} 6d4a5d94821279725ecb3b0da9319d9b
descriptor_merchant string no maxLength: { max: 255 } merchant.com
descriptor_phone string no maxLength: { max: 255 } 180012345678

Sample code of VOID response in JSON format:

{
    "api_version":1,
    "merchant_account":"your_merchant_account",
    "sessionid":"543e2136-d46c-4d7d-a3b3-075cf9adkl21",
    "transaction_unique_id":"void_request001",
    "token":"5524fa52-75d8-4c7a-84ec-039d3097ab6f",
    "reference":"VDFF0000000039FDAEGG",
    "timestamp":1408001694,
    "authcode":"",
    "status":"success",
    "code":0,
    "message":"transaction processed successfully"
}

Response parameters:

Parameter Name Type Required Rules Example
api_version float yes maxLength: { max: 32 } 1
merchant_account string yes minLength: { min: 6 }, maxLength: { max: 32 } MyAccount_MP_TRX
sessionid string yes maxLength: { max: 36 } 53ec668b-c838-44b8-86f2-5c678ae9e3fc
transaction_unique_id string yes minLength: { min: 1 } maxLength: { max: 32 } trxId1234567890
token string yes length: { size: 36 } 14848ff0308f8a396041ddde45de5f8ffffa
reference string yes length: { size: 20 } ATFF0000000039FDA11F
timestamp string yes unix timestamp 1408001694
authсode string yes maxLength: { max: 24 } authcode_1544565466.22
status string yes { SUCCESS, DECLINE, ERROR } SUCCESS
code float yes Returns response code for the transaction Response codes table
message string yes Returns explanation of the response code Response messages table

Notice: Supporting of this transaction type depends on acquirer side. Please, clarify the information before implementation of this transaction type. After the VOID transaction has been processed a merchant depending on business requirements has ability but not forced to send the following transactons:

Check transaction

Sample code of CHECK request:

https://gateway.maxpay.com/api/cc

“Content-type: application/json” –data

{
    "api_version":1,
    "merchant_account":"your_merchant_account",
    "merchant_password":"account_password",
    "transaction_type":"CHECK",
    "reference":"ATFF00000000395AD690",
     "transaction_unique_id":"check_request001"
}

Purpose: Interface should be used to check transaction status.

Request parameters:

Parameter Name Type Required Rules Example
api_version float yes maxLength: { max: 32 } 1
merchant_account string yes minLength: { min: 6 } maxLength: { max: 32 } Testshop.com
merchant_password string yes minLength: { min: 6 } maxLength: { max: 32 } testpassword
transaction_type string yes validTransType, enum: { values: [“CHECK”]} CHECK
reference string no length: { size: 20 } 14848ff0308f8a396041ddde45de5f8ffffa
transaction_unique_id string no minLength: { min: 1 } maxLength: { max: 32 } NwAkrkcPAmEcGzghnBwMeDRpXAPFsINg

Sample code of CHECK response in JSON format:

{
    "api_version":1,
    "merchant_account":"your_merchant_account",
    "sessionid":"5668fbfb-2d9c-492c-9f7c-11fb8ae9e3fc",
    "transactions":[
        {
            "reference":"ATFF00000000395AD690",
            "transaction_unique_id":"accept.1427710387.689199806",
            "transaction_type":"AUTH",
            "status":"SUCCESS",
            "code":0,
            "message":"SUCCESS",
            "token":"5519225d-3460-433f-ad4e-62649d0bb909",
            "timestamp":1429796980,
            "authcode":"111313"
        }
    ],
    "status":"success",
    "code":0,
    "message":"Transaction processed successfully"
}

Response parameters:

Parameter Name Type Required Rules Example
api_version float yes maxLength: { max: 32 } 1
merchant_account string yes minLength: { min: 6 } maxLength: { max: 32 } your_merchant_account
sessionid string yes maxLength: { max: 36 } 53ec668b-c838-44b8-86f2-5c678ae9e3fc
transactions array yes Should be array transactions
reference string yes length: { size: 20 }, transactions array element ATFF1235432423
transaction_unique_id string yes minLength: { min: 1 } maxLength: { max: 32 }, transactions array element NwAkrkcPAmEcGzghnBwMeDRpXAPFsINg
transaction_type string yes validTransType, array element AUTH
status string yes { SUCCESS, DECLINE, ERROR }, transactions array element success
code numeric yes Returns response code of the transaction, transactions array element Response codes table
message string yes Returns explanation of the response code, transactions array element Response codes table
token string yes length: { size: 36 }, transactions array element 14848ff0308f8a396041ddde45de5f8ffffa
timestamp string yes unix timestamp, transactions array element 1408001694
authcode string yes maxLength: { max: 24 }, transactions array element 1111513
status string yes { SUCCESS, DECLINE, ERROR } SUCCESS
code numeric yes Returns response code of the transaction Response codes table
message string yes Returns explanation of the response code Response codes table

After the CHECK transaction has been processed a merchant can send any transactons depending on the stage of an actual transaction flow process.

Tokenize transaction

Sample code example of TOKENIZE request:

https://gateway.maxpay.com/api/cc

“Content-type: application/json” –data

{
    "api_version":1,
    "merchant_account":"your_merchant_account",
    "merchant_password":"account_password",
    "transaction_type":"TOKENIZE",
    "card_number":"4111111111111111",
    "card_exp_month":"05",
    "card_exp_year":"2018",
    "cvv":"111",
    "card_holder":"John Doe"
}

Purpose: Interface is used to tokenize card number with randomly generated series of digits and symbols.

Request parameters:

Parameter Name Type Required Rules Example
api_version float yes maxLength: { max: 32 } 1
merchant_account string yes minLength: { min: 6 } maxLength: { max: 32 } Testshop.com
merchant_password string yes minLength: { min: 6 } maxLength: { max: 32 } testpassword
transaction_type string yes validTransType, enum: { values: [”TOKENIZE”]} TOKENIZE
card_number string yes minLength: { min: 13 }, maxLength: { max: 19 } only digits, Luhn algorithm 4864369454425300
card_exp_month string yes length: { size: 2 }, only digits 05
card_exp_year string yes length: { size: 4 }, only digits 2016
card_holder string yes minLength: { min: 3 } maxLength: { max: 32 } Card Holder

Sample code of TOKENIZE response in JSON format:

{
    "api_version":1,
    "merchant_account":"your_merchant_account",
    "sessionid":"5538fcc8-8070-4e62-9a67-773f8ae9e3fc",
    "transaction_unique_id":null,
    "token":"54a9429f-00e0-475f-bc8f-22a158a0e038",
    "reference":null,
    "timestamp":1429798090,
    "authcode":null,
    "status":"success",
    "code":0,
    "message":"Transaction processed successfully"
}

Response parameters:

Parameter Name Type Required Rules Example
api_version float yes maxLength: { max: 32 } 1
merchant_account string yes minLength: { min: 6 } maxLength: { max: 32 } Testshop.com
sessionid string yes maxLength: { max: 36 } 53ec668b-c838-44b8-86f2-5c678ae9e3fc
authcode string yes maxLength: { max: 24 } null
token string yes length: { size: 36 } 14848ff0308f8a396041ddde45de5f8ffffa
reference string yes length: { size: 20 } null
transaction_unique_id string yes minLength: { min: 1 } maxLength: { max: 32 } null
timestamp string yes unix timestamp 1408001694
status string yes { SUCCESS, DECLINE, ERROR } SUCCESS
code numeric yes Returns response code of the transaction Response codes table
message string yes Returns explanation of the response code Response codes table

After the Tokenize transaction has been processed a merchant has ability to use card Token instead of credit card number details. Notice, that Maxpay doesn’t advise to use Tokenize type of transaction.

Erroneous response

Purpose: this type of response will be transmitted if an incorrect (except CHECK) request was received or in case of erroneous system behavior. All Required fields must be transmitted in the response.

Response parameters:

Parameter Name Type Required Rules Example
api_version float yes maxLength: { max: 32 } 1
merchant_account string yes minLength: { min: 6 } maxLength: { max: 32 } Testshop.com
sessionid string yes maxLength: { max: 36 } 53ec668b-c838-44b8-86f2-5c678ae9e3fc
transaction_unique_id string yes null null
token string yes length: { size: 36 } null
reference string yes length: { size: 20 } null
authcode string yes maxLength: { max: 24 } null
eci numeric no { 1, 2, 5, 6, 7 } null
pareq string no maxLength: { max: 65535 } null
acs_url string no maxLength: { max: 255 } null
timestamp string yes unix timestamp 1408001694
status string yes {ERROR } ERROR
code numeric yes Returns response code of the transaction Response codes table
message string yes Returns explanation of the response code Response codes table

Erroneous response on check

Purpose: this type of response will be transmitted if an incorrect CHECK request was received or in case of erroneous system behavior. All Required fields must be transmitted in the response.

Response parameters:

Parameter Name Type Required Rules Example
api_version float yes maxLength: { max: 32 } 1
merchant_account string yes minLength: { min: 6 }, maxLength: { max: 32 } null
sessionid string yes maxLength: { max: 36 } null
reference string yes length: { size: 20 } null
transaction_unique_id string yes minLength: { min: 1 } maxLength: { max: 32 } null
token string yes length: { size: 36 } null
authcode string yes maxLength: { max: 24 } null
timestamp string yes unix timestamp 1429797960
status string yes { ERROR } ERROR
code numeric yes Returns response code of the transaction Response codes table
message string yes Returns explanation of the response code Returns explanation of the response code

Payout API

Overview

Maxpay provides merchants functionality which allows to make payouts to their clients.

Web Service URL
Live Maxpay Payout API Service https://gateway.maxpay.com/api/payout
Test Maxpay Payout API Service https://gateway-sandbox.maxpay.com/api/payout

Payout Methods

Example of searching request for available payout methods:

“Content-type: JSON, XML, POST” –data

{
    "api_version": 1,
    "method": "list",
    "merchant_account": "my_merchant_account",
    "merchant_password": "my_merchant_password"
}

Request parameters:

Field Mandatory Type Description
api_version yes int API version.
method yes string List - returns available payout methods.
merchant_account yes string Account of the merchant. Given by MaxPay.
merchant_password yes string Password of the merchant. Given by MaxPay.

Example of response in JSON format:

{
   "sessionid": "someid",
   "status": "success",
   "code": 0,
   "message": "Request processed successfully",
   "methods": [
        {
            "type": "card",
            "mid_name": "my_credit_card_mid",
            "mid_reference": "0001234567J",
            "currencies": ["USD"]
        },
        {
            "type": "qiwi",
            "mid_name": "my_Qiwi_mid",
            "mid_reference": "0001234567J",
            "currencies": ["EUR", "USD", "RUB"]
        },
        {
            "type": "yandex",
            "mid_name": "my_Yandex_mid",
            "mid_reference": "0001234567J",
            "currencies": ["USD", "RUB"]
        },
        {
            "type": "paysafecard",
            "mid_name": "my_Paysafecard_mid",
            "mid_reference": "0001234533D1",
            "currencies": ["USD", "EUR"]
        }
    ]
}

Response parameters:

Field Mandatory Type Description
sessionid yes string An unique Id of the session.
timestamp yes string Time of the request.
methods yes *method[] Available methods.
status yes string ENUM [‘success’, 'decline’, 'error’] Response status
code yes int Response code
message yes string Response description.

Methods

Field Mandatory Type Description
type yes string Type of the method.
mid_name yes string Name of the MID.
mid_reference yes string MID reference.
currencies yes string[] Support currencies

Notification for init method

In case of successful request merchant will receive status=pending and code=0 in response. Notice that the final status of the payout request merchant will receive in callback data, more details regarding callback data is described below.

Payout on CC

Example of the payout request on credit card via full CC data:

“Content-type: JSON, XML, POST” –data

{
    "api_version": 1,
    "method": "init",
    "merchant_account": "my_merchant_account",
    "merchant_password": "my_merchant_password",
    "transaction_unique_id": "0001234567",
    "amount": 10,
    "currency": "USD",
    "callback_url": "https://mycallback.com/",
    "user_id": "someId",
    "user_ip": "127.0.0.1",
    "user_email": "user_email@example.com",
    "card": {
        "card_cvv": "022",
        "card_number": "xxx",
        "card_holder": "John Doe",
        "card_exp_year": "2020",
        "card_exp_month": "12"
    }
}

Parameters of the payout request on credit card via full CC data:

Field Mandatory Type Description
api_version yes int API version
method yes string Init method
merchant_account yes string Account of the merchant. Given by MaxPay.
merchant_password yes string Password of the merchant. Given by MaxPay.
transaction_unique_id yes string An unique Id of the transaction.
mid_reference no string MID reference
amount yes float\int Amount of payout request.
currency yes string Currency in ISO format. Examples: USD, EUR, GBP.
callback_url yes string The url of callback. It should have https protocol.
user_id yes string An unique Id of the user.
user_email yes string Email of the user.
user_ip no string User IP address.
user_first_name no string The first name of the user.
user_last_name no string The last name of the user.
user_phone no string Phone number.
user_state no string State of the user.
user_country no string Country of the user.
user_city no string City of the user.
user_address no string Address of the user.
user_zip no string Zip of the user.
card[card_number] yes luhn string Card number.
card[card_cvv] no numeric[3,4] CVV of the card consists of 3 or 4 digits.
card[card_holder] no string Cardholder name
card[card_exp_year] no numeric[4] Expiry year consists of 4 digits.
card[card_exp_month] no numeric[2] Expiry month consists of 2 digits.

Example of the response in JSON format:

{
    "sessionid": "5118fcfc-2d9c-492c-9f7c-21470c",
    "status": "success",
    "code": 0,
    "message": "Request processed successfully"
}

Response parameters:

Field Mandatory Type Description
sessionid yes string An unique Id of the session.
status yes string ENUM ['success’, 'decline’, 'error’] Response status
code yes int Response code
message yes string Response description.

Payout via Token

Example of the payout request on credit card via Token:

“Content-type: JSON, XML, POST” –data

{
    "api_version": 1,
    "method": "init",
    "merchant_account": "my_merchant_account",
    "merchant_password": "my_merchant_password",
    "transaction_unique_id": "0001234567",
    "amount": 10,
    "currency": "USD",
    "callback_url": "https://mycallback.com/",
    "user_id": "someId",
    "user_ip": "127.0.0.1",
    "user_email": "user_email@example.com",
    "card": {
        "token": "token_value",
        "card_holder": "John Doe"
    }
}

You are able to use a Token value instead of full CC data.

Parameters of the payout request on credit card via Token:

Field Mandatory Type Description
api_version yes int API version
method yes string Init method
merchant_account yes string Account of the merchant. Given by MaxPay.
merchant_password yes string Password of the merchant. Given by MaxPay.
transaction_unique_id yes string An unique Id of the transaction.
mid_reference no string MID reference
amount yes float\int Amount of payout request.
currency yes string Currency in ISO format. Examples: USD, EUR, GBP.
callback_url yes string The url of callback. It should have https protocol.
user_id yes string An unique Id of the user.
user_email yes string Email of the user.
user_ip no string User IP address.
user_first_name no string The first name of the user.
user_last_name no string The last name of the user.
user_phone no string Phone number.
user_state no string State of the user.
user_country no string Country of the user.
user_city no string City of the user.
user_address no string Address of the user.
user_zip no string Zip of the user.
card[token] yes string Value of the Token.
card[card_holder] no string Cardholder name

Example of the response in JSON format:

{
    "sessionid": "5118fcfc-2d9c-492c-9f7c-21470a",
    "status": "success",
    "code": 0,
    "message": "Request processed successfully"
}

Response parameters:

Field Mandatory Type Description
sessionid yes string An unique Id of the session.
status yes string ENUM ['success’, 'decline’, 'error’] Response status
code yes int Response code
message yes string Response description.

Payout via QIWI

Example of the payout request via QIWI:

“Content-type: JSON, XML, POST” –data


{
  "api_version": 1,
  "method": "init",
  "merchant_account": "my_merchant_account",
  "merchant_password": "my_account_password",
  "transaction_unique_id": "transaction_unique_id",
  "mid_reference": "MD0000000D37A5F7",
  "amount": 1.5,
  "currency": "RUB",
  "callback_url": "callback_url",
  "user_id": "user_id",
  "user_ip": "user_ip",
  "user_email": "user_email",
  "qiwi": {
    "wallet_id": "qiwi wallet number"
  }
}

Parameters of the payout request via QIWI:

Field Mandatory Type Description
api_version yes int API version
method yes string Init method
merchant_account yes string Account of the merchant. Given by MaxPay.
merchant_password yes string Password of the merchant. Given by MaxPay.
transaction_unique_id yes string An unique Id of the transaction.
mid_reference yes string MID reference
amount yes float\int Amount of payout request.
currency yes string Currency in ISO format. Examples: USD, EUR, GBP.
callback_url yes string The url of callback. It should have https protocol.
user_id yes string An unique Id of the user.
user_email yes string Email of the user.
user_ip no string User IP address.
user_first_name no string The first name of the user.
user_last_name no string The last name of the user.
user_phone no string Phone number.
user_state no string State of the user.
user_country no string Country of the user.
user_city no string City of the user.
user_address no string Address of the user.
user_zip no string Zip of the user.
qiwi['wallet_id’] yes numeric[9,15] Qiwi wallet id

Example of the response in JSON format:

{
    "sessionid": "5118fcfc-2d9c-492c-9f7c-21470c",
    "status": "success",
    "code": 0,
    "message": "Request processed successfully"
}

Response parameters:

Field Mandatory Type Description
sessionid yes string An unique Id of the session.
status yes string ENUM ['success’, 'decline’, 'error’] Response status
code yes int Response code
message yes string Response description.

Payout via Yandex

Example of the payout request via Yandex:

“Content-type: JSON, XML, POST” –data

{
  "api_version": 1,
  "method": "init",
  "merchant_account": "my_merchant_account",
  "merchant_password": "my_account_password",
  "transaction_unique_id": "transaction_unique_id",
  "mid_reference": "MD0000000D37A6C9",
  "amount": 1.5,
  "currency": "RUB",
  "callback_url": "callback_url",
  "user_id": "user_id",
  "user_ip": "user_ip",
  "user_email": "user_email",
  "yandex": {
    "wallet_id": "yandex wallet number"
  }
}

Parameters of the payout request via Yandex:

Field Mandatory Type Description
api_version yes int API version
method yes string Init method
merchant_account yes string Account of the merchant. Given by MaxPay.
merchant_password yes string Password of the merchant. Given by MaxPay.
transaction_unique_id yes string An unique Id of the transaction.
mid_reference yes string MID reference
amount yes float\int Amount of payout request.
currency yes string Currency in ISO format. Examples: USD, EUR, GBP.
callback_url yes string The url of callback. It should have https protocol.
user_id yes string An unique Id of the user.
user_email yes string Email of the user.
user_ip no string User IP address.
user_first_name no string The first name of the user.
user_last_name no string The last name of the user.
user_phone no string Phone number.
user_state no string State of the user.
user_country no string Country of the user.
user_city no string City of the user.
user_address no string Address of the user.
user_zip no string Zip of the user.
yandex['wallet_id’] yes numeric[9,15] Yandex wallet id

Example of the response in JSON format:

{
    "sessionid": "5118fcfc-2d9c-492c-9f7c-214341",
    "status": "success",
    "code": 0,
    "message": "Request processed successfully"
}

Response parameters:

Field Mandatory Type Description
sessionid yes string An unique Id of the session.
status yes string ENUM ['success’, 'decline’, 'error’] Response status
code yes int Response code
message yes string Response description.

Payout via Paysafecard

Example of the payout request via Paysafecard:

“Content-type: JSON, XML, POST” –data

{
    "api_version": 1,
    "method": "init",
    "merchant_account": "my_merchant_account",
    "merchant_password": "my_merchant_password",
    "transaction_unique_id": "paysafecard_payout_1",
    "mid_reference": "MD0000000D37A843",
    "amount": 10,
    "currency": "EUR",
    "callback_url": "https://test.com/callback",
    "user_ip": "0.0.0.0",
    "paysafecard": {
        "user_id": "merchantclientid5HzDvoZSodKDJ7X7VQKrtestAutomation",
        "user_email": "psc.mypins+9000001500_xZteDVTw@gmail.com",
        "user_first_name": "SuAeRHtjkNJSoraWHZAERgaRdA",
        "user_last_name": "VgObhlCPEXNexGsXqSuIWhzDtt",
        "user_date_of_birth": "1986-06-28"
    }
}

Parameters of the payout request via Paysafecard:

Field Mandatory Type Description
api_version yes int API version
method yes string Init method
merchant_account yes string Account of the merchant. Given by MaxPay.
merchant_password yes string Password of the merchant. Given by MaxPay.
transaction_unique_id yes string An unique Id of the transaction.
mid_reference yes string MID reference
amount yes float\int Amount of payout request.
currency yes string Currency in ISO format. Examples: USD, EUR, GBP.
callback_url yes string The url of callback. It should have https protocol.
user_ip no string User IP address.
paysafecard[user_id] yes string[1, 60] An unique Id of the user
paysafecard[user_email] yes string Email of the user
paysafecard[user_first_name] yes string The first name of the user
paysafecard[user_last_name] yes string The last name of the user
paysafecard[user_date_of_birth] yes string User date of birth in format “1970-01-28”

Example of the response in JSON format:

{
    "sessionid": "5118fcfc-2d9c-492c-9f7c-214341",
    "status": "success",
    "code": 0,
    "message": "Request processed successfully"
}

Response parameters:

Field Mandatory Type Description
sessionid yes string An unique Id of the session.
status yes string ENUM ['success’, 'decline’, 'error’] Response status
code yes int Response code
message yes string Response description.

Payout via Skrill

Example of the payout request via Skrill:

“Content-type: JSON, XML, POST” –data

{
    "api_version": 1,
    "method": "init",
    "merchant_account": "my_merchant_account",
    "merchant_password": "my_merchant_password",
    "transaction_unique_id": "skrill_payout_1503405746",
    "mid_reference": "MD0000000D37A8C1",
    "amount": 1.5,
    "currency": "USD",
    "callback_url": "http://test.com/callback",
    "user_id": "user_id",
    "user_ip": "0.0.0.0",
    "user_email": "user_email",
    "type": "skrill"
}

Parameters of the payout request via Skrill:

Field Mandatory Type Description
api_version yes int API version
method yes string Init method
merchant_account yes string Account of the merchant. Given by MaxPay.
merchant_password yes string Password of the merchant. Given by MaxPay.
transaction_unique_id yes string An unique Id of the transaction.
mid_reference yes string MID reference
amount yes float\int Amount of payout request.
currency yes string Currency in ISO format. Examples: USD, EUR, GBP.
callback_url yes string The url of callback. It should have https protocol.
user_email conditional string Email of the user.
token conditional string Value of the Token. Mandatory if “user_email” not specified. Don’t pass “token” and “user_email” fields together.
user_ip no string User IP address.
type yes string “skrill” for this payment method
user_id no string[1, 60] An unique Id of the user.
user_first_name no string The first name of the user.
user_last_name no string The last name of the user.
user_date_of_birth no string User date of birth in format “1970-01-28”

Example of payout by token for Skrill:

“Content-type: JSON, XML, POST” –data


{
    "api_version": 1,
    "method": "init",
    "merchant_account": "my_merchant_account",
    "merchant_password": "my_merchant_password",
    "transaction_unique_id": "skrill_payout_1503405746",
    "mid_reference": "MD0000000D37A8C1",
    "amount": 1.5,
    "currency": "USD",
    "callback_url": "http://test.com/callback",
    "user_id": "user_id",
    "user_ip": "0.0.0.0",
    "token": "token_value",
    "type": "skrill"
}

Notice: Don’t pass “token” and “user_email” fields together.

Example of the response in JSON format:

{
    "sessionid": "5118fcfc-2d9c-492c-9f7c-214341",
    "status": "success",
    "code": 0,
    "message": "Request processed successfully"
}

Response parameters:

Field Mandatory Type Description
sessionid yes string An unique Id of the session.
status yes string ENUM ['success’, 'decline’, 'error’] Response status
code yes int Response code
message yes string Response description.

Payout via Neteller

Example of the payout request via Neteller:

“Content-type: JSON, XML, POST” –data

{
    "api_version": 1,
    "method": "init",
    "merchant_account": "my_merchant_account",
    "merchant_password": "my_merchant_password",
    "transaction_unique_id": "neteller_payout_1503405746",
    "mid_reference": "MD0000000D37A8C1",
    "amount": 1.5,
    "currency": "USD",
    "callback_url": "http://test.com/callback",
    "user_id": "user_id",
    "user_ip": "0.0.0.0",
    "user_email": "user_email",
    "type": "neteller"
}

Parameters of the payout request via Neteller:

Field Mandatory Type Description
api_version yes int API version
method yes string Init method
merchant_account yes string Account of the merchant. Given by MaxPay.
merchant_password yes string Password of the merchant. Given by MaxPay.
transaction_unique_id yes string An unique Id of the transaction.
mid_reference yes string MID reference
amount yes float\int Amount of payout request.
currency yes string Currency in ISO format. Examples: USD, EUR, GBP.
callback_url yes string The url of callback. It should have https protocol.
user_email conditional string Email of the user.
token conditional string Value of the Token. Mandatory if “user_email” not specified. Don’t pass “token” and “user_email” fields together.
user_ip no string User IP address.
type yes string “neteller” for this payment method
user_id no string An unique Id of the user.
user_first_name no string The first name of the user.
user_last_name no string The last name of the user.
user_date_of_birth no string User date of birth in format “1970-01-28”

Example of payout by token for Neteller:

“Content-type: JSON, XML, POST” –data


{
    "api_version": 1,
    "method": "init",
    "merchant_account": "my_merchant_account",
    "merchant_password": "my_merchant_password",
    "transaction_unique_id": "neteller_payout_1503405746",
    "mid_reference": "MD0000000D37A8C1",
    "amount": 1.5,
    "currency": "USD",
    "callback_url": "http://test.com/callback",
    "user_id": "user_id",
    "user_ip": "0.0.0.0",
    "token": "token_value",
    "type": "neteller"
}

Notice: Don’t pass “token” and “user_email” fields together.

Example of the response in JSON format:

{
    "sessionid": "5118fcfc-2d9c-492c-9f7c-214341",
    "status": "success",
    "code": 0,
    "message": "Request processed successfully"
}

Response parameters:

Field Mandatory Type Description
sessionid yes string An unique Id of the session.
status yes string ENUM ['success’, 'decline’, 'error’] Response status
code yes int Response code
message yes string Response description.

Payout via Ecopayz

Example of the payout request via Ecopayz

“Content-type: JSON, XML, POST” –data

{
    "api_version": 1,
    "method": "init",
    "merchant_account": "my_merchant_account",
    "merchant_password": "my_merchant_password",
    "transaction_unique_id": "ecopayz_payout_1",
    "mid_reference": "MD00000000000001",
    "amount": 1.5,
    "currency": "USD",
    "callback_url": "http://test.com/callback",
    "user_id": "user_id",
    "user_ip": "0.0.0.0",
    "user_email": "user@email.com",
    "wallet_id": "1234567890",
    "type": "ecopayz"
}

Parameters of the payout request via Neteller:

Field Mandatory Type Description
api_version yes int API version
method yes string Init method
merchant_account yes string Account of the merchant. Given by MaxPay.
merchant_password yes string Password of the merchant. Given by MaxPay.
transaction_unique_id yes string An unique Id of the transaction.
mid_reference conditional string MID reference, required for initial payout (when wallet_id is specified), otherwise it’s optional.
amount yes float\int Amount of payout request.
currency yes string Currency in ISO format. Examples: USD, EUR, GBP.
callback_url yes string The url of callback. It should have https protocol.
user_email yes string Email of the user
wallet_id conditional string ID of the wallet of user.
token conditional string Value of the Token. Mandatory if “user_email” not specified. Don’t pass “token” and “user_email” fields together.
user_ip no string User IP address.
type yes string “neteller” for this payment method
user_id no [1,60] string An unique Id of the user.
user_first_name no string The first name of the user.
user_last_name no string The last name of the user.
user_date_of_birth no string User date of birth in format “1970-01-28”

Example of payout by token for Ecopayz:

“Content-type: JSON, XML, POST” –data


{
    "api_version": 1,
    "method": "init",
    "merchant_account": "my_merchant_account",
    "merchant_password": "my_merchant_password",
    "transaction_unique_id": "ecopayz_payout_1",
    "mid_reference": "MD00000000000001",
    "amount": 1.5,
    "currency": "USD",
    "callback_url": "http://test.com/callback",
    "user_id": "user_id",
    "user_ip": "0.0.0.0",
    "user_email": "user@email.com",
    "token": "token_value",
    "type": "ecopayz"
}

Notice: Don’t pass token and wallet_id fields together.

Example of the response in JSON format:

{
    "sessionid": "5118fcfc-2d9c-492c-9f7c-214341",
    "status": "success",
    "code": 0,
    "message": "Request processed successfully"
}

Response parameters:

Field Mandatory Type Description
sessionid yes string An unique Id of the session.
status yes string ENUM ['success’, 'decline’, 'error’] Response status
code yes int Response code
message yes string Response description.

Payout cancellation

Example of payout cancellation request:

“Content-type: JSON, XML, POST” –data

{
    "api_version": 1,
    "method": "cancel",
    "merchant_account": "my_merchant_account",
    "merchant_password": "my_merchant_password",
    "transaction_unique_id": "trx000003"
}

Request parameters of payout cancellation:

Field Mandatory Type Description
api_version yes int API version.
method yes string Cancel method - allows to cancel payout request.
merchant_account yes string Account of the merchant. Given by MaxPay.
merchant_password yes string Password of the merchant. Given by MaxPay.
transaction_unique_id yes string An unique Id of the transaction.

Example of cancellation response in JSON format:

{
    "code": 0,
    "reference": "VDFF000000000001",
    "sessionid": "5118fcfc-2d9c-492c-9f7c-77701d",
    "status": "success",
    "message": "Transaction has been voided"
}

Response parameters of payout cancellation:

Field Mandatory Type Description
code yes int Response code
reference yes string Void transaction reference
sessionid yes string An unique Id of the session.
status yes string ENUM ['success’, 'decline’, 'error’] Response status
message yes string Response message.

Payout callback

Example of callback response in JSON format:

{
    "reference": "PTFF000000000001",
    "transaction_status": "SUCCESS",
    "status": "success",
    "code": 0,
    "message": "Transaction processed successfully!",
    "checkSum": "4804928393234a6cd05f177569147091d7138da25fc61d9ee5add357017239a6"
}

Response parameters of the callback:

Field Mandatory Type Description
reference yes string An unique reference of the transaction.
transaction_status yes string Status of the transaction.
status yes string ENUM ['success’, 'decline’, 'error’] Response status
code yes int Response code
message yes string Response message.
checkSum yes string Check sum value of callback packet

Check sum calculation for callback response

PHP algorithm below shows the calculation logic of “checkSum”:


<?php
$callbackData = array (
    'token' => '43d206b5-af88-4770-9d08-0c7eb17b000',
    'reference' => 'PTFF00000061B7146A8B',
    'transaction_unique_id' => '000453542',
    'status' => 'success',
    'code' => 0,
    'message' => 'Transaction processed successfully',
    'checkSum' => '4804928393234a6cd05f177569147091d7138da25fc61d9ee5add357017239a6',
);
?>

If you need to calculate and compare the value checkSum callback, use the algorithm described below:

Make notice, that all callback values take a part in calculation of the checkSum parameter.

Make notice, that a value of the your_privat_signature is provided by MaxPay integration team.

If fully translate callback shown in the example into the line we get:

Transaction statuses

Payout transaction statuses:

Status Description
NEW transaction payout created
SUCCESS transaction processed successfully
ERROR transaction error
DECLINED transaction declined
VOIDED transaction is voided
PROCESSING transaction processing
PENDING PROCESSING transaction in queue
PROCESSING POSTBACK processing postback

Payout response codes

List of the response codes for payout transactions:

Module Code Value Message (can be extended depending on case)
Payout 3300 GENERAL DECLINE General payout error
3310 VALIDATION DECLINE Payout validation error
3311 INVALID MID REFERENCE Invalid mid reference
3330 UNREGISTERED CARD Unregistered card
FRS 4000 GENERAL RECONCILLIATION ERROR
4001 RECONCILLIATION INCOMPLETE
4002 RECONCILLIATION AMOUNT MISMATCH
4003 RECONCILLIATION COUNT MISMATCH
4004 GENERAL FRS ERROR

Query on demand API

With the help of Maxpay query on demand API you will be able to get the historical data for each transaction processed by you.

Access to Maxpay Qod API

Maxpay live and test query on demand API could be reached by the following URLs:

Web Service URL
Live QOD Service https://gateway.maxpay.com/qod
Test QOD Service https://gateway-sandbox.maxpay.com/qod

Qod Workflow

The Merchant requests transactions data for own account from QOD Service API using the methods defined below. QOD Service API returns reports for each request according for the requested type and transaction report type.

Notification: If merchant use hosted payment page integration, IPs environment should be whitelisted on MaxPay’s side. 1. Click on the button “Account settings” (upper-right corner of merchant portal). 2. Select “Firewall” section. 3. Click on the button “Send new request”. 4. Input test IPs in “Development IPs” string and production IPs in “Production IPs” string. 5. Click on the button “Save”.

Qod Request formats

Qod Response formats

Sample code of QOD request:

https://gateway.maxpay.com/qod/

{
"api_version" : "1.0",
"merchant_account" : "TestQOD",
"merchant_password" : "helloworld",
"time_from" : "1408001644",
"time_to" : "1408001645",
"qod_type" :"transactions",
"order" :"asc",
"page" :"1",
"limit" :"50" 
}

The information should be requested page by page, divided on 1000 records on page. It is possible to request any page by number.

Request parameters are general for all request types

Parameter Name Type Mandatory Rules Description
api_version float\string yes maxLength: { max: 32 } QOD API version
merchant_account string yes maxLength: { max: 32 } QOD account name
merchant_password string yes minLength: { min: 6 }, maxLength: { max: 32 } QOD account password
time_from string yes timestamp Processing transaction time From time, timestamp
time_to string yes timestamp Processing transaction time To time, timestamp
qod_type string yes enum: {values: [“transactions”, ”chargebacks”, “modifications”, "fraudalerts”]} Transaction types are used in the request: transactions \ chargebacks \ modifications
order string no1 enum: {values: [“acs”, ”desc”]} Ordering ASC (by default)/DESC
page string no2 minLength: { min: 1 } maxLength: { max: 12 } Fetching page number. If response contains transactions quantity more than limit, paged fetching is possible. A page contains the Limited number of records (Limit).
limit string no3 minLength: { min: 1 } maxLength: { max: 1000 } Quantity of the fetched transactions. 1000 by default. Can’t be greater than 1000

Note 1: If Order is not defined, uses ASC ordering
Note 2: If Page is not defined, only transactions for 1st page should be fetched according to the set Limit
Note 3: If Limit is not defined, 1000 transactions should be fetched.

Transactions

Example of response in JSON:

{
  "api_version": "1.0",
  "transactions": [
    {
      "transaction_type": "AUTH",
      "status": "SUCCESS",
      "mode": "CC",
      "reference": "ATFF00000000395376F6",
      "base_reference": null,
      "amount": 10,
      "currency": "GBP",
      "merchant": {
        "merchant_account": "TestQOD",
        "descriptor_merchant": "",
        "descriptor_phone": "",
        "merchant_domain_name": "",
        "merchant_product_name": "",
        "merchant_affiliate_id": ""
      },
      "user": {
        "first_name": "User",
        "last_name": "Test",
        "country": "GBR",
        "state": "xxx",
        "city": "London",
        "address": "123 Streetname",
        "zip": "11111",
        "user_ip": "1.1.1.1",
        "user_email": "testemail@testdomain.net",
        "user_phone": "+123456789012"
      },
      "card": {
        "card_holder": "Test Cardholder",
        "brand": "VISA",
        "bin": "400002",
        "last": "1234",
        "exp_month":"06",
       "exp_year":"2015"
      },
      "bank": {
        "id": 1,
        "authcode": "111737",
        "time": 1432542316.3496
      },
      "time": 1420447215.4163,
      "token": "54817d79-8b5c-4c6f-a266-7f2264ed02ad",
      "transaction_unique_id": "accept.1420447212.1505680771",
      "pares": "",
      "code": 0,
      "message": "SUCCESS"
    }
  ],
  "merchant_account": "TestQOD",
  "timestamp": 1432542316.3496,
  "status": "success",
  "code": 0,
  "message": "Transaction processed successfully"
}

Purpose: Use transactions request qod_type allows to get all of transactions processed on the merchant account.

Response parameters:

Parameter Name Type Mandatory Rules Description
api_version float\string yes maxLength: { max: 32 } QOD API version
merchant_account string yes maxLength: { max: 32 } QOD account name
timestamp string yes unix timestamp QOD response time
status string yes maxLength: { max: 10 } Succesful QOD response should contains success status
code string yes length: { size: 4 } QOD response code
message string no maxLength: { max: 255 } QOD response code explanation
transactions array yes Should be array Contains transaction data in array
transaction_type string yes enum(‘SALE’, 'AUTH’, 'AUTH3D’, 'SALE3D’, 'SETTLE’, 'REFUND’, 'VOID’), array element Transaction type
status string yes enum('SUCCESS’, 'DECLINED’, 'ERROR’, 'MALFORMED’, 'PROCESSING’, 'BATCHED’, 'FRAUDED’, 'CHARGEDBACK’, 'REFUNDED’, 'VOIDED’, 'PARTIAL-REFUNDED’, 'WRONGREF’) , array element Transaction status
mode string yes enum('CC’, 'TOKEN’, 'REF’, 'CASCADE’) , array element Transaction mode
reference string yes length: { size: 20 }, array element Maxpay transaction reference
base_reference string\null yes length: { size: 20 }, array element Maxpay transaction base reference if exists
amount float yes decimal(14,4) unsigned, array element Transaction amount
currency string yes length: { size: 3 }, ISO 4217 (alfa-3) , array element Transaction currency
time float\null yes unix timestamp, array element Maxpay transaction time
token string yes length: { size: 36 }, array element Transaction token
transaction_unique_id string yes maxLength: { max: 32 }, array element Transaction unique identifier from merchant side
pares string yes maxLength: { max: 65535 }, array element Transaction PaRes for 3DS transactions
code numeric\null yes length: { size: 4 }, array element Transaction response code, see Response codes table below
message string\null yes maxLength: { max: 255 }, array element Transaction response message, see Response codes table below
merchant array\null yes Should be array Contains transaction merchant data
merchant_account string yes maxLength: { max: 64 }, array element Merchant account has been used to generate transaction
descriptor_merchant string yes maxLength: { max: 255 }, array element Merchant descriptor
descriptor_phone string yes maxLength: { max: 255 }, array element Merchant descriptor phone
merchant_domain_name string yes maxLength: { max: 255 }, array element Merchant website name
merchant_product_name string yes maxLength: { max: 255 }, array element Merchant product name
merchant_affiliate_id string yes maxLength: { max: 255 }, array element Merchant affiliate identifier
user array\null yes Should be array Contains transaction payer data
first_name string yes maxLength: { max: 255 }, array element Payer’s first name
last_name string yes maxLength: { max: 255 }, array element Payer’s last name
country string yes maxLength: { max: 255 }, array element Payer’s country
state string yes maxLength: { max: 255 }, array element Payer’s state
city string yes maxLength: { max: 255 }, array element Payer’s city
address string yes maxLength: { max: 255 }, array element Payer’s address
zip string yes maxLength: { max: 255 }, array element Payer’s ZIP code
user_ip string yes maxLength: { max: 255 }, array element Payer’s IP address
user_email string yes maxLength: { max: 255 }, array element Payer’s email address
user_phone string yes maxLength: { max: 255 }, array element Payer’s phone number
card array\null yes Should be array Contains transaction card data
card_holder string yes maxLength: { max: 100 }, array element Card holder name
brand string yes maxLength: { max: 255 }, array element Card brand name
bin string yes length: { size: 6 }, array element Card BIN data – first 6 digits
last string yes length: { size: 4 }, array element Card number data – last 4 digits
exp_month string yes length: { size: 2 }, array element Card expiration month
exp_year string yes length: { size: 4 }, array element Card expiration year
bank array\null yes Should be array Contains transaction bank data
id int yes maxLength: { max: 20 }, array element Bank identifier code
authcode string yes maxLength: { max: 45 }, array element Bank authorization code
time float\null yes unix timestamp, array element Bank transaction time

Chargebacks

Example of response in JSON:

{
  "api_version": "1.0",
  "chargebacks": [
    {
      "transaction": {
        "transaction_type": "SETTLE",
        "status": "CHARGEDBACK",
        "mode": "REF",
        "reference": "STFF0000000039546C12",
        "base_reference": "ATFF0000000039546BBF",
        "amount": 10,
        "currency": "GBP",
        "merchant": {
          "merchant_account": "TestQOD",
          "descriptor_merchant": "",
          "descriptor_phone": "",
          "merchant_domain_name": "",
          "merchant_product_name": "",
          "merchant_affiliate_id": ""
        },
        "user": {
          "first_name": "User",
          "last_name": "Test",
  "country": "GBR",
          "state": "xxx",
          "city": "London",
          "address": "123 Streetname",
          "zip": "11111",
          "user_ip": "",
          "user_email": "testemail@testdomain.net",
          "user_phone": "+123456789012"
        },
        "card": {
          "card_holder": "Test Cardholder7",
          "brand": "VISA",
          "bin": "400002",
          "last": "1234",
          "exp_month":"06",
         "exp_year":"2015"
        },
        "bank": {
          "id": 1,
          "authcode": "111575",
          "time": null
        },
        "time": 1421938805.751,
        "token": "",
        "transaction_unique_id": "accept.1421938801.604138208",
        "pares": "",
        "code": 0,
        "message": "SUCCESS"
      },
      "chargeback": {
        "status": "OPENED",
        "type": "CHARGEBACK_REVERSAL",
        "reason": "3102",
        "description": "Lost/Stolen card",
        "transaction_type": "CHARGEBACK",
        "transaction_status": "SUCCESS",
        "mode": "REF",
        "reference": "CBFF000000003958A4B1",
        "base_reference": "STFF0000000039546C12",
        "amount": 10,
        "bank": {
          "id": 1,
          "authcode": "",
          "time": 1428576548.6336,
          "update_time": 1428576548.6336
        },
        "time": 1428576550.499
      }
    }
  ],
  "merchant_account": "TestQOD",
  "timestamp": 1432540436.4364,
  "status": "success",
  "code": 0,
  "message": "Transaction processed successfully"
}

Purpose: Use сhargebacks request qod_type allows to get all chargebacked transactions on the merchant account.

Response parameters:

Parameter name Type Mandatory Rules Description
api_version float Yes maxLength: { max: 32 } QOD API version
merchant_account string Yes maxLength: { max: 32 } QOD account name
timestamp string Yes unix timestamp QOD response time
status string Yes maxLength: { max: 10 } Succesful QOD response should contains success status
code string Yes length: { size: 4 } QOD response code
message string No maxLength: { max: 255 } QOD response code explanation
chargebacks array Yes Should be array Contains chargebacked transaction data (initial + chargebacked) in arrays
transaction array\null Yes Should be array Array contains initial transaction data for chargebacked transaction. The same structure as for transactions qod_type is used
chargeback array\null Yes Should be array Contains chargeback transaction data in array
status string Yes maxLength: { max: 255 }, array element Chargeback status
type string Yes maxLength: { max: 255 }, array element Chargeback type
reason string Yes maxLength: { max: 255 }, array element Chargeback reason
description string Yes maxLength: { max: 255 }, array element Chargeback description
transaction_type string Yes enum('CHARGEBACK’), array element Chargeback transaction type
transaction_status string Yes enum('SUCCESS’), array element Chargeback transaction status
mode string Yes enum( 'REF’), array element Chargeback transaction mode
reference string Yes length: { size: 20 }, array element Maxpay chargebacked transaction reference
base_reference string\null Yes length: { size: 20 }, array element Maxpay chargebacked transaction base reference
amount float Yes decimal(14,4) unsigned, array element Chargeback transaction amount
time float\null Yes unix timestamp, array element Maxpay chargeback transaction time
bank array\null Yes Should be array Contains transaction bank data
id int Yes maxLength: { max: 20 }, array element Bank identifier code
authcode string Yes maxLength: { max: 45 }, array element Bank authorization code
time float\null Yes unix timestamp, array element Bank transaction time
update_time float\null Yes unix timestamp, array element Updated bank transaction time

Modifications

Example of response in JSON:

{
  "api_version": "1.0",
  "modifications": [
    {
      "transaction": {
        "transaction_type": "AUTH",
        "status": "SUCCESS",
        "mode": "CASCADE",
        "reference": "ATFF0000000039545997",
        "base_reference": null,
        "amount": 10,
        "currency": "GBP",
        "merchant": {
          "merchant_account": "TestQOD",
          "descriptor_merchant": "",
          "descriptor_phone": "",
          "merchant_domain_name": "",
          "merchant_product_name": "",
          "merchant_affiliate_id": ""
        },
        "user": {
          "first_name": "User",
          "last_name": "Test",
          "country": "GBR",
          "state": "xxx",
          "city": "London",
          "address": "123 Streetname",
          "zip": "11111",
          "user_ip": "1.1.1.1",
          "user_email": "testemail@testdomain.net",
          "user_phone": "+123456789012"
        },
        "card": {
          "card_holder": "Test Cardholder2",
          "brand": "VISA",
          "bin": "400002",
          "last": "1234",
          "exp_month":"06",
          "exp_yeat":"2015"
        },
        "bank": {
          "id": 356,
          "authcode": "authCode_1421931998.6174",
          "time": 1432544175.6856
        },
        "time": 1421931997.4228,
        "token": "54c0f42b-33ac-4cd7-a9dc-0ac4d0d54c0f",
        "transaction_unique_id": "accept.1421931994.715872787",
        "pares": "",
        "code": 0,
        "message": "SUCCESS"
      },
      "modification": {
        "reason": "",
        "description": "",
        "transaction_type": "VOID",
        "transaction_status": "SUCCESS",
        "mode": "MODIFICATION",
        "reference": "VDFF0000000039548C7E",
        "base_reference": "ATFF0000000039545997",
        "amount": 10,
        "bank": {
          "id": 1,
          "authcode": "",
          "time": 1432544175.6856
        },
        "time": 1422280865.0313,
        "update_time": 1422280865.0313,
        "code": 3100,
        "message": "Decline"
      }
    }
  ],
  "merchant_account": "TestQOD",
  "timestamp": 1432544175.6856,
  "status": "success",
  "code": 0,
  "message": "Transaction processed successfully"
} 

Purpose: Use modifications request qod_type allows to get all modified transactions on the merchant account

Response parameters:

Parameter Name Type Mandatory Rules Description
api_version float yes maxLength: { max: 32 } QOD API version
merchant_account string yes maxLength: { max: 32 } QOD account name
timestamp string yes unix timestamp QOD response time
status string yes maxLength: { max: 10 } Succesful QOD response should contains success status
code string yes length: { size: 4 } QOD response code
message string no maxLength: { max: 255 } QOD response code explanation
modifications array yes Should be array Contains modified transaction data (initial + modified) in arrays
transaction array\null yes Should be array Array contains initial transaction data for modified transaction. The same structure as for transactions qod_type is used
modification array\null yes Should be array Contains modified transaction data in array
reason string maxLength: { max: 255 }, array element Modification reason
description string maxLength: { max: 255 }, array element Modification description
transaction_type string yes validTransType, array element Modified transaction type
transaction_status string yes enum('SUCCESS’, 'DECLINED’, 'ERROR’, 'MALFORMED’, 'PROCESSING’, 'BATCHED’, 'FRAUDED’, 'CHARGEDBACK’, 'REFUNDED’, 'VOIDED’, 'PARTIAL-REFUNDED’, 'WRONGREF’), array element Modified transaction status
mode string yes enum('MODIFICATION’), array element Modified transaction mode
reference string yes length: { size: 20 }, array element Maxpay modification transaction reference
base_reference string\null yes length: { size: 20 }, array element Maxpay transaction base reference
amount float yes decimal(14,4) unsigned, array element Modified transaction amount
time float yes unix timestamp, array element Modified transaction time
update_time float yes unix timestamp, array element Modified transaction update time
code numeric\null yes length: { size: 4 }, array element Modified transaction response code, see Response codes table below
message string\null yes maxLength: { max: 255 }, array element Modified transaction response message, see Response codes table below
bank array\null yes Should be array Contains transaction bank data
id int yes maxLength: { max: 20 }, array element Bank identifier code
authcode string yes maxLength: { max: 45 }, array element Bank authorization code
time float yes unix timestamp, array element Bank transaction time

Fraud alerts

Example of response in JSON:

{
  "api_version": "1.0",
  "timestamp": 1495606195.6995,
  "session_id": "4ae6dd-6e8a-592523a8-15c39134850-0524",
  "merchant_account": "my_merchant_account",
  "fraudalerts": [
    {
      "fraud_alert": {
        "transaction": {
          "transaction_type": "SALE",
          "status": "SUCCESS",
          "mode": "CC",
          "reference": "SLFF00000000395BB0C3",
          "base_reference": null,
          "amount": 10.0,
          "currency": "GBP",
          "merchant": {
            "merchant_account": "my_merchant_account",
            "descriptor_merchant": "",
            "descriptor_phone": "",
            "merchant_domain_name": "",
            "merchant_product_name": "",
            "merchant_affiliate_id": ""
          },
          "user": {
            "first_name": "John",
            "last_name": "Doe",
            "country": "USA",
            "state": "NY",
            "city": "New York",
            "address": "123 Streetname",
            "zip": "12100",
            "user_ip": "127.0.0.1",
            "user_email": "testemail@testdomain.net",
            "user_phone": "+18001122334"
          },
          "card": {
            "card_holder": "John Doe",
            "brand": "VISA",
            "bank": "RIVER VALLEY CREDIT UNION",
            "level": "CLASSIC",
            "type": "CREDIT",
            "bin": "400002",
            "last": "5231",
            "exp_month": "07",
            "exp_year": "2019"
          },
          "bank": {
            "id": 356,
            "authcode": "",
            "time": null
          },
          "time": 1472785332.0,
          "token": "57c6cf4e-86e0-449d-b790-66cec8812686",
          "transaction_unique_id": "accept.1472785298.1611860711",
          "pares": "",
          "code": 0,
          "message": "SUCCESS"
        },
        "source": "ethoca",
        "alert_timestamp": 1486986433.0,
        "receive_timestamp": 1486986433.6219,
        "reason_code": "0",
        "reason_description": "test"
      }
    }
  ],
  "status": "success",
  "code": 0,
  "message": "Transaction processed successfully"
}

Purpose: Fraud alerts request qod_type allows to get all fraudulent transactions on the merchant account

Response parameters:

Parameter Name Type Mandatory Rules Description
api_version float yes maxLength: { max: 32 } QOD API version
timestamp string yes unix timestamp QOD response time
session_id string yes maxLength: { max: 36 } Unique ID of the session
merchant_account string yes maxLength: { max: 32 } QOD account name
fraudalerts array yes Should be array Contains fraud transactions data
transactions array yes Should be array Contains transaction data in array
transaction_type string yes enum('SALE’, 'AUTH’, 'AUTH3D’, 'SALE3D’, 'SETTLE’, 'REFUND’, 'VOID’), array element Transaction type
status string yes enum('SUCCESS’, 'DECLINED’, 'ERROR’, 'MALFORMED’, 'PROCESSING’, 'BATCHED’, 'FRAUDED’, 'CHARGEDBACK’, 'REFUNDED’, 'VOIDED’, 'PARTIAL-REFUNDED’, 'WRONGREF’) , array element Transaction status
mode string yes enum('CC’, 'TOKEN’, 'REF’, 'CASCADE’) , array element Transaction mode
reference string yes length: { size: 20 }, array element Maxpay transaction reference
base_reference string\null yes length: { size: 20 }, array element Maxpay transaction base reference if exists
amount float yes decimal(14,4) unsigned, array element Transaction amount
currency string yes length: { size: 3 }, ISO 4217 (alfa-3) , array element Transaction currency
merchant array\null yes Should be array Contains transaction merchant data
merchant_account string yes maxLength: { max: 64 }, array element Merchant account has been used to generate transaction
descriptor_merchant string yes maxLength: { max: 255 }, array element Merchant descriptor
descriptor_phone string yes maxLength: { max: 255 }, array element Merchant descriptor phone
merchant_domain_name string yes maxLength: { max: 255 }, array element Merchant website name
merchant_product_name string yes maxLength: { max: 255 }, array element Merchant product name
merchant_affiliate_id string yes maxLength: { max: 255 }, array element Merchant affiliate identifier
user array\null yes Should be array Contains transaction payer data
first_name string yes maxLength: { max: 255 }, array element Payer’s first name
last_name string yes maxLength: { max: 255 }, array element Payer’s last name
country string yes maxLength: { max: 255 }, array element Payer’s country
state string yes maxLength: { max: 255 }, array element Payer’s state
city string yes maxLength: { max: 255 }, array element Payer’s city
address string yes maxLength: { max: 255 }, array element Payer’s address
zip string yes maxLength: { max: 255 }, array element Payer’s ZIP code
user_ip string yes maxLength: { max: 255 }, array element Payer’s IP address
user_email string yes maxLength: { max: 255 }, array element Payer’s email address
user_phone string yes maxLength: { max: 255 }, array element Payer’s phone number
card array\null yes Should be array Contains transaction card data
card_holder string yes maxLength: { max: 100 }, array element Card holder name
brand string yes maxLength: { max: 255 }, array element Card brand name
bank string yes maxLength: { max: 255 }, array element Issuer bank name
level string yes maxLength: { max: 255 }, array element Card level - CLASSIC, ELECTRON, GOLD etc.
type string yes maxLength: { max: 255 }, array element Card type - CREDIT, PREPAID etc.
bin string yes length: { size: 6 }, array element Card BIN data – first 6 digits
last string yes length: { size: 4 }, array element Card number data – last 4 digits
exp_month string yes length: { size: 2 }, array element Card expiration month
exp_year string yes length: { size: 4 }, array element Card expiration year
bank array\null yes Should be array Contains transaction bank data
id int yes maxLength: { max: 20 }, array element Bank identifier code
authcode string yes maxLength: { max: 45 }, array element Bank authorization code
time float\null yes unix timestamp, array element Bank transaction time
time float\null yes unix timestamp, array element Maxpay transaction time
token string yes length: { size: 36 }, array element Transaction token
transaction_unique_id string yes maxLength: { max: 32 }, array element Transaction unique identifier from merchant side
pares string yes maxLength: { max: 65535 }, array element Transaction PaRes for 3DS transactions
code numeric\null yes length: { size: 4 }, array element Transaction response code, see Response codes table below
message string\null yes maxLength: { max: 255 }, array element Transaction response message, see Response codes table below
source string yes maxLength: { max: 32 } Transaction unique identifier from bank side
alert_timestamp yes string yes unix timestamp
receive_timestamp yes string yes unix timestamp
reason_code string yes length: { size: 4 }, array element Reason code
reason_description string yes maxLength: { max: 255 }, array element Reason description
status string yes maxLength: { max: 10 } Succesful QOD response should contains success status
code string yes length: { size: 4 } QOD response code
message string no maxLength: { max: 255 } QOD response code explanation

Ethoca alerts

This subset of API dedicated for ethoca fraud alert notification handling.

Sample request for receiving ethoca fraud alerts:

https://gateway.maxpay.com/qod/

{
"api_version" : "1.0",
"merchant_account" : "my_merchant_account",
"merchant_password" : "my_account_password",
"qod_type": "ethocaFraudAlerts",
"order" :"asc",
"page" :"1",
"limit" :"1" 
}

Request parameters

Parameter Name Type Description
api_version float\string QOD API version
merchant_account string QOD account name
merchant_password string QOD account password
qod_type string Qod type is ethocaFraudAlerts
order string Ordering ASC (by default)/DESC
page string Fetching page number. If response contains transactions quantity more than limit, paged fetching is possible. A page contains the Limited number of records (Limit).
limit string Quantity of the fetched transactions. 1000 by default. Can’t be greater than 1000

Example of response:

{
   "api_version": "1.0",
   "timestamp": 1509535794.0899,
   "session_id": "1143a5-70f5-598070af-15d9db82df7-35e5",
   "merchant_account": "my_merchant_account",
   "message": "Ethoca fraud alert list",
   "ethocaFraudAlerts": [
            {
         "id": 12,
         "source": "covery",
         "externalId": 1234567890,
         "type": "issuer_alert",
         "state": "none",
         "cardBin": "411111",
         "cardLast4": "1111",
         "alertTimestamp": 1500984840,
         "transactionTimestamp": 1495629501,
         "transactionAmount": 0.05,
         "transactionCurrency": "UAH",
         "is3dSecure": false,
         "arn": null,
         "chargebackAmount": null,
         "chargebackCurrency": null,
         "chargebackReasonCode": null,
         "merchantDescriptor": "test ethoca descriptor",
         "ethocaId": ""
      },
            {
         "id": 15,
         "source": "covery",
         "externalId": 562887,
         "type": "issuer_alert",
         "state": "none",
         "cardBin": "411111",
         "cardLast4": "1111",
         "alertTimestamp": 1500984840,
         "transactionTimestamp": 1495634658,
         "transactionAmount": 1,
         "transactionCurrency": "AUD",
         "is3dSecure": false,
         "arn": null,
         "chargebackAmount": null,
         "chargebackCurrency": null,
         "chargebackReasonCode": null,
         "merchantDescriptor": "test ethoca descriptor",
         "ethocaId": "CSEXNBVFYMXABM7CYIYVOFGWC"
      }
   ],
   "status": "success",
   "code": 0
}

Response parameters:

Parameter Name Type Description
api_version float QOD API version
timestamp string QOD response time
session_id string Unique ID of the session
merchant_account string QOD account name
message string\null Transaction response message, see Response codes table below
ethocaFraudAlerts array Contains Ethoca alert data
id int Fraud alert identifier
source string Fraud alert source
externalId string External fraud alert identifier
type string Fraud alert type
state string Current fraud alert state
cardBin string First 6 numbers of user’s credit card number
cardLast4 string Last 4 numbers of user’s credit card number
alertTimestamp int Alert time (Unix timestamp)
transactionTimestamp int Original transaction time (Unix timestamp)
transactionAmount float Original transaction amount
transactionCurrency string Original transaction currency
is3dSecure boolean or null Was transaction under 3D secure or not (true, false, null for unknown)
arn string Acquirer reference number
chargebackAmount float Chargeback amount
chargebackCurrency string Chargeback currency
chargebackReasonCode int or null Chargeback reason code
merchantDescriptor string Merchant descriptor
ethocaId string Ethoca Id of the alert
status string Succesful QOD response should contains success status
code string QOD response code

Purpose: alert confirmation gives the possibility to confirm alerts receipt and next time confirmed alerts won’t be shown in result list.

Sample request for alert confirmation:

{
  "api_version": "1.0",
  "merchant_account":"my_merchant_account",
  "merchant_password":"my_merchant_password",
  "qod_type": "ethocaFraudAlertConfirm",
  "alertId":"15"
}

Request parameters for alert confirmation

Parameter Name Type Description
api_version float\string QOD API version
merchant_account string QOD account name
merchant_password string QOD account password
qod_type string QOD type is ethocaFraudAlertConfirm
alertId int ID of the alert, received from the list

Example of response:

{
  "api_version":"1.0",
  "timestamp":1500361265.9811,
  "session_id":"4ae6dd-6e6-596db22c-15d547fff09-0c27",
  "message":"Fraud alert `15` has been successfully confirmed",
  "status":"success",
  "code":0
}

Response parameters:

Parameter Name Type Description
api_version float QOD API version
timestamp string QOD response time
session_id string Unique ID of the session
message string\null Transaction response message
status string Succesful QOD response should contains success status
code string QOD response code

Purpose: This functionality allows to confirm multiple Ethoca alerts in the same request.

Sample request of Bulk alert confirmation:

{
  "api_version": "1.0",
  "merchant_account":"my_merchant_account",
  "merchant_password":"my_merchant_password",
  "qod_type": "ethocaBulkFraudAlertConfirm",
  "alertIds": [15]
}

Request parameters for Bulk alert confirmation

Parameter Name Type Description
api_version float\string QOD API version
merchant_account string QOD account name
merchant_password string QOD account password
qod_type string QOD type is ethocaBulkFraudAlertConfirm
alertIds array IDs of the alerts

Example of response:

{
  "api_version":"1.0",
  "timestamp":1510064672.5014,
  "session_id":"f47992-1af9-5a01c21e-15f96de47ba-2f9d",
  "message":"Fraud alerts has been successfully confirmed",
  "status":"success",
  "code":0
}

Response parameters:

Parameter Name Type Description
api_version float QOD API version
timestamp string QOD response time
session_id string Unique ID of the session
message string\null Transaction response message
status string Succesful QOD response should contains success status
code string QOD response code

Purpose: alert feedback gives the possibility to send the result regarding alerts handling to Ethoca.

Sample request for alert feedback:

{
  "api_version": "1.0",
  "merchant_account":"my_merchant_account",
  "merchant_password":"my_merchant_password",
  "qod_type": "ethocaFraudAlertFeedback",
  "alertId":"15",
  "state":"none",
  "refunded":"not_refunded"
}

Request parameters for alert feedback

Parameter Name Type Mandatory Description
api_version float\string yes QOD API version
merchant_account string yes QOD account name
merchant_password string yes QOD account password
qod_type string yes QOD type is ethocaFraudAlertFeedback
alertId int yes ID of the alert, received from the list
state string yes New alert state
refunded string yes Whether transaction was refunded: none, refunded, not_refunded, not_settled
reference string no To specify which Maxpay transaction is processed

List of values for type field

Value Description
empty string
issuer_alert Confirmed fraud
fraudreporter_alert Confirmed fraud
customerdispute_alert Customer dispute

Confirmed fraud states

Value Description
none Fraud alert just received
stopped
partially_stopped
previously_cancelled
missed
notfound
account_suspended
in_progress
shipper_contacted
other

Customer dispute states

Value Description
none Fraud alert just received
resolved
previously_refunded
unresolved_dispute
notfound
other

Example of response:

{
  "api_version":"1.0",
  "timestamp":1500472087.7707,
  "session_id":"4ae6dd-4b8c-596f6312-15d5b1afeb2-0901",
  "message":"Feedback has been successfully sent for fraud alert `15`",
  "status":"success",
  "code":0
}

Response parameters:

Parameter Name Type Description
api_version float QOD API version
timestamp string QOD response time
session_id string Unique ID of the session
message string\null Transaction response message
status string Succesful QOD response should contains success status
code string QOD response code

Request validation specified (not API) response codes

Code Message (can be extended depending on case)
400 Cannot read incoming request data

Empty response

Purpose: The following fieldset should be transmitted in case of empty response data.

Response parameters:

Parameter Name Type Mandatory Rules Description
api_version float yes maxLength: { max: 32 } QOD API version
merchant_account string yes minLength: { min: 6 }, maxLength: { max: 32 } Merchant account name
timestamp string yes unix timestamp Timestamp of response
transactions \ chargebacks \ modifications array\null yes enum: { values: ["transactions”, ”chargebacks”, “modifications”]} qod_type has been used for the request transactions \ chargebacks \ modifications
status string yes maxLength: { max: 10 } Succesful response should contains success status
code string yes Length: {4 } QOD response code
message string no maxLength: { max: 255 } QOD response message

Erroneous response

Example of response in JSON:

{
  "api_version":"1.0",
  "transactions":[],
  "merchant_account":"TestQOD",
  "timestamp":1432216783.6329,
  "status":"error",
  "code":5008,
  "message":"Time from cannot be greater than Time to"
}

Purpose: The following fieldset should be transmitted in case of erroneous request/response data.

Response parameters:

Parameter Name Type Mandatory Rules Description
api_version float yes maxLength: { max: 32 } QOD API version
merchant_account string yes minLength: { min: 6 }, maxLength: { max: 32 } Merchant account name
timestamp string yes unix timestamp Timestamp of response
transactions \ chargebacks \ modifications array\null yes enum: {values: ["transactions”, ”chargebacks”, “modifications”]} shows qod_type has been used for the request: transactions \ chargebacks \ modifications Can be unknown in case id qod_type was absent in request.
status string yes maxLength: { max: 10 } Unsuccesful response should contains error status
code string yes Length: {4 } QOD response code
message string no maxLength: { max: 255 } QOD response message

Response statuses

Code Description
success Succesful QOD response
error Unsuccesful QOD response

Qod API specified response codes

Code Value Message (can be extended depending on case)
5000 QOD GENERAL ERROR QOD general error
5001 QOD UNSUPPORTED API VERSION unsupported QOD API version
5002 INVALID TIME ORDER time from cannot be more than time to

Balance API

Balance API allows to receive balance data for defined timeframe . Merchant_balance method provides multi-currencies balance for all accounts of the Merchant. Please note that mode of the balance ( test/live ) depends on the status of the account.

Web Service URL
Live balance Service https://gateway.maxpay.com/api/frs
Test balance Service https://gateway-sandbox.maxpay.com/api/frs

Example of the balance request: “Content-type: JSON, XML, POST” –data

{
    "api_version":1,
    "method": "MERCHANT_BALANCE",
    "merchant_account":"my_merchant_account",
    "merchant_password":"my_merchant_password",
    "time": 1504044107
}

Parameters of balance request:

Field Mandatory Type Description
api_version yes int API version
method yes string MERCHANT_BALANCE method
merchant_account yes string Account of the merchant. Given by MaxPay.
merchant_password yes string Password of the merchant. Given by MaxPay.
time yes int Selected time.

Example of response in JSON:

{
    "sessionid": "a84112-5464-59a2213d-15e3c1b5764-4f69",
    "timestamp": 1504252222,
    "balance": [
        {
            "currency": "USD",
            "amount": 1601.17
        },
        {
            "currency": "EUR",
            "amount": 0
        }
    ],
    "status": "success",
    "code": 0,
    "message": "Request processed successfully"
}

Parameters of balance response:

Field Mandatory Type Description
sessionid yes string Session ID.
timestamp yes int Balance response time.
balance[currency] yes string Processing currency.
balance[amount] yes float\int Processing amount.
status yes string Status of request.
code yes int Response code.
message yes string Response message.

Response codes

List of response codes

Purpose: The following codes will be transmited in each response. Response Description contains extended information to describe the result of processed transaction.

GENERAL 0 SUCCESS
1 GENERAL SYSTEM ERROR
2 DATABASE ERROR
3 INTERNAL SERVICE ERROR
10 INTERNAL SERVICE COMM ERROR
11 INTERNAL SERVICE TIMEOUT
12 SERVICE SSL ERROR
1000 GENERAL MERCHANT GATE ERROR
1001 GENERAL MERCHANT GATE ERROR
1002 MANDATORY FIELDS ARE MISSING
1003 INTERNAL COMM ERROR
1004 INVALID PARAMETER
1005 UNSUPPORTED API VERSION
2000 GENERAL MMS ERROR
2001 INVALID MERCHANT ACC PASSWORD
2002 COUNTRY RESTRICTIONS
2003 MERCHANT ACC IS NOT ACTIVE
2004 UNAUTHORIZED TRANSACTION
2005 MID NOT ACTIVE
2006 CURRENCY NOT ACTIVE
2007 AMOUNT RESTRICTIONS
2008 IP ADDRESS RESTRICTIONS
2009 MERCHANT NOT ACTIVE
2010 GATE NOT ACTIVE
2011 ENTITY ALREADY EXISTS
2012 ENTITY NOT FOUND
2013 BAD API CREDENTIALS
3000 GENERAL PROCESSING ERROR
3001 TRANSACTION UNIQUE ID ALREADY USED
3002 INVALID TOKEN
3003 INVALID REFFERENCE
3004 VOID NOT POSSIBLE
3005 REFUND NOT POSSIBLE
3006 TRANSACTION IS CB
3007 ILLEGAL INTERVAL
3008 ALREADY VOIDED
3009 ALREADY REFUNDED
3010 ALREADY SETTLED
3011 CARD TYPE NOT SUPPORTED
3012 ACCOUNT IS NOT 3D ENABLED
3013 REQUIRED 3DS
3014 TRANSACTION NOT FOUND FOR CHECK
3015 INVALID CURRENCY
3016 WRONG SETTLE AMOUNT
3017 WRONG MID CREDENTIALS
3018 MID IP ERROR
3019 VALIDATION FAILED
3020 INVALID CHARGEBACK
3021 TRANSACTION BLOCKED
3022 THE AMOUNT IS INCORRECT
3023 TRANSACTION IS ABORTED BY THE CUSTOMER
3024 TRANSACTION IS EXPIRED
3100 GENERAL BANK DECLINE
3101 INSUFFICIENT FUNDS
3102 LOST/STOLEN CARD
3103 3DSECURE AUTH FAILED
3104 INVALID CVV
3105 CARD EXPIRED
3106 INVALID AMOUNT
3107 INVALID CARD NUMBER
3108 REFUND LIMIT EXCEEDED
3109 TIMEOUT
3110 BANK REQUIRED FIELDS ARE MISSING OR INCORRECT
3111 BANK ACCESS ERROR
3112 BANK CARD TYPE NOT SUPPORTED
3113 BANK TRANSACTION TYPE NOT SUPPORTED
3114 BANK CURRENCY NOT SUPPORTED
3115 REFUND NOT POSSIBLE DO VOID
3116 COUNTRY NOT SUPPORTED
3117 MALFORMED BANK RESPONSE
3118 BANK_CONNECTION_ERROR
3119 REFERAL OR RESTRICTED CARD
3120 RISK BANK DECLINE
3121 INVALID ACQUIRER TOKEN
3122 INVALID ACQUIRER REFERENCE
3123 ACQUIRER 3D SECURE IS NOT ENABLED
3124 UNKNOWN ACQUIRER PROCESSING STATUS
3125 ACQUIRER INTERNAL ERROR
3126 WITHDRAWAL FREQUENCY LIMIT EXCEEDED
3127 BANK NEGATIVE LIST
3128 FRAUD BANK DECLINE
3129 AUTHORIZATION DECLINED
ANTIFRAUD 3200 GENERAL FRAUD DECLINE
3201 GENERAL MANUAL REVIEW
3202 VOLUME LIMIT EXCEEDED
3203 REFUND LIMIT EXCEEDED
3220 TRUST LIST FRAUD DECLINE
3221 TRUST LIST MANUAL REVIEW
Payout 3300 GENERAL DECLINE
3310 VALIDATION DECLINE
3311 INVALID MID REFERENCE
3330 UNREGISTERED CARD
FRS 4000 GENERAL RECONCILLIATION ERROR
4001 RECONCILLIATION INCOMPLETE
4002 RECONCILLIATION AMOUNT MISMATCH
4003 RECONCILLIATION COUNT MISMATCH
4004 GENERAL FRS ERROR
QOD 5000 QOD GENERAL ERROR
5001 QOD UNSUPPORTED API VERSION
5002 INVALID TIME ORDER
AUTH 6000 INTERNAL AUTH FAILURE
6001 WRONG CREDENTIALS
6002 ACCESS DENIED
6003 THE USER ALREADY EXISTS
6004 THE USER IS NOT FOUND
6005 THE ROLE IS NOT FOUND
6006 THE PERMISSION IS NOT FOUND
6007 THE TOKEN IS EXPIRED
6008 THE TOKEN IS NOT FOUND
6009 THE USER IS TEMPORARY BLOCKED
6010 THE PASSWORD IS EXPIRED
6011 THE PASSWORD IS INVALID
6012 THE PASSWORD IS PREVIOUSLY USED
7000 INTERNAL PAYMENT GATE ERROR
7101 INTERNAL PAYMENT GATE SENDER ERROR
7102 EXTERNAL COMMUNICATION ERROR
7103 EXTERNAL COMMUNICATION TIMEOUT

Behavior on response codes

RC Transaction result ACTION
0 SUCCESS
1 unknown CHECK transaction status
2 unknown CHECK transaction status
3 unknown CHECK transaction status
10 unknown CHECK transaction status
11 unknown CHECK transaction status
12 unknown CHECK transaction status
1003 unknown CHECK transaction status
6000 unknown CHECK transaction status
OTHER RC DECLINE

API libraries

Maxpay hosted payment page client

For hosted payment page integration you can use our has library on GitHub, where you can find: * Simple payment form * Payment form with pre selected product * Payment form with filled user information * Payment form with custom return urls * Payment form with custom params, params will be returned in callback * Payment form with dynamic products * Valdiate callback data * Rebilling API * Cancel subscription API * Refund API

Magento module

Module for Magento 1.9 is available on GitHub

Installing Copy all files to {site root directory}/ * Login to admin interface * Navigate to menu “System” -> “Configuration” * Open tab “Payment methods” * Choose Maxpay * Enable module

Drupal module

Module for Drupal is available on GitHub

Installing The installation process is described at https://www.drupal.org/node/1897420.

Requirements xautoload module https://www.drupal.org/project/xautoload

Configuration After being installed this module automatically adds MaxPay payment method to checkout. Use “MaxPay” section in Admin panel to configure the module. This module requires “MaxPay public key” and “MaxPay secret key” which are supposed to be taken from https://my.maxpay.com after registration.

WooCommerce plugin

WooCommerce plugin is available on GitHub

Installing The Payment Gateway Plugin * Download the plugin zip file. * Login to your WordPress Admin. Click on Plugins | Add New from the left hand menu. * Click on the “Upload” option, then click “Choose File” to select the zip file from your computer. Once selected, press “OK” and press the “Install Now” button. * Activate the plugin. * Open the settings page for WooCommerce and click the “Payment Gateways,” tab. * Click on the sub tab for “MaxPay.” * Configure your MaxPay Commerce Gateway settings. See below for details.

Obtain Credentials from MaxPay Commerce Gateway To setup your MaxPay Commerce Gateway you will need to enter your public and secret keys.

Connect to WooCommerce To configure the plugin, go to WooCommerce > Settings from the left hand menu, then the top tab “Payment Gateways”. You should see “MaxPay” as an option at the top of the screen. You can select the radio button next to this option to make it the default gateway. * Enable/Disable – check the box to enable MaxPay. * Title – allows you to determine what your customers will see this payment option as on the checkout page. * Description – controls the message that appears under the payment fields on the checkout page. Here you can list the types of cards you accept. * Instructions – controls the message that appears under the description fields on the checkout page. Here you can list the types of cards you accept. * Public_key – enter your public key obtained from MaxPay account. * Secret_key – enter your secret key obtained from MaxPay account. * Save Changes.