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 widget Code example
redirect <input type='hidden' name='payment_method' value='Credit card'>
popup / 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

Use additional parameters for sending them on Pop widget

Parameter Description
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

Use additional parameters for sending them on iFrame widget

Parameter Description
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
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

Use additional parameters for sending them on Redirect form

Parameter Description
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

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”

Let’s look at the sample with French locale.

Type of widget Code example
redirect <input type='hidden' name='locale' value='fr-FR'>
popup / iframe data-locale=“fr-FR”

Custom product API

Pop up example with custom product


<div>
    <form class='maxpayPaymentForm'>
        <script
            src="https://hpp.maxpay.com/client.js" 
            class="maxpayScript" 
            data-iframesrc="https://hpp.maxpay.com/hpp" 
            data-key="pkTest_67pcq3B5i8N7utM7WRNM6ZGvxFmHE4W9" 
            data-signature="199d5077dd7be9a8313954bcc7d4fe7ec9b005beab2ef7e00932cc48e3981f87" 
            data-uniqueuserid="testUserId" 
            data-cardholdername="John Payseed" 
            data-address="New road st 1" 
            data-city="Boston" 
            data-country="USA" 
            data-phone="+1231234123" 
            data-email="johnappleseed@gmail.com"
            data-zip="12100"
            data-success_url="maxpay.com"
            data-decline_url="example.com"  
            data-customproduct='[{"productId":12345,"productType":"subscriptionProduct","productName":"Demo custom product","currency":"USD","amount":100,"productDescription":"Monthly subscription for","subscriptionLength":"2","subscriptionPeriod":"24H","subscriptionEndDate":"1735689600"}]'
            data-type="popup">
        </script>
    </form>
</div>


In case you would like to make the product selection on your side you have a possibility to pass custom products and avoid ‘choose 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. Request method: POST

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 no int The length of subscription product.
subscriptionPeriod no string The period of subscription. Values:
  • 24H;
  • 7D;
  • 30D;
  • 365D.
subscriptionBillingCycles no int Amount of available billing cycles
subscriptionTrialEnd no float The end date of subscription
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.

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 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 send callback data. The number of attempts is limited.

Examples below describe different cases with callback data receiving:

Code Body text
200 OK
200
500 OK

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


Rebilling API

Example request:

<?php
    array (
      'publicKey' => 'pkTest_56137fd80ffc4a639cf91e81941d1f51',
      'signature' => 'bac1c2876f98149d225da91c85956ece1d695809d2a32fff81459c04ff77580b',
      'rebillToken' => '575955d2-5818-4806-8498-7855f3666259',
      'productId' => 'myproductId',
      'uniqueUserId' => 'subscriptionfull',
      'amount' => 100,
      'productName' => 'Monthlysubscription',
      'currency' => 'USD',
      'productType' => 'subscriptionProduct',
      'subscriptionLength' => 1,
      'subscriptionPeriod' => '24H',
      'subscriptionTrialPrice' => 99.9,
      'subscriptionTrialStart' => 1447337995,
      'subscriptionTrialEnd' => 1497339252,
      'subscriptionEndDate' => 1498030452,
      'cardHolderName' => 'John Doe',
      'firstName' => 'John',
      'lastName' => 'Doe',
      'email' => 'johndoe@test.com',
      'country' => 'USA',
      'city' => 'New York',
      'address' => 'Fake street 12',
      'zip' => '12100',
      'phone' => '35422211190'
    )
?>

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.

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

Request parameters:

PARAMETER REQUIRED DESCRIPTION
publicKey yes The public key of the application. Could be found in the general settings of the application.
uniqueUserId yes The unique id of the user in your system.
rebillToken yes The unique payment token which is received after the 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 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.
currency optional Default EUR string. ISO 3 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 optional Applicable only if the product type is ‘subscriptionProduct’ numeric. The length of the subscription product.
subscriptionPeriod optional Applicable only if the product type is ‘subscriptionProduct’ string. The period of subscription. Values:
  • 24H;
  • 7D;
  • 30D;
  • 365D.
subscriptionEndDate optional 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’.
trialLength optional Applicable only if the product type is ‘trialProduct’ numeric. The length of the trial product.
trialPeriod optional Applicable only if the product type is ‘trialProduct’ string. The period of trial. Values:
  • 24H;
  • 7D;
  • 30D;
  • 365D.
postTrialProductId optional 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.
signature yes Signature of the payment page. Calculation is described below.
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.

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. 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 send callback data. The number of attempts is limited.

Examples below describe different cases with callback data receiving:

Code Body text
200 OK
200
500 OK

*Notice all callback values take a part in calculation of the checkSum parameter, 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"
  }
}

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
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 send callback data. The number of attempts is limited.

Examples below describe different cases with callback data receiving:

Code Body text
200 OK
200
500 OK

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


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 method: POST.
Request URL: https://hpp.maxpay.com/api/refund

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"
        }
    }

Callback values

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 send callback data. The number of attempts is limited.

Examples below describe different cases with callback data receiving:

Code Body text
200 OK
200
500 OK

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 Custome 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


<form method="post" action="https://hpp.maxpay.com/hpp">
    <input type="hidden" name="key" value="publick_key_from_Mportal">
    <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>

For example, use the form below:

Find a real example of a signature based on the forme of the above:

Also, 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.

Test credit cards

Card brand Number CVV Expiry date
Visa 2D 4111111111111111 123 [3 digits random] MM - 2 digits random; YY- 18 or greater
Mastercard 2D 5191330000004415 123 [3 digits random] MM - 2 digits random; YY- 18 or greater
Visa 3D 4012000300001003 123 [3 digits random] MM - 2 digits random; YY- 18 or greater
Mastercard 3D 5191330000004415 123 [3 digits random] MM - 2 digits random; YY- 18 or greater

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

Going 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. Also, provide to integration@maxpay.com the value of live callback url. It have to 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:

Test credit cards

Card brand / flow Number CVV Expiry date
Visa 2D 4111111111111111 123 [3 digits random] MM - 2 digits (month); YYYY- 4 digits (year), 2018 or greater
Mastercard 2D 5191330000004415 123 [3 digits random] MM - 2 digits (month); YYYY- 4 digits (year), 2018 or greater
Visa 3D Secure 4012000300001003 123 [3 digits random] MM - 2 digits (month); YYYY- 4 digits (year), 2018 or greater
Mastercard 3D Secure 5191330000004415 123 [3 digits random] MM - 2 digits (month); YYYY- 4 digits (year), 2018 or greater

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

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 Mandatory Rules Example
api_version float/string 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: 6 }, maxLength: { max: 32 } NwAkrkcPAmEcGzghnBwMeDRpXAPFsINg
transaction_type string yes validTransType, enum: { values: [”AUTH”]} AUTH
amount float yes float, maxLength: [0 - 9999999999.99] 5800
currency string yes length: { size: 3 }, ISO 4217 (alfa-3) GBP
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
cvv string no minLength: { min: 3}, maxLength: { max: 4 }, only digits 911
first_name string yes minLength: { min: 1}, maxLength: { max: 32 } Card
last_name string yes minLength: { min: 1 }, maxLength: { max: 32 } Holder
card_holder string yes minLength: { min: 2 }, maxLength: { max: 32 } Card Holder
address string no minLength: { min: 2 } maxLength: { max: 32 } Billing address
city string no minLength: { min: 2 }, maxLength: { max: 32 } New Castle
state string no minLength: { min: 1 }, maxLength: { max: 32 } Texas
zip string yes minLength: { min: 2 }, maxLength: { max: 10 } 235467
country string yes minLength: { min: 2 }, maxLength: { max: 3 }, ISO 3166-1 alpha-3 GBR
user_phone string no minLength: { min: 7 }, maxLength: { max: 15 } 380111111111
user_ email string yes minLength: { min: 6 }, maxLength: { max: 255 }, valid email 14848ff0308f8a396041ddde45de5f8a@gmail.com
user_ip string yes Ipv4Address 192.168.0.1
merchant_user_id string no maxLength: { max: 32 } 6d4a5d94821279725ecb3b0da9319d9b
merchant_domain_name string no maxLength: { max: 255 } vertu.com
merchant_affiliate_id string no maxLength: { max: 255 } 1234
merchant_product_name string no maxLength: { max: 255 } Chips
descriptor_merchant string no maxLength: { max: 255 } merchant.com
descriptor_phone string no maxLength: { max: 255 } 180012345678
pares string no NotEmptyString ABJASDKA+SDKAJ/SGDSAD

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 Mandatory 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 minLength: { min: 1 } maxLength: { max: 32 } NwAkrkcPAmEcGzghnBwMeDRpXAPFsINg
token string yes length: { size: 36 } 14848ff0308f8a396041ddde45de5f8ffffa
reference string yes length: { size: 20 } ATFF1235432423
timestamp string yes unix timestamp 1408001694
authсode string yes maxLength: { max: 24 } 1111513
status string yes { SUCCESS, DECLINE, ERROR } SUCCESS
code numeric yes Returns response code for the transaction Response codes table
message string yes Returns explanation of the response code Response codes table

After the AUTH transaction has been processed a merchant have to send the following transactions:

Auth (with token) transaction

Sample code of AUTH (with 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 Mandatory Rules Example
api_version float/string 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: 6 }, maxLength: { max: 32 } NwAkrkcPAmEcGzghnBwMeDRpXAPFsINg
transaction_type string yes validTransType, enum: { values: [”AUTH”]} AUTH
amount float yes float, maxLength: [0 - 9999999999.99] 5800
currency string yes length: { size: 3 }, ISO 4217(alfa-3) GBP
cvv string no minLength: { min: 3}, maxLength: { max: 4 }, only digits 911
first_name string yes minLength: { min: 1}, maxLength: { max: 32 } Card
last_name string yes minLength: { min: 1 }, maxLength: { max: 32 } Holder
card_holder string yes minLength: { min: 2 }, maxLength: { max: 32 } Card Holder
address string no minLength: { min: 2 } maxLength: { max: 32 } Billing address
city string no minLength: { min: 2 }, maxLength: { max: 32 } New Castle
state string no minLength: { min: 1 }, maxLength: { max: 32 } Texas
zip string yes minLength: { min: 2 }, maxLength: { max: 10 } 235467
country string yes minLength: { min: 2 }, maxLength: { max: 3 }, ISO 3166-1 alpha-3 GBR
user_phone string no minLength: { min: 7 }, maxLength: { max: 15 } 380111111111
user_ email string yes minLength: { min: 6 }, maxLength: { max: 255 }, valid email 14848ff0308f8a396041ddde45de5f8a@gmail.com
user_ip string yes Ipv4Address 192.168.0.1
merchant_user_id string no maxLength: { max: 32 } 6d4a5d94821279725ecb3b0da9319d9b
merchant_domain_name string no maxLength: { max: 255 } vertu.com
merchant_affiliate_id string no maxLength: { max: 255 } 1234
merchant_product_name string no maxLength: { max: 255 } Chips
descriptor_merchant string no maxLength: { max: 255 } merchant.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

Sample code of AUTH (with 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":" ATFF0000000039FDAEEF",
    "timestamp":1408001694,
    "authcode":"authcode_1544565466.22",
    "status":"error",
    "code":3100,
    "message":"Decline"
}

Response parameters:

Parameter Name Type Mandatory 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 minLength: { min: 1 } maxLength: { max: 32 } NwAkrkcPAmEcGzghnBwMeDRpXAPFsINg
token string yes length: { size: 36 } 14848ff0308f8a396041ddde45de5f8ffffa
reference string yes length: { size: 20 } ATFF1235432423
timestamp string yes unix timestamp 1408001694
authсode string yes maxLength: { max: 24 } 1111513
status string yes { SUCCESS, DECLINE, ERROR } SUCCESS
code numeric yes Returns response code for the transaction Response codes table
message string yes Returns explanation of the response code Response codes table

After the AUTH (with token) transaction has been processed a merchant depending on business requirements has ability but not forced to send the following transactions:

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 mandatory 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 Mandatory Rules Example
api_version float/string 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: 6 }, maxLength: { max: 32 } NwAkrkcPAmEcGzghnBwMeDRpXAPFsINg
transaction_type string yes validTransType, enum: { values: [”AUTH3D”]} AUTH3D
amount float yes float, maxLength: [0 - 9999999999.99] 5800
currency string yes length: { size: 3 }, ISO 4217 (alfa-3) GBP
card_number string yes minLength: { min: 13 }, maxLength: { max: 19 } only digits, Luhn algorithm
  • 4012000300001003
  • 5191330000004415
card_exp_month string yes length: { size: 2 }, only digits 05
card_exp_year string yes length: { size: 4 }, only digits 2016
cvv string no minLength: { min: 3}, maxLength: { max: 4 }, only digits 911
first_name string yes minLength: { min: 1}, maxLength: { max: 32 } Card
last_name string yes minLength: { min: 1 }, maxLength: { max: 32 } Holder
card_holder string yes minLength: { min: 2 }, maxLength: { max: 32 } Card Holder
address string no minLength: { min: 2 } maxLength: { max: 32 } Billing address
city string no minLength: { min: 2 }, maxLength: { max: 32 } New Castle
state string no minLength: { min: 1 }, maxLength: { max: 32 } Texas
zip string yes minLength: { min: 2 }, maxLength: { max: 10 } 235467
country string yes minLength: { min: 2 }, maxLength: { max: 3 }, ISO 3166-1 alpha-3 GBR
user_phone string no minLength: { min: 7 }, maxLength: { max: 15 } 380111111111
user_ email string yes minLength: { min: 6 }, maxLength: { max: 255 }, valid email 14848ff0308f8a396041ddde45de5f8a@gmail.com
user_ip string yes Ipv4Address 192.168.0.1
merchant_user_id string no maxLength: { max: 32 } 6d4a5d94821279725ecb3b0da9319d9b
merchant_domain_name string no maxLength: { max: 255 } vertu.com
merchant_affiliate_id string no maxLength: { max: 255 } 1234
merchant_product_name string no maxLength: { max: 255 } Chips
descriptor_merchant string no maxLength: { max: 255 } merchant.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 Mandatory 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/JWIK1LsvAqNNpZSEA8BLS1UhWMwFolC4sR2Wvj72jQpre TDzuzueDQL21QwNt4w2ghGYMWkTE7Myo5Rr5AnO+gRWMdvrCbwyYTMeEkcG9s
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 numeric yes Returns response code for the transaction Response codes table
message string yes Returns explanation of the response code Response codes 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>

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

Auth3D (with token) transaction

Sample code of AUTH3D (with 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 Mandatory Rules Example
api_version float/string 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: 6 }, maxLength: { max: 32 } NwAkrkcPAmEcGzghnBwMeDRpXAPFsINg
transaction_type string yes validTransType, enum: { values: [”AUTH3D”]} AUTH3D
amount float yes float, maxLength: [0 - 9999999999.99] 5800
currency string yes length: { size: 3 }, ISO 4217 (alfa-3) GBP
cvv string no minLength: { min: 3}, maxLength: { max: 4 }, only digits 911
first_name string yes minLength: { min: 1}, maxLength: { max: 32 } Card
last_name string yes minLength: { min: 1 }, maxLength: { max: 32 } Holder
card_holder string yes minLength: { min: 2 }, maxLength: { max: 32 } Card Holder
address string no minLength: { min: 2 } maxLength: { max: 32 } Billing address
city string no minLength: { min: 2 }, maxLength: { max: 32 } New Castle
state string no minLength: { min: 1 }, maxLength: { max: 32 } Texas
zip string yes minLength: { min: 2 }, maxLength: { max: 10 } 235467
country string yes minLength: { min: 2 }, maxLength: { max: 3 }, ISO 3166-1 alpha-3 GBR
user_phone string no minLength: { min: 7 }, maxLength: { max: 15 } 380111111111
user_ email string yes minLength: { min: 6 }, maxLength: { max: 255 }, valid email 14848ff0308f8a396041ddde45de5f8a@gmail.com
user_ip string yes Ipv4Address 192.168.0.1
merchant_user_id string no maxLength: { max: 32 } 6d4a5d94821279725ecb3b0da9319d9b
merchant_domain_name string no maxLength: { max: 255 } vertu.com
merchant_affiliate_id string no maxLength: { max: 255 } 1234
merchant_product_name string no maxLength: { max: 255 } Chips
descriptor_merchant string no maxLength: { max: 255 } merchant.com
descriptor_phone string no maxLength: { max: 255 } 180012345678
token string yes length: { size: 36 } 14848ff0308f8a396041ddde45de5f8ffffa

Sample code of AUTH3D (with 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 Mandatory 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
toke 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/JWIK1LsvAqNNpZSEA8BLS1UhWMwFolC4sR2Wvj72jQpre TDzuzueDQL21QwNt4w2ghGYMWkTE7Myo5Rr5AnO+gRWMdvrCbwyYTMeEkcG9s
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 numeric yes Returns response code for the transaction Response codes table
message string yes Returns explanation of the response code Response codes 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>

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

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":19.99,
    "currency":"USD",
    "reference":"STFF0000000039FDAEC1"
}

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

Request parameters:

Parameter Name Type Mandatory 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: 6 }, maxLength: { max: 32 } NwAkrkcPAmEcGzghnBwMeDRpXAPFsINg
transaction_type string yes validTransType, enum: { values: [“SETTLE”]} SETTLE
amount float yes float, maxLength: [0 - 9999999999.999] 5800
currency string yes length: { size: 3 }, ISO 4217 (alfa-3) GBP
reference string yes length: { size: 20 } 14848ff0308f8a396041ddde45de5f8ffffa
merchant_domain_name string no maxLength: { max: 255} merchant.com
merchant_affiliate_id string no maxLength: { max: 255} 1
merchant_user_id string no maxLength: { max: 32} 6d4a5d94821279725ecb3b0da9319d9b
merchant_product_name string no maxLength: { max: 255} Test product
descriptor_merchant string no maxLength: { max: 255} merchant.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 Mandatory 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
token string yes length: { size: 36 } 14848ff0308f8a396041ddde45de5f8ffffa
authсode string yes maxLength: { max: 24 } 1111513
reference string yes length: { size: 20 } ATFF1235432423
transaction_unique_id string yes minLength: { min: 1 } maxLength: { max: 32 } NwAkrkcPAmEcGzghnBwMeDRpXAPFsINg
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
timestamp string yes unix timestamp 1408001694

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 mandatory transmitted in the request.

Request parameters:

Parameter Name Type Mandatory Rules Example
api_version float/string 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: 6 }, maxLength: { max: 32 } NwAkrkcPAmEcGzghnBwMeDRpXAPFsINg
transaction_type string yes validTransType, enum: { values: [”SALE”]} SALE
reference string no length: { size: 20 } Mandatory for 3Ds flow 14848ff0308f8a396041ddde45de5f8ffffa
amount float yes float, maxLength: [0 - 9999999999.99] 5800.99
currency string yes length: { size: 3 }, ISO 4217 (alfa-3) GBP
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
cvv string no minLength: { min: 3}, maxLength: { max: 4 }, only digits 911
first_name string yes minLength: { min: 1}, maxLength: { max: 32 } Card
last_name string yes minLength: { min: 1 }, maxLength: { max: 32 } Holder
card_holder string yes minLength: { min: 2 }, maxLength: { max: 32 } Card Holder
address string no minLength: { min: 2 } maxLength: { max: 32 } Billing address
city string no minLength: { min: 2 }, maxLength: { max: 32 } New Castle
state string no minLength: { min: 1 }, maxLength: { max: 32 } Texas
zip string yes minLength: { min: 2 }, maxLength: { max: 10 } 235467
country string yes minLength: { min: 2 }, maxLength: { max: 3 }, ISO 3166-1 alpha-3 GBR
user_phone string no minLength: { min: 7 }, maxLength: { max: 15 } 380111111111
user_ email string yes minLength: { min: 6 }, maxLength: { max: 255 }, valid email 14848ff0308f8a396041ddde45de5f8a@gmail.com
user_ip string yes Ipv4Address 192.168.0.1
merchant_user_id string no maxLength: { max: 32 } 6d4a5d94821279725ecb3b0da9319d9b
merchant_domain_name string no maxLength: { max: 255 } vertu.com
merchant_affiliate_id string no maxLength: { max: 255 } 1234
merchant_product_name string no maxLength: { max: 255 } Chips
descriptor_merchant string no maxLength: { max: 255 } merchant.com
descriptor_phone string no maxLength: { max: 255 } 180012345678
pares string no NotEmptyString, Mandatory for 3Ds flow ABJASDKA+SDKAJ/SGDSAD

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 Mandatory 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 minLength: { min: 1 } maxLength: { max: 32 } NwAkrkcPAmEcGzghnBwMeDRpXAPFsINg
token string yes length: { size: 36 } 14848ff0308f8a396041ddde45de5f8ffffa
reference string yes length: { size: 20 } ATFF1235432423
timestamp string yes unix timestamp 1408001694
authсode string yes maxLength: { max: 24 } 1111513
status string yes { SUCCESS, DECLINE, ERROR } SUCCESS
code numeric yes Returns response code for the transaction Response codes table
message string yes Returns explanation of the response code Response codes 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 (with token) transaction

Example of SALE (with 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 Mandatory Rules Example
api_version float/string 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: 6 }, maxLength: { max: 32 } NwAkrkcPAmEcGzghnBwMeDRpXAPFsINg
transaction_type string yes validTransType, enum: { values: [”SALE”]} SALE
amount float yes float, maxLength: [0 - 9999999999.99] 5800
currency string yes length: { size: 3 }, ISO 4217 (alfa-3) GBP
cvv string no minLength: { min: 3}, maxLength: { max: 4 }, only digits 911
first_name string yes minLength: { min: 1}, maxLength: { max: 32 } Card
last_name string yes minLength: { min: 1 }, maxLength: { max: 32 } Holder
card_holder string yes minLength: { min: 2 }, maxLength: { max: 32 } Card Holder
address string no minLength: { min: 2 } maxLength: { max: 32 } Billing address
city string no minLength: { min: 2 }, maxLength: { max: 32 } New Castle
state string no minLength: { min: 1 }, maxLength: { max: 32 } Texas
zip string yes minLength: { min: 2 }, maxLength: { max: 10 } 235467
country string yes minLength: { min: 2 }, maxLength: { max: 3 }, ISO 3166-1 alpha-3 GBR
user_phone string no minLength: { min: 7 }, maxLength: { max: 15 } 380111111111
user_ email string yes minLength: { min: 6 }, maxLength: { max: 255 }, valid email 14848ff0308f8a396041ddde45de5f8a@gmail.com
user_ip string yes Ipv4Address 192.168.0.1
merchant_user_id string no maxLength: { max: 32 } 6d4a5d94821279725ecb3b0da9319d9b
merchant_domain_name string no maxLength: { max: 255 } vertu.com
merchant_affiliate_id string no maxLength: { max: 255 } 1234
merchant_product_name string no maxLength: { max: 255 } Chips
descriptor_merchant string no maxLength: { max: 255 } merchant.com
descriptor_phone string no maxLength: { max: 255 } 180012345678
token string yes length: { size: 36 } 14848ff0308f8a396041ddde45de5f8ffffa

Example of SALE (with 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 Mandatory 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 minLength: { min: 1 } maxLength: { max: 32 } NwAkrkcPAmEcGzghnBwMeDRpXAPFsINg
token string yes length: { size: 36 } 14848ff0308f8a396041ddde45de5f8ffffa
reference string yes length: { size: 20 } ATFF1235432423
timestamp string yes unix timestamp 1408001694
authсode string yes maxLength: { max: 24 } 1111513
status string yes { SUCCESS, DECLINE, ERROR } SUCCESS
code numeric yes Returns response code for the transaction Response codes table
message string yes Returns explanation of the response code Response codes table

After the SALE 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 Mandatory Rules Example
api_version float/string 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: 6 }, maxLength: { max: 32 } NwAkrkcPAmEcGzghnBwMeDRpXAPFsINg
transaction_type string yes validTransType, enum: { values: [”SALE3D”]} SALE3D
amount float yes float, maxLength: [0 - 9999999999.99] 5800
currency string yes length: { size: 3 }, ISO 4217 (alfa-3) GBP
card_number string yes minLength: { min: 13 }, maxLength: { max: 19 } only digits, Luhn algorithm
  • 4012000300001003
  • 5191330000004415
card_exp_month string yes length: { size: 2 }, only digits 05
card_exp_year string yes length: { size: 4 }, only digits 2016
cvv string no minLength: { min: 3}, maxLength: { max: 4 }, only digits 911
first_name string yes minLength: { min: 1}, maxLength: { max: 32 } Card
last_name string yes minLength: { min: 1 }, maxLength: { max: 32 } Holder
card_holder string yes minLength: { min: 2 }, maxLength: { max: 32 } Card Holder
address string no minLength: { min: 2 } maxLength: { max: 32 } Billing address
city string no minLength: { min: 2 }, maxLength: { max: 32 } New Castle
state string no minLength: { min: 1 }, maxLength: { max: 32 } Texas
zip string yes minLength: { min: 2 }, maxLength: { max: 10 } 235467
country string yes minLength: { min: 2 }, maxLength: { max: 3 }, ISO 3166-1 alpha-3 GBR
user_phone string no minLength: { min: 7 }, maxLength: { max: 15 } 380111111111
user_ email string yes minLength: { min: 6 }, maxLength: { max: 255 }, valid email 14848ff0308f8a396041ddde45de5f8a@gmail.com
user_ip string yes Ipv4Address 192.168.0.1
merchant_user_id string no maxLength: { max: 32 } 6d4a5d94821279725ecb3b0da9319d9b
merchant_domain_name string no maxLength: { max: 255 } vertu.com
merchant_affiliate_id string no maxLength: { max: 255 } 1234
merchant_product_name string no maxLength: { max: 255 } Chips
descriptor_merchant string no maxLength: { max: 255 } merchant.com
descriptor_phone string no maxLength: { max: 255 } 180012345678
callback_url string yes maxLength: { max: 255 } https://testshop.com/success
redirect_url string yes maxLength: { max: 255 } http://testshop.com/redirect

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 Mandatory 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
eci numeric 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 numeric yes Returns response code for the transaction Response codes table
message string yes Returns explanation of the response code Response codes table

Sample code of callback on SALE3D transaction 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": "",
    "status":"success",
    "code":0,
    "message":"transaction processed successfully",
    "signature":"7be7f8abad70931c177bedb88993405ab88aee79e0a54b8411f02eadc27f3476"
}

According to SALE3D flow Maxpay initiates SALE transaction automatically and sends the response to predefined Merchant callback URL.

Callback SALE response parameters:

Parameter Name Type Mandatory 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 } 55882952-a344-40ce-af84-173c025bd8bd
transaction_unique_id string yes maxLength: { max: 32 }, minLength: { min: 1 } 1434986821.1471529083
token string yes length: { size: 36 } 55880d83-3fb0-43eb-a18f-173c025bd8bd
reference string yes length: { size: 20 } S3FF00000000395DA2C3
timestamp string yes unix timestamp 1434986844
authcode string yes maxLength: { max: 24 } 1434986845.693
status string yes { SUCCESS, DECLINE, ERROR } SUCCESS
code numeric yes Returns response code for the transaction Response codes table
message string yes Returns explanation of the response code Response codes table
signature * string yes maxLength: { max: 32 } 7be7f8abad70931c177bedb88993405ab88aee79e0a54b8411f02eadc27f3476

* The signature field contains hash of the response data and has to be validated on the Merchant side using the following hash algorithm for alphabetically sorted and concatenated fields data: hash(‘sha256’,’($key[0]=$val[0].$key[n]=$val[n].$key[n+1]=$val[n+1].$secret’), where $key equals field name, $val equals field value, $secret equals hashed using sha512 Merchant account password value.

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

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

Sale3D (with token) transaction

Sample code of SALE3D (with 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 Mandatory Rules Example
api_version float/string 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: 6 }, maxLength: { max: 32 } NwAkrkcPAmEcGzghnBwMeDRpXAPFsINg
transaction_type string yes validTransType, enum: { values: [”SALE3D”]} SALE3D
amount float yes float, maxLength: [0 - 9999999999.999] 5800
currency string yes length: { size: 3 }, ISO 4217 (alfa-3) GBP
cvv string no minLength: { min: 3}, maxLength: { max: 4 }, only digits 911
first_name string yes minLength: { min: 1}, maxLength: { max: 32 } Card
last_name string yes minLength: { min: 1 }, maxLength: { max: 32 } Holder
card_holder string yes minLength: { min: 2 }, maxLength: { max: 32 } Card Holder
address string no minLength: { min: 2 } maxLength: { max: 32 } Billing address
city string no minLength: { min: 2 }, maxLength: { max: 32 } New Castle
state string no minLength: { min: 1 }, maxLength: { max: 32 } Texas
zip string yes minLength: { min: 2 }, maxLength: { max: 10 } 235467
country string yes minLength: { min: 2 }, maxLength: { max: 3 }, ISO 3166-1 alpha-3 GBR
user_phone string no minLength: { min: 7 }, maxLength: { max: 15 } 380111111111
user_ email string yes minLength: { min: 6 }, maxLength: { max: 255 }, valid email 14848ff0308f8a396041ddde45de5f8a@gmail.com
user_ip string yes Ipv4Address 192.168.0.1
merchant_user_id string no maxLength: { max: 32 } 6d4a5d94821279725ecb3b0da9319d9b
merchant_domain_name string no maxLength: { max: 255 } vertu.com
merchant_affiliate_id string no maxLength: { max: 255 } 1234
merchant_product_name string no maxLength: { max: 255 } Chips
descriptor_merchant string no maxLength: { max: 255 } merchant.com
descriptor_phone string no maxLength: { max: 255 } 180012345678
token string yes length: { size: 36 } 14848ff0308f8a396041ddde45de5f8ffffa
callback_url string yes maxLength: { max: 255 } https://testshop.com/success
redirect_url string yes maxLength: { max: 255 } http://testshop.com/redirect

Example of SALE3D (with 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 Mandatory 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
eci numeric 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 numeric yes Returns response code for the transaction Response codes table
message string yes Returns explanation of the response code Response codes table

Sample code of callback on SALE3D transaction 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": "",
    "status":"success",
    "code":0,
    "message":"transaction processed successfully",
    "signature":"7be7f8abad70931c177bedb88993405ab88aee79e0a54b8411f02eadc27f3476"
}

According to SALE3D flow Maxpay initiates SALE transaction automatically and sends the response to predefined Merchant callback URL.

Callback SALE response parameters:

Parameter Name Type Mandatory 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 } 55882952-a344-40ce-af84-173c025bd8bd
transaction_unique_id string yes maxLength: { max: 32 }, minLength: { min: 1 } 1434986821.1471529083
token string yes length: { size: 36 } 55880d83-3fb0-43eb-a18f-173c025bd8bd
reference string yes length: { size: 20 } S3FF00000000395DA2C3
timestamp string yes unix timestamp 1434986844
authcode string yes maxLength: { max: 24 } 1434986845.693
status string yes { SUCCESS, DECLINE, ERROR } SUCCESS
code numeric yes Returns response code for the transaction Response codes table
message string yes Returns explanation of the response code Response codes table
signature * string yes maxLength: { max: 32 } 7be7f8abad70931c177bedb88993405ab88aee79e0a54b8411f02eadc27f3476

* The signature field contains hash of the response data and has to be validated on the Merchant side using the following hash algorithm for alphabetically sorted and concatenated fields data: hash(‘sha256’,’($key[0]=$val[0].$key[n]=$val[n].$key[n+1]=$val[n+1].$secret’), where $key equals field name, $val equals field value, $secret equals hashed using sha512 Merchant account password value.

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

After the SALE transaction has been processed a merchant depending on business requirements has ability but not forced 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 Mandatory 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: [“REFUND”]} REFUND
amount float yes float, maxLength: [0 - 9999999999.999] 5800
currency string yes length: { size: 3 }, ISO 4217 (alfa-3) GBP
reference string yes length: { size: 20 } SLFF0000000039FDAEGG reference of SALE, SALE3D or SETTLE transaction
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 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 Mandatory 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 minLength: { min: 1 } maxLength: { max: 32 } NwAkrkcPAmEcGzghnBwMeDRpXAPFsINg
token string yes length: { size: 36 } 14848ff0308f8a396041ddde45de5f8ffffa
reference string yes length: { size: 20 } ATFF1235432423
timestamp string yes unix timestamp 1408001694
authсode string yes maxLength: { max: 24 } 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 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 Mandatory 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 Mandatory 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 minLength: { min: 1 } maxLength: { max: 32 } NwAkrkcPAmEcGzghnBwMeDRpXAPFsINg
token string yes length: { size: 36 } 14848ff0308f8a396041ddde45de5f8ffffa
reference string yes length: { size: 20 } ATFF1235432423
timestamp string yes unix timestamp 1408001694
authсode string yes maxLength: { max: 24 } 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 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 Mandatory 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 Mandatory 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 Mandatory 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 Mandatory 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 mandatory fields must be transmitted in the response.

Response parameters:

Parameter Name Type Mandatory 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 mandatory fields must be transmitted in the response.

Response parameters:

Parameter Name Type Mandatory 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"]
        }
    ]
}

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

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 yes 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_number yes luhn string Card number.
card_cvv no numeric[3,4] CVV of the card consists of 3 or 4 digits.
card_holder no string Cardholder name
card_exp_year no numeric[4] Expiry year consists of 4 digits.
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.

Atlternative methdos

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
my_merchant_account yes string Account of the merchant. Given by MaxPay.
my_account_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 yes 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 yes array Params for qiwi. See full param description below
Field Mandatory Type Description
qiwi['wallet_id’] yes numeric[9,15] API version

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.

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
my_merchant_account yes string Account of the merchant. Given by MaxPay.
my_account_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 yes 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 yes array Yandex.Money wallet id
Field Mandatory Type Description
yandex['wallet_id’] yes numeric[9,15] API version

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 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 yes 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.
token yes string The value of the Token.
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 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!"
}

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.

Transaction statuses

Payout transaction statuses:

Status Description
NEW transaction payout created
SUCCESS transaction processed successfully
ERROR transaction error
DECLINED transaction declined
CANCELED transaction is canceled
VALIDATION transaction on validation
PROCESSING transaction processing
PENDING PROCESSING transaction in queue
PENDING POSTBACK waiting for postback
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

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.

Qod Request formats

Qod Response formats

Sample code example 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",
          "custom_fields": {
            "custom_bank_transaction_id": "EM000000000000000006JC1",
            "custom_descriptor_merchant": "",
            "custom_mid_id": "1",
            "custom_mid_name": "testmid"
          }
        },
        "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
custom_fields array\null yes Should be array Contains custome_fields data
custom_bank_transaction_id string yes maxLength: { max: 32 }, array element Transaction unique identifier from bank side
custom_descriptor_merchant string yes maxLength: { max: 255 }, array element Merchant descriptor
custom_mid_id string yes maxLength: { max: 20 }, array element Custome MID ID
custom_mid_name string yes maxLength: { max: 32 }, array element Custome MID name
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

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

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
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:

Magento module

Module for Magento 1.9 is available on GitHub The installation process is described on GItHub.