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.

HPP integration flow

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

General settings

Fill up the fields:

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

Create product

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

Payment methods

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

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

Payment form

Maxpay’s payment form customizer allows you to:

Pop Up payment form

Example of the Pop Up payment form:


<div>
    <form class='pspPaymentForm'>
        <script src="https://hpp.maxpay.com/paymentPage.js"
            class="pspScript" 
            data-iframesrc="https://hpp.maxpay.com/hpp"
            data-buttontext="Pay!" 
            data-name="Application" 
            data-key="pkTest_67pcq3B5i8N7utM7WRNM6ZGvxFmHE4W9" 
            data-signature="199d5077dd7be9a8313954bcc7d4fe7ec9b005beab2ef7e00932cc48e3981f87"
            data-uniqueuserid="user123"
            data-payment_method='Credit card'
            data-uniqueTransactionId='transactionId123'
            data-productPublicIde='productId120'
            data-email='john.doe@gmail.com'
            data-firstname='John'
            data-lastname='Doe'
            data-phone='1800080048'
            data-address='Address 123'
            data-city='New York'
            data-country='USA'
            data-zip='12100'
            data-success_url='https://merchant.com/successful-purchase'
            data-decline_url='https://merchant.com/unsuccessful-purchase'
            data-back_url='https://merchant.com'
            data-locale='en-US'
            data-displaybuybutton="true" 
            data-type="popup">
        </script>
    </form>
</div>

Parameters of the Pop Up payment form

Parameter Validation Description
data-buttontext 32 characters text of the button
data-name constant value name of your payment application
data-key constant value public key from general settings
data-signature calculated value signature of the payment widget. Information about a signature generation below
data-uniqueuserid 1-64 characters merchant’s unique user ID (unique user ID in merchant’s system)
data-displaybuybutton true or false allows to display the bu button
data-type constant value, integrated integrated value for iFrame payment page

If merchant sends additional parameters to the payment form, then a signature value should be calculated, instead of using a default value. Use additional parameters for sending them to Pop Up payment form:

Parameter Validation Description
data-uniqueTransactionId 1-45 characters this parameter allows to assign a value for the transaction and receive it in callback data, if a value doesn’t pass - Maxpay generates this value by itself
data-productPublicId 1-32 characters allows to preselect a product for the payment page, the value is Product ID you can find it in Products to sell section
data-email 6-255 characters, valid email parameter for sending email value
data-firstname 2-32 characters user’s first name
data-lastname 2-32 characters user’s last name
data-phone 7-15 digits parameter for sending phone value
data-address 2-64 characters parameter for sending address value
data-city 2-32 characters parameter for sending city value
data-country 3 characters, ISO3 parameter for sending country value
data-zip 2-10 characters parameter for sending zip value
data-success_url max - 255 characters parameter for sending success redirect url value
data-decline_url max - 255 characters parameter for sending decline redirect url value
data-back_url max - 255 characters parameter for sending a back step url for user
data-locale constant value from the list parameter for displaying a language on payment page

iFrame payment form

Example of iFrame payment form:


<div>
    <script src="https://hpp.maxpay.com/paymentPage.js" 
        class="pspScript" 
        data-iframesrc="https://hpp.maxpay.com/hpp"
        data-buttontext="Pay!" 
        data-name="Application" 
        data-key="pkTest_67pcq3B5i8N7utM7WRNM6ZGvxFmHE4W9" 
        data-signature="199d5077dd7be9a8313954bcc7d4fe7ec9b005beab2ef7e00932cc48e3981f87"
        data-uniqueuserid="user123"
        data-payment_method='Credit card'
        data-uniqueTransactionId='transactionId123'
        data-productPublicIde='productId120'
        data-email='john.doe@gmail.com'
        data-firstname='John'
        data-lastname='Doe'
        data-phone='1800080048'
        data-address='Address 123'
        data-city='New York'
        data-country='USA'
        data-zip='12100'
        data-success_url='https://merchant.com/successful-purchase'
        data-decline_url='https://merchant.com/unsuccessful-purchase'
        data-back_url='https://merchant.com'
        data-locale='en-US'
        data-type="integrated" 
        data-width="auto" 
        data-height="auto">
    </script>
    <form class='pspPaymentForm'></form>
    <iframe id='psp-hpp-199d5077dd7be9a8313954bcc7d4fe7ec9b005beab2ef7e00932cc48e3981f87'></iframe>
</div>

Parameters for iFrame payment form

Parameter Validation Description
data-name constant value name of your payment application
data-key constant value public key from general settings
data-signature calculated value signature of the payment widget. Information about a signature generation below
data-uniqueuserid 1-64 characters merchant’s unique user ID (unique user ID in merchant’s system)
data-type constant value, integrated integrated value for iFrame payment page
data-width pixel value width of the iFrame
data-height pixel value height of the iFrame

If merchant sends additional parameters to the payment form, then a signature value should be calculated, instead of using a default value. Use additional parameters for sending them to iFrame payment form:

Parameter Validation Description
data-uniqueTransactionId 1-45 characters this parameter allows to assign a value for the transaction and receive it in callback data, if a value doesn’t pass - Maxpay generates this value by itself
data-productPublicId 1-32 characters allows to preselect a product for the payment page, the value is Product ID you can find it in Products to sell section
data-email 6-255 characters, valid email parameter for sending email value
data-firstname 2-32 characters user’s first name
data-lastname 2-32 characters user’s last name
data-phone 7-15 digits parameter for sending phone value
data-address 2-64 characters parameter for sending address value
data-city 2-32 characters parameter for sending city value
data-country 3 characters, ISO3 parameter for sending country value
data-zip 2-10 characters parameter for sending zip value
data-success_url max - 255 characters parameter for sending success redirect url value
data-decline_url max - 255 characters parameter for sending decline redirect url value
data-back_url max - 255 characters parameter for sending a back step url for user
data-locale constant value from the list parameter for displaying a language on payment page

Redirect payment page

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'>
    <input type='hidden' name='payment_method' value='Credit card'>
    <input type='hidden' name='uniqueTransactionId' value='transactionId123'>
    <input type='hidden' name='productPublicId' value='productId120'>
    <input type='hidden' name='email' value='john.doe@gmail.com'>
    <input type='hidden' name='firstname' value='John'>
    <input type='hidden' name='lastname' value='Doe'>
    <input type='hidden' name='phone' value='1800080048'>
    <input type='hidden' name='address' value='Address 123'>
    <input type='hidden' name='city' value='New York'>
    <input type='hidden' name='country' value='USA'>
    <input type='hidden' name='zip' value='12100'>
    <input type='hidden' name='success_url' value='https://merchant.com/successful-purchase'>
    <input type='hidden' name='decline_url' value='https://merchant.com/unsuccessful-purchase'>
    <input type='hidden' name='back_url' value='https://merchant.com'>
    <input type='hidden' name='locale' value='en-US'>
    <button type='submit'>Pay</button>
</form>

Parameters of Redirect form

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

If merchant sends additional parameters to the payment page, then a signature value should be calculated, instead of using a default value. Use additional parameters for sending them to Redirect payment form:

Parameter Validation Description
uniqueTransactionId 1-45 characters this parameter allows to assign a value for the transaction and receive it in callback data, if a value doesn’t pass - Maxpay generates this value by itself
productPublicId 1-32 characters allows to preselect a product for the payment page, the value is Product ID you can find it in Products to sell section
email 6-255 characters, valid email parameter for sending email value
firstname 2-32 characters user’s first name
lastname 2-32 characters user’s last name
phone 7-15 digits parameter for sending phone value
address 2-64 characters parameter for sending address value
city 2-32 characters parameter for sending city value
country 3 characters, ISO3 parameter for sending country value
zip 2-10 characters parameter for sending zip value
success_url max - 255 characters parameter for sending success redirect url value
decline_url max - 255 characters parameter for sending decline redirect url value
back_url max - 255 characters parameter for sending a back step url for user
locale constant value from the list parameter for displaying a language on payment page

Callback

Example of the callback request to merchant in application/x-www-form-urlencoded format:

    transactionId=hppS1513841180.7902mId3126aId1335
    &reference=SLFF00000006CAAC0F1B
    &uniqueUserId=auto_yJJj935t8kyUX55Q
    &totalAmount=9.99
    &currency=USD
    &transactionType=SALE
    &status=success
    &message=Transaction+processed+successfully
    &code=0
    &productList[0][productId]=2131
    &productList[0][name]=My Product
    &productList[0][amount]=9.99
    &productList[0][currency]=USD
    &convertedAmount=9.99
    &convertedCurrency=USD
    &checkSum=91935c8e71dcac1473d6613e62e0d84d039a075971efd1e11fb4901001938a365d2bee325793a

Callback values

Description of the callback parameters

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 merchant’s system.
totalAmount Total amount of transaction
currency The currency of transaction. ISO3 currencies.
transactionType The type of the transaction.
status Status of the transaction.
message An explanation message of the transaction. The detailed list could be found in “response codes” section below.
code The response code of the transaction. The detailed list could be found in “response codes” section below.
productList Array with product data
productList[productId] Id of the product
productList[name] Name of the product
productList[amount] Amount of the product
productList[currency] Currency of the product
convertedAmount Converted amount
convertedCurrency Converted currency
checkSum Check sum of callback packet

Maxpay sends callback data to merchant in application/x-www-form-urlencoded format. Callback is received to a merchant when in response Maxpay got the code - 200 (it’s required), and body text - OK (it’s optional). In other cases, callback is not received and Maxpay will try periodically to re-send callback data. The number of attempts are limited.

Be advised, that MaxPay can resend a few times callbacks for one transaction. It depends by acquirer bank side.

Examples below describe different cases with callback data receiving:

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

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


Callback 2.0

Example of the callback 2.0 request to merchant in application/json format:

X_SIGNATURE: c37484fc04e55e4a17ca3389f20010608b8822935badaac7275604854c6b5bf9

{
    "uniqueTransactionId":"hpp180926125439m7059a4040uf62e5bb29b97bc",
    "reference":"SLFF0000000040598D81",
    "uniqueUserId":"auto_AH1IqGXIu555VyLF",
    "totalAmount":5,
    "currency":"USD",
    "transactionType":"SALE",
    "status":"success",
    "message":"Transaction processed successfully",
    "code":0,
    "productList":[
        {   
            "productId":"p_6e30432104",
            "name":"Trial product witout description",
            "amount":5,
            "currency":"USD"
        }
    ],
    "testMode":"0"
}
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 merchant’s system.
totalAmount Total amount of transaction
currency The currency of transaction. ISO3 currencies.
transactionType The type of the transaction.
status Status of the transaction.
message An explanation message of the transaction. The detailed list could be found in “response codes” section below.
code The response code of the transaction. The detailed list could be found in “response codes” section below.
productList Array with product data
productList[productId] Id of the product
productList[name] Name of the product
productList[amount] Amount of the product
productList[currency] Currency of the product
testMode 0 - it means test mode

Maxpay sends callback 2.0 data to merchant in application/json format. Callback is received to a merchant when in response Maxpay got the code - 200 (it’s required), and body text - OK (it’s optional). In other cases, callback is not received and Maxpay will try periodically to re-send callback data. The number of attempts are limited. Be advised, that transaction status is better to handle by transaction code, not status or text message.

For signature calculation you should take sha256 from the callback string.

Locale for the payment page

Maxpay provides different languages for the payment page.

Look at available languages below:

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

Let’s look at the sample with French locale.

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

Custom product API

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

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

Custom Fixed Product

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


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

Example with custom fixed product for Redirect payment form


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

Parameters for custom fixed product are provided below:

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

Custom Trial Product

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


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

Example with custom trial product for Redirect payment form


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

Parameters for custom trial product are provided below:

Request parameters:

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

Custom Subscription Product

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


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

Example with custom subscription product for Redirect payment form


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

Parameters for custom subscription product are provided below:

Request parameters:

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


Example of the callback request to merchant in application/x-www-form-urlencoded format:

    transactionId=hppS1513841180.7902mId3126aId1335
    &reference=SLFF00000006CAAC0F1B
    &uniqueUserId=auto_yJJj935t8kyUX55Q
    &totalAmount=9.99
    &currency=USD
    &transactionType=SALE
    &status=success
    &message=Transaction+processed+successfully
    &code=0
    &productList[0][productId]=2131
    &productList[0][name]=My Product
    &productList[0][amount]=9.99
    &productList[0][currency]=USD
    &convertedAmount=9.99
    &convertedCurrency=USD
    &checkSum=91935c8e71dcac1473d6613e62e0d84d039a075971efd1e11fb4901001938a365d2bee325793a

Callback values

Description of the callback parameters

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 merchant’s system.
totalAmount Total amount of transaction
currency The currency of transaction. ISO3 currencies.
transactionType The type of the transaction.
status Status of the transaction.
message An explanation message of the transaction. The detailed list could be found in “response codes” section below.
code The response code of the transaction. The detailed list could be found in “response codes” section below.
productList Array with product data
productList[productId] Id of the product
productList[name] Name of the product
productList[amount] Amount of the product
productList[currency] Currency of the product
convertedAmount Converted amount
convertedCurrency Converted currency
checkSum Check sum of callback packet

Maxpay sends callback data to merchant in application/x-www-form-urlencoded format. Callback is received to a merchant when in response Maxpay got the code - 200 (it’s required), and body text - OK (it’s optional). In other cases, callback is not received and Maxpay will try periodically to re-send callback data. The number of attempts are limited.

Be advised, that MaxPay can resend a few times callbacks for one transaction. It depends by acquirer bank side.

Examples below describe different cases with callback data receiving:

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

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


One click feature

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

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


Rebilling feature

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

Example of the callback request with Token value to merchant in application/x-www-form-urlencoded format:

    transactionId=hppS1513841180.7902mId3126aId1335
    &reference=SLFF00000006CAAC0F1B
    &uniqueUserId=auto_yJJj935t8kyUX55Q
    &totalAmount=9.99
    &currency=USD
    &transactionType=SALE
    &status=success
    &message=Transaction+processed+successfully
    &code=0
    &productList[0][productId]=2131
    &productList[0][name]=My Product
    &productList[0][amount]=9.99
    &productList[0][currency]=USD
    &convertedAmount=9.99
    &convertedCurrency=USD
    &billToken=9293f4vc-47fq-45d4-9eh2-08d29te9d899
    &checkSum=91935c8e71dcac1473d6613e62e0d84d039a075971efd1e11fb4901001938a365d2bee325793a
  1. Select the Payment forms section and click to edit the current payment form.
  2. Click on the Rebilling checkbox for activating the feature.
  3. For rebilling payment - use the value of the billToken which you receive in callback data.

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

Rebilling API

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

Rebilling request with fixed product

Example of the fixed product request:

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

Parameters for rebilling fixed product are provided below:

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

Request parameters:

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

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

Rebilling request with trial product

Example of trial trial product request:

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

Parameters for rebilling trial product are provided below:

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

Request parameters:

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

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

Rebilling request with subscription product

Example of the subscription product request:

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

Parameters for rebilling subscription product are provided below:

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

Request parameters:

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

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

Example of the callback request to merchant in application/x-www-form-urlencoded format:

    transactionId=hppS1513841180.7902mId3126aId1335
    &reference=SLFF00000006CAAC0F1B
    &uniqueUserId=auto_yJJj935t8kyUX55Q
    &totalAmount=9.99
    &currency=USD
    &transactionType=SALE
    &status=success
    &message=Transaction+processed+successfully
    &code=0
    &productList[0][productId]=2131
    &productList[0][name]=My Product
    &productList[0][amount]=9.99
    &productList[0][currency]=USD
    &convertedAmount=9.99
    &convertedCurrency=USD
    &checkSum=91935c8e71dcac1473d6613e62e0d84d039a075971efd1e11fb4901001938a365d2bee325793a

Callback values

Description of the callback parameters

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 merchant’s system.
totalAmount Total amount of transaction
currency The currency of transaction. ISO3 currencies.
transactionType The type of the transaction.
status Status of the transaction.
message An explanation message of the transaction. The detailed list could be found in “response codes” section below.
code The response code of the transaction. The detailed list could be found in “response codes” section below.
productList Array with product data
productList[productId] Id of the product
productList[name] Name of the product
productList[amount] Amount of the product
productList[currency] Currency of the product
convertedAmount Converted amount
convertedCurrency Converted currency
checkSum Check sum of callback packet

Maxpay sends callback data to merchant in application/x-www-form-urlencoded format. Callback is received to a merchant when in response Maxpay got the code - 200 (it’s required), and body text - OK (it’s optional). In other cases, callback is not received and Maxpay will try periodically to re-send callback data. The number of attempts are limited.

Be advised, that MaxPay can resend a few times callbacks for one transaction. It depends by acquirer bank side.

Examples below describe different cases with callback data receiving:

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

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


Cancel subscription API

Cancel subscription API is the way to unsubscribe customers from rebilling API. For current customers subscriptions use the parameters below to cancel subscription payments.

Example of the cancelation request:

<?php

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

?>

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 from Embed code.

Example of the response:

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

Description of the response fields:

PARAMETER DESCRIPTION
transactionId The unique id of the transaction.
message An explanation message of the transaction. The detailed list could be found in “response codes” 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

API for canceling post-trial product

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

Example of the canceling post-trial request:

    <?php

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

    ?>

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

Request parameters:

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

Example of the response:

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

Description of callback fields:

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

Example of the response on repeated request:

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

Refund API

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

Example of the refund request:

    <?php

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

    ?>

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

Request parameters:

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

Example of the response:

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

Description of response parameters:

PARAMETER DESCRIPTION
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

Maxpay.js

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

HPP signature calculation

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

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

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

Sample form for signature calculation


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

The algorithm is provided below:

Example of the signature calculation based on the form above:

<?php

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

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

?>

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

The full logic are available at the link GitHub sample code

HPP checkSum calculation in callback response

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

<?php

    //Callback data request to merchant
    +transactionId=hppS1513841180.7902mId3126aId1335
    &+reference=SLFF00000006CAAC0F1B
    &+uniqueUserId=auto_yJJj935t8kyUX55Q
    &+totalAmount=9.99
    &+currency=USD
    &+transactionType=SALE
    &+status=success
    &+message=Transaction+processed+successfully
    &+code=0
    &+productList[0][productId]=2131
    &+productList[0][name]=My Product
    &+productList[0][amount]=9.99
    &+productList[0][currency]=USD
    &+convertedAmount=9.99
    &+convertedCurrency=USD
    &+billToken=9293f4vc-47fq-45d4-9eh2-08d29te9d899
    &checkSum=91935c8e71dcac1473d6613e62e0d84d039a075971efd1e11fb4901001938a365d2bee325793a

    //Example of the sorted parameters. Also, private key, from API keys settings is added in the end of the line.
    $sortedData = 'billToken=9293f4vc-47fq-45d4-9eh2-08d29te9d899|code=0|convertedAmount=9.99|convertedCurrency=USD|currency=USD|productList.0.amount=9.99|productList.0.currency=USD|productList.0.name=My Product|productList.0.productId=2131|message=Transaction+processed+successfully|reference=SLFF00000006CAAC0F1B|status=success|totalAmount=9.99|transactionId=hppS1513841180.7902mId3126aId1335|transactionType=SALE|uniqueUserId=auto_yJJj935t8kyUX55Q|your_privat_key';    

    //Getting the result of checkSum calculation
    $countedCheckSum = hash('sha256', $sortedData);

?>

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:

Custom parameters

Additional custom parameters:

Purpose: custom parameters can be added to the callback data. For activation please send a query to support@maxpay.com. Parameters will be sent in the separatecustom array.

NAME OF THE PARAMETER SEND TO MERCHANT DESCRIPTION
Bank descriptor custom_bank_descriptor Descriptor of the acquirer
Bank advice custom_bank_advice Advice by the acquirer
Bank Id custom_bank_id Id of the acquirer
Bank name custom_bank_name Name of the acquirer
Bank reason code custom_bank_reason_code Reason code of the acquirer
Bank reason description custom_bank_reason_description Acquirer reason description
Bank transaction id custom_bank_transaction_id Transaction Id by bank
Bank user address custom_bank_user_address User address by bank
Bank user city custom_bank_user_city User city by bank
Bank user country custom_bank_user_country User country by bank
Bank user first name custom_bank_user_first_name User first name by bank
Bank user Id custom_bank_user_id User Id by bank
Bank user lastname custom_bank_user_last_name User last name by bank
Card bank custom_card_bank Bank issuer
Card bin custom_card_bin Bin of the card
Card brand custom_card_brand Brand of the card
Cardholder custom_card_cardholder Cardholder name
Card country custom_card_country Card country
Card country ISO3 custom_card_country_iso3 Card country ISO3 format
Card hash custom_card_hash Hash of the credit card
Card last custom_card_last The last 4 digits of the credit card
Card month custom_card_month Expiration month of the credit card
Card year custom_card_year Expiration year of the credit card
Chargeback base amount custom_chargeback_base_amount Amount of the base transaction
Chargeback base amount CNY custom_chargeback_base_amount_cny Amount of the base transaction in CNY
Chargeback base amount EUR custom_chargeback_base_amount_eur Amount of the base transaction in EUR
Chargeback base amount GBP custom_chargeback_base_amount_gbp Amount of the base transaction in GBP
Chargeback base amount UAH custom_chargeback_base_amount_uah Amount of the base transaction in UAH
Chargeback base amount USD custom_chargeback_base_amount_usd Amount of the base transaction in USD
Chargeback base currency custom_chargeback_base_currency Currency of the base transaction
Descriptor merchant custom_descriptor_merchant Descriptor
Descriptor phone custom_descriptor_phone Descriptor phone
Fee EUR custom_fee_eur Fee in EUR
Fee GBP custom_fee_gbp Fee in GBP
Fee info custom_fee_info Information regarding fee
Fee rolling reserve custom_fee_rolling_reserve Rolling reserve fee
Fee UAH custom_fee_uah Fee in UAH
Fee USD custom_fee_usd Fee in USD
Fraud action custom_fraud_action Fraud action
Fraud decision custom_fraud_decision Fraud decision
fraud reject reason custom_fraud_reject_reason Reject reason by fraud
Fraud score custom_fraud_score Fraud score by user
MID id custom_mid_id Id of the MID
MID name custom_mid_name Name of the MID
MID reference custom_mid_reference Reference of the MID
Next billing date custom_next_billing_date Next billing date
Payment account id custom_payment_account_id Account Id
Secure storage id secure_storage_id Hashed value of the PAN
User first name custom_user_first_name The first name of the user
User last name custom_user_last_name The last name of the user
User phone custom_user_phone Phone of the user

API libraries

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


Also, Module for Magento 1.9 is available on GitHub

Test mode

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

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

Test credit cards

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

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

Going to live

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

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

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

Host to host API

Overview

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

Other definitions:

ECI VALUES

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

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

Access to Maxpay Gateway API

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Integration flow

Please, follow for the next flow:

  1. Sign up at my.maxpay.com
  2. Provide test IP(s) environment and live IP(s) environment for whitelisting: a) Click on the button “Account settings” (upper-right corner of merchant portal). b) Select “Firewall” section. c) Click on the button “Send new request”. d) Input test IPs in “Development IPs” string and production IPs in “Production IPs” string. e) Click on the button “Save”.

  3. Implement credentials by Maxpay integration team on your side.

  4. Provide to merchantsupport@maxpay.com the list of required transaction types of your business model.

  5. Test all transaction types regarding your bussiness model.

  6. Provide to merchantsupport@maxpay.com reference of test transactions in order to finish test integration and receive production credentials.

  7. If test transactions are processed correctly, MaxPay’s integration team will provide credentials for production mode.

  8. Implement production credentials.

  9. Test production integration with all transaction types regarding your bussiness model.

Test mode

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

Test credit cards

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

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

AUTH3D transaction

Sample code of AUTH3D transaction request:

“Content-type: application/json” –data

{
    "api_version":1,
    "merchant_account":"MyAccount_MP_TRX",
    "merchant_password":"account_password",
    "transaction_unique_id":"auth3d_request001",
    "transaction_type":"AUTH3D",
    "amount":9.99,
    "currency":"EUR",
    "card_number":"4012000300001003",
    "card_exp_month":"05",
    "card_exp_year":"2019",
    "cvv": "111",
    "first_name":"John",
    "last_name":"Doe",
    "card_holder":"John Doe",
    "address":"123 Street name.",
    "city":"City Name",
    "state":"New York",
    "zip":"12100",
    "country":"USA",
    "user_phone":"+12025550000",
    "user_email":"johndoe@test.com",
    "user_ip":"127.0.0.1"
}

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

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

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

Request parameters:

PARAMETER NAME REQUIRED RULES EXAMPLE
api_version yes float 1
merchant_account yes string,[6-32] MyAccount_MP_TRX
merchant_password yes string,[6-32] Account password
transaction_unique_id yes string,[1-45] auth3d_request001
transaction_type yes string,[AUTH3D] AUTH3D
amount yes float,[0 - 9999999.9999] 9.99
currency yes string,[3], ISO 4217 (alfa-3) EUR
card_number yes string,[13-19] only digits, Luhn algorithm 4864369454425300
card_exp_month yes string,2 digits month number [‘01’..'12’] 05
card_exp_year yes string,[4], only digits 2020
cvv conditional string,[3-4], only digits 911
first_name yes string,[1-32] John
last_name yes string,[1-32] Doe
card_holder yes string,[2-32] John Doe
address conditional string,[2-64] 123 Street
city conditional string,[2-32] New York
state conditional string,[1-32] NY
zip conditional string,[2-10] 12100
country yes string,[2-3], ISO 3166-1 alpha-3 USA
user_phone conditional string,[7-15] +12025550000
user_ email yes string,[6-255], valid email johndoe@test.com
user_ip yes string,IpAddress 127.0.0.1
merchant_user_id optional string,[0-32] UserId1200021
merchant_domain_name optional string,[0-255] merchant-site.com
merchant_affiliate_id optional string,[0-255] AF_id_7101
merchant_product_name optional string,[0-255] Software
descriptor_merchant optional string,[0-255] merchant-descriptor.com
descriptor_phone optional string,[0-255] 180012345678
mid_reference optional string,[16] MD12345678901234
date_of_birth optional string,[YYYY-MM-DD] 1986-06-28

Notification: In most cases conditional parameters are required for acquirers.

Notification: for test mode add a plus symbol for a phone value. Otherwise a transaction will be declined with reason GENERAL BANK DECLINE.

Notification: Supporting of this transaction type depends on acquirer side. Please, clarify the information before implementation of this transaction type.

Sample code of AUTH3D response in JSON format:

{
  "api_version": 1,
  "merchant_account": "MyAccount_MP_TRX",
  "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 REQUIRED RULES EXAMPLE
api_version yes float 1
merchant_account yes string,[6-32] MyAccount_MP_TRX
sessionid yes string,[36] 53ec668b-c838-44b8-86f2-5c678ae9e3fc
transaction_unique_id yes string,[1-45] auth3d_request001
token yes string,[36] 5814f79a-c8fc-40c2-8161-4e0u68cc13ed
reference yes string,[20] A3FF000000439730A8E
timestamp yes unix timestamp 1408001694
authcode yes string,[0-24] 1111513
pareq optional string,[65535] eJxVUctuwjAQ/JWIK1LsvAqNNpZS
acs_url optional string,[0-255] https://maxpay.com:9443/PIT/ATS
eci optional float,[1] 1, 2, 5, 6, 7
status yes string,[SUCCESS, DECLINE, ERROR] SUCCESS
code yes float,[1-4] Returns response code for the transaction
message yes string Returns explanation of the response code

Example of redirect form after AUTH3D:


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

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

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

Notification: Supporting of this transaction type depends on acquirer side. Please, clarify the information before implementation of this transaction type. After the AUTH3D transaction has been processed a merchant depending on business requirements has ability but not forced to send the following transactons: * AUTH * SETTLE - depends on acquirer side * SALE (with reference and pares as required fields) * VOID - depends on acquirer side * CHECK

AUTH transaction

Sample code of AUTH transaction request:

“Content-type: application/json” –data

{
    "api_version":1,
    "merchant_account":"MyAccount_MP_TRX",
    "merchant_password":"account_password",
    "transaction_unique_id":"auth_request001",
    "transaction_type":"AUTH",
    "amount":9.99,
    "currency":"EUR",
    "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",
    "state":"New York",
    "zip":"12100",
    "country":"USA",
    "user_phone":"+12025550000",
    "user_email":"johndoe@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 REQUIRED RULES EXAMPLE
api_version yes float 1
merchant_account yes string,[6-32] MyAccount_MP_TRX
merchant_password yes string,[6-32] Account password
transaction_unique_id yes string,[1-45] auth3d_request001
transaction_type yes string,[AUTH] AUTH
amount yes float,[0 - 9999999.9999] 9.99
currency yes string,[3], ISO 4217 (alfa-3) EUR
card_number yes string,[13-19] only digits, Luhn algorithm 4864369454425300
card_exp_month yes string,2 digits month number ['01’..'12’] 05
card_exp_year yes string,[4], only digits 2020
cvv conditional string,[3-4], only digits 911
first_name yes string,[1-32] John
last_name yes string,[1-32] Doe
card_holder yes string,[2-32] John Doe
address conditional string,[2-64] 123 Street
city conditional string,[2-32] New York
state conditional string,[1-32] NY
zip conditional string,[2-10] 12100
country yes string,[2-3], ISO 3166-1 alpha-3 USA
user_phone conditional string,[7-15], only digits +12025550000
user_ email yes string,[6-255], valid email johndoe@test.com
user_ip yes string,IpAddress 127.0.0.1
merchant_user_id optional string,[0-32] UserId1200021
merchant_domain_name optional string,[0-255] merchant-site.com
merchant_affiliate_id optional string,[0-255] AF_id_7101
merchant_product_name optional string,[0-255] Software
descriptor_merchant optional string,[0-255] merchant-descriptor.com
descriptor_phone optional string,[0-255] 180012345678
mid_reference optional string,[16] MD12345678901234
date_of_birth optional string,[YYYY-MM-DD] 1986-06-28

Notification: In most cases conditional parameters are required for acquirers.

Notification: if merchant use a scheme AUTH3D + AUTH + SETTLE, then for AUTH request merchant should also add a PARes value.

Notification: for test mode add a plus symbol for a phone value. Otherwise a transaction will be declined with reason GENERAL BANK DECLINE.

Notification: Supporting of this transaction type depends on acquirer side. Please, clarify the information before implementation of this transaction type.

Sample code of AUTH response in JSON format:

{
    "api_version":1,
    "merchant_account":"MyAccount_MP_TRX",
    "sessionid":"543e2136-d46c-4d7d-a3b3-075cf9adkl01",
    "transaction_unique_id":"auth_request001",
    "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 REQUIRED RULES EXAMPLE
api_version yes float 1
merchant_account yes string,[6-32] MyAccount_MP_TRX
sessionid yes string,[36] 53ec668b-c838-44b8-86f2-5c678ae9e3fc
transaction_unique_id yes string,[1-45] auth3d_request001
token yes string,[36] 5814f79a-c8fc-40c2-8161-4e0u68cc13ed
reference yes string,[20] ATFF000000439730A8E
timestamp yes unix timestamp 1408001694
authcode yes string,[0-24] 1111513
status yes string,[SUCCESS, DECLINE, ERROR] SUCCESS
code yes float,[1-4] Returns response code for the transaction
message yes string Returns explanation of the response code

After the AUTH transaction has been processed a merchant have to send the following transactions:
* SETTLE * VOID * CHECK

AUTH (by token) transaction

Sample code of AUTH (by token) request:

“Content-type: application/json” –data

{
    "api_version":1,
    "merchant_account":"MyAccount_MP_TRX",
    "merchant_password":"merchant_password",
    "transaction_unique_id":"auth_with_token001",
    "transaction_type":"AUTH",
    "amount":9.99,
    "currency":"EUR",
    "first_name":"John",
    "last_name":"Doe",
    "card_holder":"John Doe",
    "address":"123 Street name.",
    "city":"City Name",
    "state":"New York",
    "zip":"12100",
    "country":"USA",
    "user_phone":"+12025550000",
    "user_email":"johndoe@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 REQUIRED RULES EXAMPLE
api_version yes float 1
merchant_account yes string,[6-32] MyAccount_MP_TRX
merchant_password yes string,[6-32] Account password
transaction_unique_id yes string,[1-45] auth3d_request001
transaction_type yes string,[AUTH] AUTH
amount yes float,[0 - 9999999.9999] 9.99
currency yes string,[3], ISO 4217 (alfa-3) EUR
card_holder yes string,[2-32] John Doe
first_name yes string,[1-32] John
last_name yes string,[1-32] Doe
address conditional string,[2-64] 123 Street
city conditional string,[2-32] New York
state conditional string,[1-32] NY
zip conditional string,[2-10] 12100
country yes string,[2-3], ISO 3166-1 alpha-3 USA
user_phone conditional string,[7-15], only digits +12025550000
user_ email yes string,[6-255], valid email johndoe@test.com
user_ip yes string,IpAddress 127.0.0.1
merchant_user_id optional string,[0-32] UserId1200021
merchant_domain_name optional string,[0-255] merchant-site.com
merchant_affiliate_id optional string,[0-255] AF_id_7101
merchant_product_name optional string,[0-255] Software
descriptor_merchant optional string,[0-255] merchant-descriptor.com
descriptor_phone optional string,[0-255] 180012345678
mid_reference optional string,[16] MD12345678901234
token yes string,[36] 5524fa52-75d8-4c7a-84ec-039d3097ab6f
date_of_birth optional string,[YYYY-MM-DD] 1986-06-28

Notification: In most cases conditional parameters are required for acquirers.

Notification: if merchant use a scheme AUTH3D + AUTH + SETTLE, then for AUTH request merchant should also add a PARes value.

Notification: for test mode add a plus symbol for a phone value. Otherwise a transaction will be declined with reason GENERAL BANK DECLINE.

Notification: Supporting of this transaction type depends on acquirer side. Please, clarify the information before implementation of this transaction type.

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

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

Response parameters:

PARAMETER NAME REQUIRED RULES EXAMPLE
api_version yes float 1
merchant_account yes string,[6-32] MyAccount_MP_TRX
sessionid yes string,[36] 53ec668b-c838-44b8-86f2-5c678ae9e3fc
transaction_unique_id yes string,[1-45] auth3d_request001
token yes string,[36] 5814f79a-c8fc-40c2-8161-4e0u68cc13ed
reference yes string,[20] ATFF000000439730A8E
timestamp yes unix timestamp 1408001694
authcode yes string,[0-24] 1111513
status yes string,[SUCCESS, DECLINE, ERROR] SUCCESS
code yes float,[1-4] Returns response code for the transaction
message yes string Returns explanation of the response code

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

AUTH (by PARes) transaction

Sample code of AUTH (by PARes) request:

“Content-type: application/json” –data

{
    "api_version":1,
    "merchant_account":"MyAccount_MP_TRX",
    "merchant_password":"merchant_password",
    "transaction_unique_id":"auth_with_pares001",
    "transaction_type":"AUTH",
    "amount":9.99,
    "currency":"EUR",
    "first_name":"John",
    "last_name":"Doe",
    "address":"123 Street name.",
    "city":"City Name",
    "state":"New York",
    "zip":"12100",
    "country":"USA",
    "user_phone":"+12025550000",
    "user_email":"johndoe@test.com",
    "user_ip":"127.0.0.1",
    "reference":"A3FF000000439730A8E",
    "pares":"pares_value" 
}

Purpose: Interface is used to hold transaction amount on the card account using PARes and a reference of the AUTH3D transaction.

Request parameters:

PARAMETER NAME REQUIRED RULES EXAMPLE
api_version yes float 1
merchant_account yes string,[6-32] MyAccount_MP_TRX
merchant_password yes string,[6-32] Account password
transaction_unique_id yes string,[1-45] auth3d_request001
transaction_type yes string,[AUTH] AUTH
amount yes float,[0 - 9999999.9999] 9.99
currency yes string,[3], ISO 4217 (alfa-3) EUR
reference yes string,[20] A3ADS324434DFFSDF423
pares optional string Pares value
cvv optional string,[3-4], only digits 911
merchant_user_id optional string,[0-32] UserId1200021
merchant_domain_name optional string,[0-255] merchant-site.com
merchant_affiliate_id optional string,[0-255] AF_id_7101
merchant_product_name optional string,[0-255] Software
descriptor_merchant optional string,[0-255] merchant-descriptor.com
descriptor_phone optional string,[0-255] 180012345678

Notification: if merchant use a scheme AUTH3D + AUTH + SETTLE, then for AUTH request merchant should also add a PARes value and a reference of the AUTH3D transaction.

Notification: for test mode add a plus symbol for a phone value. Otherwise a transaction will be declined with reason GENERAL BANK DECLINE.

Notification: Supporting of this transaction type depends on acquirer side. Please, clarify the information before implementation of this transaction type.

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

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

Response parameters:

PARAMETER NAME REQUIRED RULES EXAMPLE
api_version yes float 1
merchant_account yes string,[6-32] MyAccount_MP_TRX
sessionid yes string,[36] 53ec668b-c838-44b8-86f2-5c678ae9e3fc
transaction_unique_id yes string,[1-45] auth3d_request001
token yes string,[36] 5814f79a-c8fc-40c2-8161-4e0u68cc13ed
reference yes string,[20] ATFF000000439730AF1
timestamp yes unix timestamp 1408001694
authcode yes string,[0-24] 1111513
eci optional float,[1] 1, 2, 5, 6, 7
status yes string,[SUCCESS, DECLINE, ERROR] SUCCESS
code yes float,[1-4] Returns response code for the transaction
message yes string Returns explanation of the response code

After the AUTH (by PARes) transaction has been processed a merchant depending on business requirements has ability but not forced to send the following transactions: * SETTLE * VOID * CHECK

SETTLE transaction

Sample code of SETTLE transaction request:

“Content-type: application/json” –data

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

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

Request parameters:

PARAMETER NAME REQUIRED RULES EXAMPLE
api_version yes float 1
merchant_account yes string,[6-32] MyAccount_MP_TRX
merchant_password yes string,[6-32] Account password
transaction_unique_id yes string,[1-45] auth3d_request001
transaction_type yes string,[SETTLE] SETTLE
amount yes float,[0 - 9999999.9999] 9.99
currency yes string,[3], ISO 4217 (alfa-3) EUR
reference yes string,[20] ATFFS324434DFFSDF423
merchant_user_id optional string,[0-32] UserId1200021
merchant_domain_name optional string,[0-255] merchant-site.com
merchant_affiliate_id optional string,[0-255] AF_id_7101
merchant_product_name optional string,[0-255] Software
descriptor_merchant optional string,[0-255] merchant-descriptor.com
descriptor_phone optional string,[0-255] 180012345678

Notification: for test mode add a plus symbol for a phone value. Otherwise a transaction will be declined with reason GENERAL BANK DECLINE.

Notification: Supporting of this transaction type depends on acquirer side. Please, clarify the information before implementation of this transaction type.

Sample code of SETTLE response in JSON format:

{
    "api_version":1,
    "merchant_account":"MyAccount_MP_TRX",
    "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 REQUIRED RULES EXAMPLE
api_version yes float 1
merchant_account yes string,[6-32] MyAccount_MP_TRX
sessionid yes string,[36] 53ec668b-c838-44b8-86f2-5c678ae9e3fc
transaction_unique_id yes string,[1-45] auth3d_request001
token yes string,[36] 5814f79a-c8fc-40c2-8161-4e0u68cc13ed
reference yes string,[20] STFF000000439730A51
timestamp yes unix timestamp 1408001694
authcode yes string,[0-24] 1111513
status yes string,[SUCCESS, DECLINE, ERROR] SUCCESS
code yes float,[1-4] Returns response code for the transaction
message yes string Returns explanation of the response code

After the SETTLE transaction has been processed a merchant depending on business requirements has ability but not forced to send the following transactons: * VOID (depends on acquirer side) * REFUND * CHECK

SALE3D transaction

Sample code of SALE3D transaction request:

“Content-type: application/json” –data

{
    "api_version":1,
    "merchant_account":"MyAccount_MP_TRX",
    "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",
    "state":"New York",
    "zip":"12100",
    "country":"USA",
    "user_phone":"+12025550000",
    "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 REQUIRED RULES EXAMPLE
api_version yes float 1
merchant_account yes string,[6-32] MyAccount_MP_TRX
merchant_password yes string,[6-32] Account password
transaction_unique_id yes string,[1-45] auth3d_request001
transaction_type yes string,[SALE3D] SALE3D
amount yes float,[0 - 9999999.9999] 9.99
currency yes string,[3], ISO 4217 (alfa-3) EUR
card_number yes string,[13-19] only digits, Luhn algorithm 4864369454425300
card_exp_month yes string,2 digits month number ['01’..'12’] 05
card_exp_year yes string,[4], only digits 2020
cvv conditional string,[3-4], only digits 911
first_name yes string,[1-32] John
last_name yes string,[1-32] Doe
card_holder yes string,[2-32] John Doe
address conditional string,[2-64] 123 Street
city conditional string,[2-32] New York
state conditional string,[1-32] NY
zip conditional string,[2-10] 12100
country yes string,[2-3], ISO 3166-1 alpha-3 USA
user_phone conditional string,[7-15], only digits +12025550000
user_ email yes string,[6-255], valid email johndoe@test.com
user_ip yes string,IpAddress 127.0.0.1
callback_url yes Not Empty String https://testshop.com/success
redirect_url yes Not Empty String https://merchant-site.com
merchant_user_id optional string,[0-32] UserId1200021
merchant_domain_name optional string,[0-255] merchant-site.com
merchant_affiliate_id optional string,[0-255] AF_id_7101
merchant_product_name optional string,[0-255] Software
descriptor_merchant optional string,[0-255] merchant-descriptor.com
descriptor_phone optional string,[0-255] 180012345678
mid_reference optional string,[16] MD12345678901234
date_of_birth optional string,[YYYY-MM-DD] 1986-06-28

Notification: In most cases conditional parameters are required for acquirers.

Notification: for test mode add a plus symbol for a phone value. Otherwise a transaction will be declined with reason GENERAL BANK DECLINE.

Notification: Supporting of this transaction type depends on acquirer side. Please, clarify the information before implementation of this transaction type.

Example of SALE3D response in JSON format:

{
    "api_version":1,
    "merchant_account":"MyAccount_MP_TRX",
    "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 REQUIRED RULES EXAMPLE
api_version yes float 1
merchant_account yes string,[6-32] MyAccount_MP_TRX
sessionid yes string,[36] 53ec668b-c838-44b8-86f2-5c678ae9e3fc
transaction_unique_id yes string,[1-45] auth3d_request001
token yes string,[36] 5814f79a-c8fc-40c2-8161-4e0u68cc13ed
reference yes string,[20] S3FF0000004397DS30A8E
timestamp yes unix timestamp 1408001694
authcode yes string,[0-24] 1111513
acs_url optional string,[0-255] https://maxpay.com:9443/PIT/ATS
eci optional float,[1] 1, 2, 5, 6, 7
status yes string,[SUCCESS, DECLINE, ERROR] SUCCESS
code yes float,[1-4] Returns response code for the transaction
message yes string Returns explanation of the response code

Callback

Sample code of callback on SALE3D transaction in application/x-www-form-urlencoded format:


    token=50cb16c0-21a8-ambc-a177-555bbd65a038
    &reference=SLFF00000006CAAC0F1B
    &transaction_unique_id=sale3D_transaction_001
    &status=success
    &code=0
    &message=Transaction+processed+successfully
    &checkSum=91935c8e71dcac1473d6613e62e0d84d039a075971efd1e11fb4901001938a365d2bee325793a

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

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

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

Be advised, that MaxPay can resend a few times callbacks for one transaction. It depends by acquirer bank side.

Examples below describe different cases with callback data receiving:

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

After the SALE3D transaction has been processed a merchant depending on business requirements has ability to send the following transactons: * REFUND * CHECK

Callback 2.0

Example of the callback 2.0 request to merchant in application/json format:

X_SIGNATURE: c37484fc04e55e4a17ca3389f20010608b8822935badaac7275604854c6b5bf9

{
    "uniqueTransactionId":"hpp180926125439m7059a4040uf62e5bb29b97bc",
    "reference":"SLFF0000000040598D81",
    "uniqueUserId":"auto_AH1IqGXIu555VyLF",
    "totalAmount":5,
    "currency":"USD",
    "transactionType":"SALE",
    "status":"success",
    "message":"Transaction processed successfully",
    "code":0,
    "productList":[
        {   
            "productId":"p_6e30432104",
            "name":"Trial product witout description",
            "amount":5,
            "currency":"USD"
        }
    ],
    "testMode":"0"
}
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 merchant’s system.
totalAmount Total amount of transaction
currency The currency of transaction. ISO3 currencies.
transactionType The type of the transaction.
status Status of the transaction.
message An explanation message of the transaction. The detailed list could be found in “response codes” section below.
code The response code of the transaction. The detailed list could be found in “response codes” section below.
productList Array with product data
productList[productId] Id of the product
productList[name] Name of the product
productList[amount] Amount of the product
productList[currency] Currency of the product
testMode 0 - it means test mode

Maxpay sends callback 2.0 data to merchant in application/json format. Callback is received to a merchant when in response Maxpay got the code - 200 (it’s required), and body text - OK (it’s optional). In other cases, callback is not received and Maxpay will try periodically to re-send callback data. The number of attempts are limited. Be advised, that transaction status is better to handle by transaction code, not status or text message.

For signature calculation you should take sha256 from the callback string.

SALE transaction

Sample code of SALE transaction request:

“Content-type: application/json” –data

{
    "api_version":1,
    "merchant_account":"MyAccount_MP_TRX",
    "merchant_password":"account_password",
    "transaction_unique_id":"sale_request001",
    "transaction_type":"SALE",
    "amount":9.99,
    "currency":"EUR",
    "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",
    "state":"New York",
    "zip":"12100",
    "country":"USA",
    "user_phone":"+12025550000",
    "user_email":"johndoe@test.com",
    "user_ip":"127.0.0.1"
}

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

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

Request parameters:

PARAMETER NAME REQUIRED RULES EXAMPLE
api_version yes float 1
merchant_account yes string,[6-32] MyAccount_MP_TRX
merchant_password yes string,[6-32] Account password
transaction_unique_id yes string,[1-45] sale_request001
transaction_type yes string,[SALE] SALE
amount yes float,[0 - 9999999.9999] 9.99
currency yes string,[3], ISO 4217 (alfa-3) EUR
card_number yes string,[13-19] only digits, Luhn algorithm 4864369454425300
card_exp_month yes string,2 digits month number ['01’..'12’] 05
card_exp_year yes string,[4], only digits 2020
cvv conditional string,[3-4], only digits 911
first_name yes string,[1-32] John
last_name yes string,[1-32] Doe
card_holder yes string,[2-32] John Doe
address conditional string,[2-64] 123 Street
city conditional string,[2-32] New York
state conditional string,[1-32] NY
zip conditional string,[2-10] 12100
country yes string,[2-3], ISO 3166-1 alpha-3 USA
user_phone conditional string,[7-15], only digits +12025550000
user_ email yes string,[6-255], valid email johndoe@test.com
user_ip yes string,IpAddress 127.0.0.1
callback_url yes Not Empty String https://testshop.com/success
redirect_url yes Not Empty String https://merchant-site.com
merchant_user_id optional string,[0-32] UserId1200021
merchant_domain_name optional string,[0-255] merchant-site.com
merchant_affiliate_id optional string,[0-255] AF_id_7101
merchant_product_name optional string,[0-255] Software
descriptor_merchant optional string,[0-255] merchant-descriptor.com
descriptor_phone optional string,[0-255] 180012345678
mid_reference optional string,[16] MD12345678901234
date_of_birth optional string,[YYYY-MM-DD] 1986-06-28

Notification: In most cases conditional parameters are required for acquirers.

Notification: for test mode add a plus symbol for a phone value. Otherwise a transaction will be declined with reason GENERAL BANK DECLINE.

Example of SALE response in JSON format:

{
    "api_version":1,
    "merchant_account":"MyAccount_MP_TRX",
    "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 REQUIRED RULES EXAMPLE
api_version yes float 1
merchant_account yes string,[6-32] MyAccount_MP_TRX
sessionid yes string,[36] 53ec668b-c838-44b8-86f2-5c678ae9e3fc
transaction_unique_id yes string,[1-45] auth3d_request001
token yes string,[36] 5814f79a-c8fc-40c2-8161-4e0u68cc13ed
reference yes string,[20] S30000004397DS30A8E
timestamp yes unix timestamp 1408001694
authcode yes string,[0-24] 1111513
status yes string,[SUCCESS, DECLINE, ERROR] SUCCESS
code yes float,[1-4] Returns response code for the transaction
message yes string Returns explanation of the response code

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

SALE (by token) transaction

Example of SALE (by token) request:

“Content-type: application/json” –data

{
    "api_version":1,
    "merchant_account":"MyAccount_MP_TRX",
    "merchant_password":"account_password",
    "transaction_unique_id":"sale_token001",
    "transaction_type":"SALE",
    "amount":9.99,
    "currency":"EUR",
    "first_name":"John",
    "last_name":"Doe",
    "card_holder":"John Doe",
    "address":"123 Street name.",
    "city":"City Name",
    "state":"New York",
    "zip":"12100",
    "country":"USA",
    "user_phone":"+12025550000",
    "user_email":"johndoe@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 REQUIRED RULES EXAMPLE
api_version yes float 1
merchant_account yes string,[6-32] MyAccount_MP_TRX
merchant_password yes string,[6-32] Account password
transaction_unique_id yes string,[1-45] sale_token001
transaction_type yes string,[SALE] SALE
amount yes float,[0 - 9999999.9999] 9.99
currency yes string,[3], ISO 4217 (alfa-3) EUR
card_holder yes string,[2-32] John Doe
first_name yes string,[1-32] John
last_name yes string,[1-32] Doe
address conditional string,[2-64] 123 Street
city conditional string,[2-32] New York
state conditional string,[1-32] NY
zip conditional string,[2-10] 12100
country yes string,[2-3], ISO 3166-1 alpha-3 USA
user_phone conditional string,[7-15], only digits +12025550000
user_ email yes string,[6-255], valid email johndoe@test.com
user_ip yes string,IpAddress 127.0.0.1
merchant_user_id optional string,[0-32] UserId1200021
merchant_domain_name optional string,[0-255] merchant-site.com
merchant_affiliate_id optional string,[0-255] AF_id_7101
merchant_product_name optional string,[0-255] Software
descriptor_merchant optional string,[0-255] merchant-descriptor.com
descriptor_phone optional string,[0-255] 180012345678
mid_reference optional string,[16] MD12345678901234
token yes string,[36] 5524fa52-75d8-4c7a-84ec-039d3097ab6f
date_of_birth optional string,[YYYY-MM-DD] 1986-06-28

Notification: for test mode add a plus symbol for a phone value. Otherwise a transaction will be declined with reason GENERAL BANK DECLINE.

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

{
    "api_version":1,
    "merchant_account":"MyAccount_MP_TRX",
    "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 REQUIRED RULES EXAMPLE
api_version yes float 1
merchant_account yes string,[6-32] MyAccount_MP_TRX
sessionid yes string,[36] 53ec668b-c838-44b8-86f2-5c678ae9e3fc
transaction_unique_id yes string,[1-45] sale_token_request001
token yes string,[36] 5814f79a-c8fc-40c2-8161-4e0u68cc13ed
reference yes string,[20] SLFF000000439730AF1
timestamp yes unix timestamp 1408001694
authcode yes string,[0-24] 1111513
status yes string,[SUCCESS, DECLINE, ERROR] SUCCESS
code yes float,[1-4] Returns response code for the transaction
message yes string Returns explanation of the response code

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

SALE (by PARes) transaction

Sample code of SALE (by PARes) transaction request:

“Content-type: application/json” –data

{
    "api_version":1,
    "merchant_account":"MyAccount_MP_TRX",
    "merchant_password":"account_password",
    "transaction_unique_id":"sale_request001",
    "transaction_type":"SALE",
    "amount":9.99,
    "currency":"EUR",
    "reference":"SLFF00000FDD342FC"
    "first_name":"John",
    "last_name":"Doe",
    "address":"123 Street name.",
    "city":"City Name",
    "state":"New York",
    "zip":"12100",
    "country":"USA",
    "user_phone":"+12025550000",
    "user_email":"johndoe@test.com",
    "user_ip":"127.0.0.1",
    "reference":"A3FF000000439730A8E",
    "pares":"pares_value" 
}

Purpose: Interface is used to collect money directly from cardholder account using PARes by AUTH3D transaction and a reference of the AUTH3D transaction.

Request parameters:

PARAMETER NAME REQUIRED RULES EXAMPLE
api_version yes float 1
merchant_account yes string,[6-32] MyAccount_MP_TRX
merchant_password yes string,[6-32] Account password
transaction_unique_id yes string,[1-45] auth3d_request001
transaction_type yes string,[SALE] SALE
amount yes float,[0 - 9999999.9999] 9.99
currency yes string,[3], ISO 4217 (alfa-3) EUR
reference yes string,[20] A3ADS324434DFFSDF423
pares optional string Pares value
cvv optional string,[3-4], only digits 911
merchant_user_id optional string,[0-32] UserId1200021
merchant_domain_name optional string,[0-255] merchant-site.com
merchant_affiliate_id optional string,[0-255] AF_id_7101
merchant_product_name optional string,[0-255] Software
descriptor_merchant optional string,[0-255] merchant-descriptor.com
descriptor_phone optional string,[0-255] 180012345678

Notification: for test mode add a plus symbol for a phone value. Otherwise a transaction will be declined with the reason GENERAL BANK DECLINE.

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

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

Response parameters:

PARAMETER NAME REQUIRED RULES EXAMPLE
api_version yes float 1
merchant_account yes string,[6-32] MyAccount_MP_TRX
sessionid yes string,[36] 53ec668b-c838-44b8-86f2-5c678ae9e3fc
transaction_unique_id yes string,[1-45] auth3d_request001
token yes string,[36] 5814f79a-c8fc-40c2-8161-4e0u68cc13ed
reference yes string,[20] ATFF000000439730AF1
timestamp yes unix timestamp 1408001694
authcode yes string,[0-24] 1111513
status yes string,[SUCCESS, DECLINE, ERROR] SUCCESS
code yes float,[1-4] Returns response code for the transaction
message yes string Returns explanation of the response code

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

REFUND transaction

Sample code of REFUND request:

“Content-type: application/json” –data

{
    "api_version":1,
    "merchant_account":"MyAccount_MP_TRX",
    "merchant_password":"account_password",
    "transaction_unique_id":"refund_request001",
    "transaction_type":"REFUND",
    "amount":9.99,
    "currency":"EUR",
    "reference":"SLFF0000000039FDAEGG"
}

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

Request parameters:

PARAMETER NAME REQUIRED RULES EXAMPLE
api_version yes float 1
merchant_account yes string,[6-32] MyAccount_MP_TRX
merchant_password yes string,[6-32] Account password
transaction_unique_id yes string,[1-45] auth3d_request001
transaction_type yes string,[REFUND] REFUND
amount yes float,[0 - 9999999.9999] 9.99
currency yes string,[3], ISO 4217 (alfa-3) EUR
reference yes string,[20] SLFF00000434DFFSDF423
merchant_user_id optional string,[0-32] UserId1200021
descriptor_merchant optional string,[0-255] merchant-descriptor.com
descriptor_phone optional string,[0-255] 180012345678

Sample code of REFUND response in JSON format:

{
    "api_version":1,
    "merchant_account":"MyAccount_MP_TRX",
    "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 REQUIRED RULES EXAMPLE
api_version yes float 1
merchant_account yes string,[6-32] MyAccount_MP_TRX
sessionid yes string,[36] 53ec668b-c838-44b8-86f2-5c678ae9e3fc
transaction_unique_id yes string,[1-45] auth3d_request001
token yes string,[36] 5814f79a-c8fc-40c2-8161-4e0u68cc13ed
reference yes string,[20] RF00000000439730AF1
timestamp yes unix timestamp 1408001694
authcode yes string,[0-24] 1111513
status yes string,[SUCCESS, DECLINE, ERROR] SUCCESS
code yes float,[1-4] Returns response code for the transaction
message yes string Returns explanation of the response code

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

VOID transaction

Sample code of VOID request:

“Content-type: application/json” –data

{
    "api_version":1,
    "merchant_account":"MyAccount_MP_TRX",
    "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 REQUIRED RULES EXAMPLE
api_version yes float 1
merchant_account yes string,[6-32] MyAccount_MP_TRX
merchant_password yes string,[6-32] Account password
transaction_unique_id yes string,[1-45] auth3d_request001
transaction_type yes string,[VOID] VOID
reference yes string,[20] SLFF00000434DFFSDF423
merchant_user_id optional string,[0-32] UserId1200021
descriptor_merchant optional string,[0-255] merchant-descriptor.com
descriptor_phone optional string,[0-255] 180012345678

Notification: Supporting of this transaction type depends on acquirer side. Please, clarify the information before implementation of this transaction type.

Sample code of VOID response in JSON format:

{
    "api_version":1,
    "merchant_account":"MyAccount_MP_TRX",
    "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 REQUIRED RULES EXAMPLE
api_version yes float 1
merchant_account yes string,[6-32] MyAccount_MP_TRX
sessionid yes string,[36] 53ec668b-c838-44b8-86f2-5c678ae9e3fc
transaction_unique_id yes string,[1-45] auth3d_request001
token yes string,[36] 5814f79a-c8fc-40c2-8161-4e0u68cc13ed
reference yes string,[20] RF00000000439730AF1
timestamp yes unix timestamp 1408001694
authcode yes string,[0-24] 1111513
status yes string,[SUCCESS, DECLINE, ERROR] SUCCESS
code yes float,[1-4] Returns response code for the transaction
message yes string Returns explanation of the response code

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

CHECK transaction

Sample code of CHECK request:

“Content-type: application/json” –data

{
    "api_version":1,
    "merchant_account":"MyAccount_MP_TRX",
    "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 REQUIRED RULES EXAMPLE
api_version yes float 1
merchant_account yes string,[6-32] MyAccount_MP_TRX
merchant_password yes string,[6-32] Account password
transaction_unique_id yes string,[1-45] auth3d_request001
transaction_type yes string,[CHECK] CHECK
reference yes string,[20] SLFF00000434DFFSDF423

Sample code of CHECK response in JSON format:

{
    "api_version":1,
    "merchant_account":"MyAccount_MP_TRX",
    "sessionid":"5668fbfb-2d9c-492c-9f7c-11fb8ae9e3fc",
    "transactions":[
        {
            "reference":"ATFF00000000395AD690",
            "transaction_unique_id":"check_request001",
            "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 REQUIRED RULES EXAMPLE
api_version yes float 1
merchant_account yes string,[6-32] MyAccount_MP_TRX
sessionid yes string,[36] 53ec668b-c838-44b8-86f2-5c678ae9e3fc
transactions yes array transactions
reference yes string,[20] RF00000000439730AF1
transaction_unique_id yes string,[1-45] check_request001
transaction_type yes string AUTH
status yes string,[SUCCESS, DECLINE, ERROR] SUCCESS
code yes float,[1-4] Returns response code for the transaction
message yes string Returns explanation of the response code
token yes string,[36] 5814f79a-c8fc-40c2-8161-4e0u68cc13ed
timestamp yes unix timestamp 1408001694
authcode yes string,[0-24] 1111513
transactions end yes end of the array transactions end
status yes string,[SUCCESS, DECLINE, ERROR] SUCCESS
code yes float,[1-4] Returns response code for the transaction
message yes string Returns explanation of the response code

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

TOKENIZE transaction

Sample code example of TOKENIZE request:

“Content-type: application/json” –data

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

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

Request parameters:

PARAMETER NAME REQUIRED RULES EXAMPLE
api_version yes float 1
merchant_account yes string,[6-32] MyAccount_MP_TRX
merchant_password yes string,[6-32] Account password
transaction_type yes string,[TOKENIZE] TOKENIZE
card_number yes string,[13-19] only digits, Luhn algorithm 4864369454425300
card_exp_month yes string,2 digits month number ['01’..'12’] 05
card_exp_year yes string,[4], only digits 2020
card_holder yes string,[2-32] John Doe

Sample code of TOKENIZE response in JSON format:

{
    "api_version":1,
    "merchant_account":"MyAccount_MP_TRX",
    "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 REQUIRED RULES EXAMPLE
api_version yes float 1
merchant_account yes string,[6-32] MyAccount_MP_TRX
sessionid yes string,[36] 53ec668b-c838-44b8-86f2-5c678ae9e3fc
transaction_unique_id yes string,[1-45] null
token yes string,[36] 5814f79a-c8fc-40c2-8161-4e0u68cc13ed
reference yes string,[20] null
timestamp yes unix timestamp 1408001694
authcode yes string,[0-24] 1111513
status yes string,[SUCCESS, DECLINE, ERROR] SUCCESS
code yes float,[1-4] Returns response code for the transaction
message yes string Returns explanation of the response code

After the Tokenize transaction has been processed a merchant has ability to use card Token instead of credit card number details. Be advised, that MaxPay doesn’t advise to use Token value for initial payments.

Erroneous response

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

Response parameters:

PARAMETER NAME REQUIRED RULES EXAMPLE
api_version yes float 1
merchant_account yes string,[6-32] MyAccount_MP_TRX
sessionid yes string,[36] 53ec668b-c838-44b8-86f2-5c678ae9e3fc
transaction_unique_id yes string,[1-45] null
token yes string,[36] null
reference yes string,[20] null
timestamp yes unix timestamp 1408001694
authcode yes string,[0-24] null
pareq optional string,[65535] null
acs_url optional string,[0-255] null
eci optional float,[1] null
status yes string,[SUCCESS, DECLINE, ERROR] ERROR
code yes float,[1-4] Returns response code for the transaction
message yes string Returns explanation of the response code

Erroneous response on check

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

Response parameters:

PARAMETER NAME REQUIRED RULES EXAMPLE
api_version yes float 1
merchant_account yes string,[6-32] null
sessionid yes string,[36] null
transaction_unique_id yes string,[1-45] null
token yes string,[36] null
reference yes string,[20] null
timestamp yes unix timestamp 1408001694
authcode yes string,[0-24] null
status yes string,[SUCCESS, DECLINE, ERROR] ERROR
code yes float,[1-4] Returns response code for the transaction
message yes string Returns explanation of the response code

Custom parameters

Additional custom parameters (request):

Purpose: Own custom parameters also could be sent via API. For more information please contact support@maxpay.com

Additional custom parameters (response/callback):

Purpose: Custom parameters can be added to the response. For activation please send a query to support@maxpay.com.

NAME OF THE PARAMETER SEND TO MERCHANT RULES DESCRIPTION
Bank descriptor custom_bank_descriptor /.{0,255}/ Descriptor of the acquirer
Bank advice custom_bank_advice /.{0,65535}/ Advice by the acquirer
Bank Id custom_bank_id /\d{1,20}/ Id of the acquirer
Bank name custom_bank_name /.{0,32}/ Name of the acquirer
Bank reason code custom_bank_reason_code /.{0,45}/ Reason code of the acquirer
Bank reason description custom_bank_reason_description /.{0,200}/ Acquirer reason description
Bank transaction id custom_bank_transaction_id /.{0,255}/ Transaction Id by bank
Bank user address custom_bank_user_address /.{0,255}/ User address by bank
Bank user city custom_bank_user_city /.{0,255}/ User city by bank
Bank user country custom_bank_user_country /.{0,255}/ User country by bank
Bank user first name custom_bank_user_first_name /.{0,255}/ User first name by bank
Bank user Id custom_bank_user_id /.{0,255}/ User Id by bank
Bank user lastname custom_bank_user_last_name /.{0,255}/ User last name by bank
Card bank custom_card_bank /.{0,255}/ Bank issuer
Card bin custom_card_bin /\d{6}/ Bin of the card
Card brand custom_card_brand /.{0,255}/ Brand of the card
Cardholder custom_card_cardholder /.{0,255}/ Cardholder name
Card country custom_card_country /.{0,255}/ Card country
Card country ISO3 custom_card_country_iso3 /.{3}/ Card country ISO3 format
Card hash custom_card_hash /.{0,255}/ Hash of the credit card
Card last custom_card_last /\d{4}/ The last 4 digits of the credit card
Card month custom_card_month /\d{2}/ Expiration month of the credit card
Card year custom_card_year /\d{2}/ Expiration year of the credit card
Chargeback base amount custom_chargeback_base_amount /\d{1,14}.\d{1,6}/ Amount of the base transaction
Chargeback base amount CNY custom_chargeback_base_amount_cny /\d+(.\d{1,4})?/ Amount of the base transaction in CNY
Chargeback base amount EUR custom_chargeback_base_amount_eur /\d+(.\d{1,4})?/ Amount of the base transaction in EUR
Chargeback base amount GBP custom_chargeback_base_amount_gbp /\d+(.\d{1,4})?/ Amount of the base transaction in GBP
Chargeback base amount UAH custom_chargeback_base_amount_uah /\d+(.\d{1,4})?/ Amount of the base transaction in UAH
Chargeback base amount USD custom_chargeback_base_amount_usd /\d+(.\d{1,4})?/ Amount of the base transaction in USD
Chargeback base currency custom_chargeback_base_currency /.{1,10}/ Currency of the base transaction
Descriptor merchant custom_descriptor_merchant /\d+(.\d{1,4})?/ Descriptor
Descriptor phone custom_descriptor_phone /\d+(.\d{1,4})?/ Descriptor phone
Fee EUR custom_fee_eur /\d+(.\d{1,4})?/ Fee in EUR
Fee GBP custom_fee_gbp /\d+(.\d{1,4})?/ Fee in GBP
Fee info custom_fee_info /.{0,65535}/ Information regarding fee
Fee rolling reserve custom_fee_rolling_reserve /\d+(.\d{1,4})?/ Rolling reserve fee
Fee UAH custom_fee_uah /\d+(.\d{1,4})?/ Fee in UAH
Fee USD custom_fee_usd /\d+(.\d{1,4})?/ Fee in USD
Fraud action custom_fraud_action /.{0,255}/ Fraud action
Fraud decision custom_fraud_decision /accept or reject or manual/ Fraud decision
fraud reject reason custom_fraud_reject_reason /.{0,65535}/ Reject reason by fraud
Fraud score custom_fraud_score /\d{1,9}/ Fraud score by user
MID id custom_mid_id /\d{1,20}/ Id of the MID
MID name custom_mid_name /.{0,64}/ Name of the MID
MID reference custom_mid_reference /MD[0-9A-F]{14}/ Reference of the MID
Next billing date custom_next_billing_date /\d{8,}/ Next billing date
Payment account id custom_payment_account_id /\d{1,20}/ Account Id
Secure storage id secure_storage_id /.{0,45}/ Hashed value of the PAN
User first name custom_user_first_name /.{0,255}/ The first name of the user
User last name custom_user_last_name /.{0,255}/ The last name of the user
User phone custom_user_phone /.{0,255}/ Phone of the user

Validation exposition: MDN web docs

Payout API

Overview

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

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

This API call allows to get all available payout methods.

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 the response in application/json format:

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

Response parameters:

Field Mandatory Type Description
sessionid yes string An unique Id of the session.
timestamp yes string Time of the request.
methods yes array Array which contains of type, mid_name, mid_reference, bank_code, currencies.
methods[type] yes string Type of the payout.
methods[mid_name] yes string Name of the MID.
methods[mid_reference] yes string MID reference, uses to send payout to specific MID.
methods[bank_code] yes string Bank code, uses for routing. Always null for type=card.
methods[currencies] yes string[] Supported currencies.
status yes string [‘success’, 'decline’, 'error’] Response status.
code yes int Response code.
message yes string Response description.

Notification for init method In case of successful request merchant will receive status=pending and code=0 in response. Be advised that the final status of the payout request merchant will receive in callback data, more details regarding callback data is provided below.

Payout on credit card

Example of the payout request on credit card via full credit card data, application/json format:

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

{
    "api_version": 1,
    "method": "init",
    "merchant_account": "my_merchant_account",
    "merchant_password": "my_merchant_password",
    "transaction_unique_id": "payout_request_0001",
    "amount": 10,
    "currency": "USD",
    "callback_url": "https://merchant.com/callback",
    "user_id": "merchantUserId_00001",
    "user_ip": "127.0.0.1",
    "user_email": "john.doe@example.com",
    "card": {
        "card_cvv": "029",
        "card_number": "4012000300001003",
        "card_holder": "John Doe",
        "card_exp_year": "2022",
        "card_exp_month": "07"
    }
}

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

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

Example of the response in application/json format:

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

Response parameters:

Field Mandatory Type Description
sessionid yes string An unique Id of the session
timestamp yes UNIX timestamp Timestamp
status yes string Response status
code yes int Response code
message yes string Response description

Notification: in case of successful request merchant will receive status=pending and code=0 in response. Be advised that the final status of the payout request merchant will receive in callback data, more details regarding callback data is provided below.

Payout via Token

Example of the payout request on credit card via Token, application/json format:

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

{
    "api_version": 1,
    "method": "init",
    "merchant_account": "my_merchant_account",
    "merchant_password": "my_merchant_password",
    "transaction_unique_id": "payout_request_0001",
    "amount": 10,
    "currency": "USD",
    "callback_url": "https://merchant.com/callback",
    "user_id": "merchantUserId_00001",
    "user_ip": "127.0.0.1",
    "user_email": "john.doe@example.com",
    "card": {
        "token": "5aaaa194-1d68-4ef8-a72f-009184ee03a6",
        "card_holder": "John Doe"
    }
}

Merchant can use Token value instead of full credit card data. Token is hashed data of the credit card. Token value contains of credit card number, expiry date and card holder name.

Parameters of the payout request on credit card via Token:

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

Example of the response in application/json format:

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

Response parameters:

Field Mandatory Type Description
sessionid yes string An unique Id of the session
timestamp yes UNIX timestamp Timestamp
status yes string Response status
code yes int Response code
message yes string Response description

Notification: in case of successful request merchant will receive status=pending and code=0 in response. Be advised that the final status of the payout request merchant will receive in callback data, more details regarding callback data is provided below.

Payout via QIWI

Example of the payout request via QIWI in application/json format:

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

{
    "api_version": 1,
    "method": "init",
    "merchant_account": "my_merchant_account",
    "merchant_password": "my_account_password",
    "transaction_unique_id": "payout_request_0001",
    "mid_reference": "MD0000000D37A5F7",
    "amount": 100,
    "currency": "RUB",
    "callback_url": "https://merchant.com/callback",
    "user_id": "merchantUserId_00001",
    "user_ip": "user_ip",
    "user_email": "john.doe@test.com",
    "qiwi": {
        "wallet_id": "qiwi wallet number"
    }
}

Parameters of the payout request via QIWI:

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

Notification: only one of the parameters: mid_reference or bank_code should be sent in the request.

Example of the response in application/json format:

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

Response parameters:

Field Mandatory Type Description
sessionid yes string An unique Id of the session
timestamp yes UNIX timestamp Timestamp
status yes string Response status
code yes int Response code
message yes string Response description

Payout via Yandex

Example of the payout request via Yandex in application/json format:

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

{
    "api_version": 1,
    "method": "init",
    "merchant_account": "my_merchant_account",
    "merchant_password": "my_account_password",
    "transaction_unique_id": "payout_request_0001",
    "mid_reference": "MD0000000D37A6C9",
    "amount": 100,
    "currency": "RUB",
    "callback_url": "https://merchant.com/callback",
    "user_id": "merchantUserId_00001",
    "user_ip": "127.0.01",
    "user_email": "john.doe@test.com",
    "yandex": {
        "wallet_id": "yandex wallet ID number"
    }
}

Parameters of the payout request via Yandex:

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

Notification: only one of the parameters: mid_reference or bank_code should be sent in the request.

Example of the response in application/json format:

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

Response parameters:

Field Mandatory Type Description
sessionid yes string An unique Id of the session
timestamp yes UNIX timestamp Timestamp
status yes string Response status
code yes int Response code
message yes string Response description

Payout via Paysafecard

Example of the payout request via Paysafecard in application/json format:

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

{
    "api_version": 1,
    "method": "init",
    "merchant_account": "my_merchant_account",
    "merchant_password": "my_merchant_password",
    "transaction_unique_id": "payout_request_0001",
    "mid_reference": "MD0000000D37A843",
    "amount": 10,
    "currency": "EUR",
    "callback_url": "https://merchant.com/callback",
    "user_ip": "127.0.0.1",
    "paysafecard": {
        "user_id": "merchantUserId_00001",
        "user_email": "john.doe@test.com",
        "user_first_name": "John",
        "user_last_name": "Doe",
        "user_date_of_birth": "1986-06-28"
    }
}

Parameters of the payout request via Paysafecard:

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

Notification: only one of the parameters: mid_reference or bank_code should be sent in the request.

Example of the response in application/json format:

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

Response parameters:

Field Mandatory Type Description
sessionid yes string An unique Id of the session
timestamp yes UNIX timestamp Timestamp
status yes string Response status
code yes int Response code
message yes string Response description

Payout via Skrill

Example of payout by wallet for Skrill in application/json format:

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

{
    "api_version": 1,
    "method": "init",
    "merchant_account": "my_merchant_account",
    "merchant_password": "my_merchant_password",
    "transaction_unique_id": "payout_request_0001",
    "mid_reference": "MD0000000D37A8C1",
    "amount": 15,
    "currency": "USD",
    "callback_url": "https://merchant.com/callback",
    "type": "skrill",
    "wallet_id": "users_skrill_wallet@email.com",
    "user_email": "john.doe@test.com"
}

Example of payout by token for Skrill:

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

{
    "api_version": 1,
    "method": "init",
    "merchant_account": "my_merchant_account",
    "merchant_password": "my_merchant_password",
    "transaction_unique_id": "payout_request_0001",
    "mid_reference": "MD0000000D37A8C1",
    "amount": 1.5,
    "currency": "USD",
    "callback_url": "https://merchant.com/callback",
    "type": "skrill",
    "token": "5814f79a-c8fc-40c2-8161-4e0u68cc13ed",
    "user_email": "john.doe@test.com"
}

Parameters of the payout request via Skrill:

FIELD MANDATORY TYPE DESCRIPTION
api_version yes int API version
method yes string Init method
merchant_account yes string Account of the merchant. Given by MaxPay.
merchant_password yes string Password of the merchant. Given by MaxPay.
transaction_unique_id yes string An unique Id of the transaction.
mid_reference conditional string MID reference, optional for payout by token, otherwise it’s required.
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.
type yes string “skrill” for this payment method.
user_ip no string User IP address.
user_id no string[1, 60] An unique Id of the user.
user_first_name no string The first name of the user.
user_last_name no string The last name of the user.
user_date_of_birth no string User date of birth in format “1970-01-28”
user_email no string Email of the user.
wallet_id conditional string Skrill wallet id. Pass to make payout to Skrill wallet. Pass only one of these fields
base_reference conditional string Reference of base Sale. Pass to make payout to customer account where sale came from (accepts all Skrill sale types except sale from Skrill wallet).
token conditional string Value of the Token. Pass to repeat previous payout or to make payout after Skrill sale (accepts all Skrill sale types, including Skrill Wallet).

Notification: only one of the parameters: wallet_id, base_reference or token should be sent in the request.

Example of the response in application/json format:

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

Response parameters:

Field Mandatory Type Description
sessionid yes string An unique Id of the session
timestamp yes UNIX timestamp Timestamp
status yes string Response status
code yes int Response code
message yes string Response description

Payout via Neteller

Example of the payout request via Neteller in application/json format:

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

{
    "api_version": 1,
    "method": "init",
    "merchant_account": "my_merchant_account",
    "merchant_password": "my_merchant_password",
    "transaction_unique_id": "payout_request_0001",
    "mid_reference": "MD0000000D37A8C1",
    "amount": 1.5,
    "currency": "USD",
    "callback_url": "https://merchant.com/callback",
    "user_id": "merchantUserId_00001",
    "user_ip": "127.0.0.1",
    "user_email": "john.doe@test.com",
    "type": "neteller"
}

Parameters of the payout request via Neteller:

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

Example of the Neteller payout request by token in application/json format:

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

{
    "api_version": 1,
    "method": "init",
    "merchant_account": "my_merchant_account",
    "merchant_password": "my_merchant_password",
    "transaction_unique_id": "payout_request_0001",
    "mid_reference": "MD0000000D37A8C1",
    "amount": 10,
    "currency": "USD",
    "callback_url": "https://merchant.com/callback",
    "user_id": "merchantUserId_00001",
    "user_ip": "127.0.0.1",
    "token": "token_value",
    "type": "neteller"
}

Notification: only one of the parameters: mid_reference or bank_code should be sent in the request. Also from these pair only one of the parameters: token or user_email should be sent in the request.

Example of the response in application/json format:

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

Response parameters:

Field Mandatory Type Description
sessionid yes string An unique Id of the session
timestamp yes UNIX timestamp Timestamp
status yes string Response status
code yes int Response code
message yes string Response description

Payout via Ecopayz

Example of the payout request via Ecopayz in application/json format

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

{
    "api_version": 1,
    "method": "init",
    "merchant_account": "my_merchant_account",
    "merchant_password": "my_merchant_password",
    "transaction_unique_id": "payout_request_0001",
    "mid_reference": "MD00000000000001",
    "amount": 1.5,
    "currency": "USD",
    "callback_url": "https://merchant.com/callback",
    "user_id": "merchantUserId_00001",
    "user_ip": "127.0.0.1",
    "user_email": "john.doe@test.com",
    "wallet_id": "1234567890",
    "type": "ecopayz"
}

Parameters of the payout request via Ecopayz:

Field Mandatory Type Description
api_version yes int API version
method yes string Init method
merchant_account yes string Account of the merchant. Given by MaxPay.
merchant_password yes string Password of the merchant. Given by MaxPay.
transaction_unique_id yes string An unique Id of the transaction.
mid_reference conditional string MID reference, pass to send payout to specific MID. If “wallet_id” specified, pass exactly one of these fields. If “token” specified, you can pass only “mid_reference” or pass nothing (previous MID by token will be used).
bank_code conditional string Bank code, pass for routing.
amount yes float\int Amount of payout request.
currency yes string Currency in ISO format. Examples: USD, EUR, GBP.
callback_url yes string The url of callback. It should have https protocol.
user_email yes string Email of the user
wallet_id conditional string ID of the wallet of user.
token conditional string Value of the Token. Mandatory if “user_email” not specified. Don’t pass “token” and “user_email” fields together.
user_ip no string User IP address.
type yes string “ecopayz” for this payment method
user_id no [1,60] string An unique Id of the user.
user_first_name no string The first name of the user.
user_last_name no string The last name of the user.
user_date_of_birth no string User date of birth in format “1970-01-28”

Example of the payout by token request via Ecopayz in application/json format:

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


{
    "api_version": 1,
    "method": "init",
    "merchant_account": "my_merchant_account",
    "merchant_password": "my_merchant_password",
    "transaction_unique_id": "payout_request_0001",
    "mid_reference": "MD00000000000001",
    "amount": 1.5,
    "currency": "USD",
    "callback_url": "https://merchant.com/callback",
    "user_id": "merchantUserId_00001",
    "user_ip": "127.0.0.1",
    "user_email": "john.doe@test.com",
    "token": "token_value",
    "type": "ecopayz"
}

Notification: only one of the parameters: token or wallet_id should be sent in the request.

Example of the response in application/json format:

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

Response parameters:

Field Mandatory Type Description
sessionid yes string An unique Id of the session
timestamp yes UNIX timestamp Timestamp
status yes string Response status
code yes int Response code
message yes string Response description

Payout via Crystal Payments

Example of the payout via CP request in application/json format:

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

{
    "api_version": "1",
    "method": "init",
    "merchant_account": "my_merchant_account",
    "merchant_password": "my_merchant_password",
    "transaction_unique_id": "payout_request_0001",
    "mid_reference": "MD00000000000003",
    "amount": 10,
    "currency": "CNY",
    "account_number": "1234",
    "bank_name": "Bank name",
    "bank_branch": "Bank Branch",
    "user_first_name": "John",
    "user_last_name": "Doe",
    "user_phone": "+1234567890",
    "user_email": "john.doe@test.com",
    "user_ip": "127.0.0.1",
    "callback_url": "https://merchant.com/callback",
    "type": "crystal_payments"
}

Parameters of the payout request via Crystal Payments:

FIELD MANDATORY TYPE DESCRIPTION
api_version yes int API version
method yes string Method “init”
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
amount yes float\int Amount of payout request
currency yes string Currency in ISO format, examples: USD, EUR, GBP
account_number yes string User account number
bank_name yes string User bank name
bank_branch yes string User bank branch
mid_reference conditional string MID reference, pass to send payout to specific MID. Pass exactly one of these fields.
bank_code conditional string Bank code, pass for routing.
user_first_name yes string The first name of the user
user_last_name yes string The last name of the user
user_phone yes string Phone number
user_email yes string Email of the user
user_ip yes string User IP address
callback_url yes string The url of callback, it should have https protocol
type yes string “crystal_payments” for this payment method
user_date_of_birth no string User date of birth in format “1970-01-28”
user_id no string[1, 60] An unique Id of the user

Notification: only one of the parameters: mid_reference or bank_code should be sent in the request.

Example of the response in application/json format:

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

Response parameters:

Field Mandatory Type Description
sessionid yes string An unique Id of the session
timestamp yes UNIX timestamp Timestamp
status yes string Response status
code yes int Response code
message yes string Response description

Payout via Ebanx

Example of the payout via Ebanx request in application/json format:

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

    {
        "api_version": 1,
        "method": "init",
        "merchant_account": "my_merchant_account",
        "merchant_password": "my_merchant_password",
        "transaction_unique_id": "payout_request_0001",
        "mid_reference": "MD00000000000003",
        "amount": "1.00",
        "currency": "USD",
        "callback_url": "https://merchant.com/callback",
        "user_country": "br",
        "user_first_name": "Han",
        "user_last_name": "Solo",
        "user_email": "john.doe@test.com",
        "user_date_of_birth": "1977-05-25",
        "user_document": "85351346893",
        "user_document_type": "cpf",
        "type": "ebanx",
        "user_id": "merchantUserId_00001",
        "user_ip": "127.0.0.1"
    }

Parameters of the payout request via Ebanx:

FIELD MANDATORY TYPE DESCRIPTION
api_version yes int API version
method yes string Method “init”
merchant_account yes string Account of the merchant Given by MaxPay
merchant_password yes string Password of the merchant Given by MaxPay
transaction_unique_id yes string An unique Id of the transaction
mid_reference conditional string MID reference, pass to send payout to specific MID. Pass exactly one of these fields.
bank_code conditional string Bank code, pass for routing.
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_country yes string[2] The two-letter country code for the customer country. The available codes are:
  • br: Brazil
  • cl: Chile
  • co: Colombia
  • mx: Mexico
  • pe: Peru
user_first_name yes string The first name of the user
user_last_name yes string The last name of the user
user_email yes string Email of the user
user_document yes string Payee national identification number * Brazil: CPF (natural person taxpayer ID) or CNPJ (business taxpayer ID).
  • Chile: RUT (Chilean taxation unique contributor roll identification number).
  • Colombia: Cédula de Ciudadanía – CC (National Identity Document)
  • or Cédula de Extranjería – CE (National Identity Document for Immigrants).
  • Peru: DNI (National Identity Document).
  • Mexico: Payee document is optional for Mexico.
user_document_type yes string Payee national identification number type
  • Brazil: CPF or CNPJ.
  • Chile: RUT.
  • Colombia: CC or CE.
  • Peru: DNI.
  • Mexico: Payee document type is optional for Mexico.
type yes string “ebanx” for this payment method
user_date_of_birth conditional string User date of birth in format “1970-01-28”
  • Optional in Brazil when the Payee document type is CNPJ
  • Required for all other
user_id no string[1, 60] An unique Id of the user
user_ip no string User IP address
user_phone no string Phone number

Notification: only one of the parameters: mid_reference or bank_code should be sent in the request.

Example of the response in application/json format:

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

Response parameters:

Field Mandatory Type Description
sessionid yes string An unique Id of the session
timestamp yes UNIX timestamp Timestamp
status yes string Response status
code yes int Response code
message yes string Response description

Payout cancellation

Example of payout cancellation request in application/json format: “Content-type: JSON, XML, POST” –data

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

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 which should be canceled.

Example of cancellation response in application/json format:

    {
        "sessionid": "777c3b-5766-5b4f470c-164adad89df-17a3",
        "timestamp": 1531922191,
        "status": "success",
        "code": 0,
        "message": "Request processed successfully"
    }

Response parameters of the payout cancellation:

Field Mandatory Type Description
sessionid yes string An unique Id of the session.
timestamp yes UNIX timestamp Timestamp
status yes string Response status
code yes int Response code
message yes string Response message.

Payout callback

Example of callback request to merchant in application/x-www-form-urlencoded format:


    token=5aaaa194-1d68-4ef8-a72f-009184ee03a6
    &reference=PTFF00000000396580CF
    &transaction_unique_id=payout_0716100000&status=success
    &code=0&message=Transaction processed successfully
    &checkSum=4804928393234a6cd05f177569147091d7138da25fc61d9ee5add357017239a6

Callback request parameters:

Field Mandatory Type Description
token yes string Hashed credit card value.
reference yes string An unique reference of the transaction.
transaction_unique_id yes string An unique ID of the transaction by merchant side
status yes string ['success’, 'decline’, 'error’] Response status
code yes int Response code
message yes string Response message.
checkSum yes string checkSum value of callback packet

Maxpay sends callback data to merchant in application/x-www-form-urlencoded format. Callback is received to a merchant when in response Maxpay got the code - 200 (it’s required), and body text - OK (it’s optional). In other cases, callback is not received to merchant and Maxpay will try periodically to re-send callback data. The number of attempts are limited.

checkSum calculation

checkSum calculation allows to compare value of the checkSum in callback request with own calculation.

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


    <?php

        // Example of the callback request to merchant, application/x-www-form-urlencoded format. 
        $callbackData = 'token=5aaaa194-1d68-4ef8-a72f-009184ee03a6&reference=PTFF00000000396580CF&transaction_unique_id=payout_0716100000&status=success&code=0&message=Transaction processed successfully&checkSum=4804928393234a6cd05f177569147091d7138da25fc61d9ee5add357017239a6';

        // Example of the sorted parameters. Also, private key, provided by Maxpay is added in the end of the line.
        $sortedData = 'code=0|message=Transaction processed successfully|reference=PTFF00000000396580CF|status=success|token=5aaaa194-1d68-4ef8-a72f-009184ee03a6|transaction_unique_id=payout_0716100000|your_private_signature';

        // Getting the result of checkSum calculation
        $countedCheckSum = hash('sha256', $sortedData);

    ?>

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

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

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

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

Callback 2.0

Example of the callback 2.0 request to merchant in application/json format:

Headers:
ACCEPT: */*
ACCEPT_ENCODING: gzip
CONNECTION: close
HOST: example.com
USER_AGENT: Go-http-client/1.1
GEOIP_COUNTRY_CODE: US
SSL: 1
X_SIGNATURE: c37484fc04e55e4a17ca3389f20010608b8822935badaac7275604854c6b5bf9

Body:
{
    "uniqueTransactionId":"hpp180926125439m7059a4040uf62e5bb29b97bc",
    "reference":"SLFF0000000040598D81",
    "uniqueUserId":"auto_AH1IqGXIu555VyLF",
    "totalAmount":5,
    "currency":"USD",
    "transactionType":"SALE",
    "status":"success",
    "message":"Transaction processed successfully",
    "code":0,
    "productList":[
        {   
            "productId":"p_6e30432104",
            "name":"Trial product witout description",
            "amount":5,
            "currency":"USD"
        }
    ],
    "testMode":"0"
}
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 merchant’s system.
totalAmount Total amount of transaction
currency The currency of transaction. ISO3 currencies.
transactionType The type of the transaction.
status Status of the transaction.
message An explanation message of the transaction. The detailed list could be found in “response codes” section below.
code The response code of the transaction. The detailed list could be found in “response codes” section below.
productList Array with product data
productList[productId] Id of the product
productList[name] Name of the product
productList[amount] Amount of the product
productList[currency] Currency of the product
testMode 0 - it means test mode

Maxpay sends callback 2.0 data to merchant in application/json format. Callback is received to a merchant when in response Maxpay got the code - 200 (it’s required), and body text - OK (it’s optional). In other cases, callback is not received and Maxpay will try periodically to re-send callback data. The number of attempts are limited. Be advised, that transaction status is better to handle by transaction code, not status or text message.

For signature calculation you should take sha256 from the callback string.

Transaction statuses

Payout transaction statuses:

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

Payout response codes

List of the response codes for payout transactions:

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

Query on demand API

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

Access to Maxpay Qod API

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

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

Qod Workflow

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

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

Qod Request formats

Qod Response formats

Sample code of QOD request:

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

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

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

Request parameters are general for all request types

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

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

Transactions

Example of response in JSON:

{
  "api_version": "1.0",
  "transactions": [
    {
      "transaction_type": "AUTH",
      "status": "SUCCESS",
      "mode": "CC",
      "reference": "ATFF00000000395376F6",
      "base_reference": null,
      "amount": 10,
      "currency": "GBP",
      "merchant": {
        "merchant_account": "TestQOD",
        "descriptor_merchant": "",
        "descriptor_phone": "",
        "merchant_domain_name": "",
        "merchant_product_name": "",
        "merchant_affiliate_id": ""
      },
      "user": {
        "first_name": "User",
        "last_name": "Test",
        "country": "GBR",
        "state": "xxx",
        "city": "London",
        "address": "123 Streetname",
        "zip": "11111",
        "user_ip": "1.1.1.1",
        "user_email": "testemail@testdomain.net",
        "user_phone": "+123456789012"
      },
      "card": {
          "card_holder": "Test Cardholder",
          "brand": null,
          "bank": null,
          "level": null,
          "type": null,
          "bin": "400002",
          "last": "5231",
          "exp_month": "07",
          "exp_year": "2019"
      },
      "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
bank string yes maxLength: { max: 255 }, array element Bank issuer
type string yes maxLength: { max: 255 }, array element Type of the card
bin string yes length: { size: 6 }, array element Card BIN data – the first 6 digits
last string yes length: { size: 4 }, array element Card number data – the 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,
        "currency": GBP,
        "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
currency string yes ISO3 Transaction currency
time float yes unix timestamp, array element Modified transaction time
update_time float yes unix timestamp, array element Modified transaction update time
code numeric\null yes length: { size: 4 }, array element Modified transaction response code, see Response codes table below
message string\null yes maxLength: { max: 255 }, array element Modified transaction response message, see Response codes table below
bank array\null yes Should be array Contains transaction bank data
id int yes maxLength: { max: 20 }, array element Bank identifier code
authcode string yes maxLength: { max: 45 }, array element Bank authorization code
time float yes unix timestamp, array element Bank transaction time

Fraud alerts

Example of response in JSON:

{
  "api_version": "1.0",
  "timestamp": 1495606195.6995,
  "session_id": "4ae6dd-6e8a-592523a8-15c39134850-0524",
  "merchant_account": "my_merchant_account",
  "fraudalerts": [
    {
      "fraud_alert": {
        "transaction": {
          "transaction_type": "SALE",
          "status": "SUCCESS",
          "mode": "CC",
          "reference": "SLFF00000000395BB0C3",
          "base_reference": null,
          "amount": 10.0,
          "currency": "GBP",
          "merchant": {
            "merchant_account": "my_merchant_account",
            "descriptor_merchant": "",
            "descriptor_phone": "",
            "merchant_domain_name": "",
            "merchant_product_name": "",
            "merchant_affiliate_id": ""
          },
          "user": {
            "first_name": "John",
            "last_name": "Doe",
            "country": "USA",
            "state": "NY",
            "city": "New York",
            "address": "123 Streetname",
            "zip": "12100",
            "user_ip": "127.0.0.1",
            "user_email": "testemail@testdomain.net",
            "user_phone": "+18001122334"
          },
          "card": {
            "card_holder": "John Doe",
            "brand": "VISA",
            "bank": "RIVER VALLEY CREDIT UNION",
            "level": "CLASSIC",
            "type": "CREDIT",
            "bin": "400002",
            "last": "5231",
            "exp_month": "07",
            "exp_year": "2019"
          },
          "bank": {
            "id": 356,
            "authcode": "",
            "time": null
          },
          "time": 1472785332.0,
          "token": "57c6cf4e-86e0-449d-b790-66cec8812686",
          "transaction_unique_id": "accept.1472785298.1611860711",
          "pares": "",
          "code": 0,
          "message": "SUCCESS"
        },
        "source": "ethoca",
        "alert_id": 123,
        "alert_timestamp": 1486986433.0,
        "receive_timestamp": 1486986433.6219,
        "reason_code": "0",
        "reason_description": "test",
        "arn": null
      }
    }
  ],
  "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
End merchant array - - - -
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
End user array - - - -
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
End card array - - - -
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
End bank array - - - -
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
End transaction array - - - -
source string yes maxLength: { max: 32 } Transaction unique identifier from bank side
alert_id int yes maxLength: { max: 20 }, array element fraud alert id
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
arn string\null yes maxLength: { max: 255 } Acquirer Reference Number
End fraud_alert array - - - -
status string yes maxLength: { max: 10 } Succesful QOD response should contains success status
code string yes length: { size: 4 } QOD response code
message string no maxLength: { max: 255 } QOD response code explanation

Ethoca alerts

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

Sample request for receiving ethoca fraud alerts:

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

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

Request parameters

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

Example of response:

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

Response parameters:

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

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

Sample request for alert confirmation:

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

Request parameters for alert confirmation

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

Example of response:

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

Response parameters:

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

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

Sample request of Bulk alert confirmation:

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

Request parameters for Bulk alert confirmation

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

Example of response:

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

Response parameters:

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

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

Sample request for alert feedback:

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

Request parameters for alert feedback

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

List of values for type field

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

Confirmed fraud states

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

Customer dispute states

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

Example of response:

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

Response parameters:

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

Request validation specified (not API) response codes

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

Empty response

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

Response parameters:

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

Erroneous response

Example of response in JSON:

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

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

Response parameters:

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

Response statuses

Code Description
success Succesful QOD response
error Unsuccesful QOD response

Qod API specified response codes

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

Balance API

Merchant balance

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

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

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

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

Parameters of balance request:

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

Example of response in JSON:

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

Parameters of balance response:

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

Balance per MID

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

{
    "api_version":1,
    "method": "MERCHANT_BALANCE_PER_MID",
    "merchant_account":"my_merchant_account",
    "merchant_password":"my_account_password",
    "time": 1504044107
}

Parameters of balance request:

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

Example of response in JSON:

{
    "sessionid": "a84112-5464-59a2213d-15e3c1b5764-4f69",
    "timestamp": 1504252222,
    "balance": [
        {
            "mid_name": "mid_1",
            "mid_reference": "MD0000000D22298F",
            "mid_balance": [
                {
                    "currency": "AFN",
                    "amount": 0
                },
                {
                    "currency": "CAD",
                    "amount": 83
                },
                {
                    "currency": "EUR",
                    "amount": -94
                },
                {
                    "currency": "NOK",
                    "amount": 176
                },
                {
                    "currency": "RUB",
                    "amount": 0
                },
                {
                    "currency": "UAH",
                    "amount": 0
                },
                {
                    "currency": "USD",
                    "amount": 111583
                }
            ]
        },
        {
            "mid_name": "mid_2",
            "mid_reference": "MD0000000D9D77SA",
            "mid_balance": [
                {
                    "currency": "AFN",
                    "amount": 0
                },
                {
                    "currency": "CAD",
                    "amount": 0
                },
                {
                    "currency": "EUR",
                    "amount": 7
                },
                {
                    "currency": "NOK",
                    "amount": 0
                },
                {
                    "currency": "RUB",
                    "amount": 0
                },
                {
                    "currency": "UAH",
                    "amount": 0
                },
                {
                    "currency": "USD",
                    "amount": -10
                }
            ]
        ],
    "status": "success",
    "code": 0,
    "message": "Request processed successfully"
}

Parameters of balance response:

Field Mandatory Type Description
sessionid yes string Session ID.
timestamp yes int Balance response time.
balance[mid_name] yes string Processing currency.
balance[mid_reference] yes string MID reference.
balance[mid_balance] yes string MID balance includes currencies and amounts.
mid_balance[currency] yes string Processing currency.
mid_balance[amount] yes float\int Processing amount.
status yes string Status of request.
code yes int Response code.
message yes string Response message.

Response codes

List of response codes

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

GENERAL 0 SUCCESS
1 GENERAL SYSTEM ERROR
2 DATABASE ERROR
3 INTERNAL SERVICE ERROR
10 INTERNAL SERVICE COMM ERROR
11 INTERNAL SERVICE TIMEOUT
12 SERVICE SSL ERROR
1000 GENERAL MERCHANT GATE ERROR
1001 GENERAL MERCHANT GATE ERROR
1002 MANDATORY FIELDS ARE MISSING
1003 INTERNAL COMM ERROR
1004 INVALID PARAMETER
1005 UNSUPPORTED API VERSION
2000 GENERAL MMS ERROR
2001 INVALID MERCHANT ACC PASSWORD
2002 COUNTRY RESTRICTIONS
2003 MERCHANT ACC IS NOT ACTIVE
2004 UNAUTHORIZED TRANSACTION
2005 MID NOT ACTIVE
2006 CURRENCY NOT ACTIVE
2007 AMOUNT RESTRICTIONS
2008 IP ADDRESS RESTRICTIONS
2009 MERCHANT NOT ACTIVE
2010 GATE NOT ACTIVE
2011 ENTITY ALREADY EXISTS
2012 ENTITY NOT FOUND
2013 BAD API CREDENTIALS
3000 GENERAL PROCESSING ERROR
3001 TRANSACTION UNIQUE ID ALREADY USED
3002 INVALID TOKEN
3003 INVALID REFFERENCE
3004 VOID NOT POSSIBLE
3005 REFUND NOT POSSIBLE
3006 TRANSACTION IS CB
3007 ILLEGAL INTERVAL
3008 ALREADY VOIDED
3009 ALREADY REFUNDED
3010 ALREADY SETTLED
3011 CARD TYPE NOT SUPPORTED
3012 ACCOUNT IS NOT 3D ENABLED
3013 REQUIRED 3DS
3014 TRANSACTION NOT FOUND FOR CHECK
3015 INVALID CURRENCY
3016 WRONG SETTLE AMOUNT
3017 WRONG MID CREDENTIALS
3018 MID IP ERROR
3019 VALIDATION FAILED
3020 INVALID CHARGEBACK
3021 TRANSACTION BLOCKED
3022 THE AMOUNT IS INCORRECT
3023 TRANSACTION IS ABORTED BY THE CUSTOMER
3024 TRANSACTION IS EXPIRED
3026 MODIFICATION STATUS CHANGE
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
3132 RECURRING IS STOPPED BY THE CUSTOMER
ANTIFRAUD 3200 GENERAL FRAUD DECLINE
3201 GENERAL MANUAL REVIEW
3202 VOLUME LIMIT EXCEEDED
3203 REFUND LIMIT EXCEEDED
3220 TRUST LIST FRAUD DECLINE
3221 TRUST LIST MANUAL REVIEW
Payout 3300 GENERAL DECLINE
3310 VALIDATION DECLINE
3311 INVALID MID REFERENCE
3330 UNREGISTERED CARD
FRS 4000 GENERAL RECONCILLIATION ERROR
4001 RECONCILLIATION INCOMPLETE
4002 RECONCILLIATION AMOUNT MISMATCH
4003 RECONCILLIATION COUNT MISMATCH
4004 GENERAL FRS ERROR
QOD 5000 QOD GENERAL ERROR
5001 QOD UNSUPPORTED API VERSION
5002 INVALID TIME ORDER
AUTH 6000 INTERNAL AUTH FAILURE
6001 WRONG CREDENTIALS
6002 ACCESS DENIED
6003 THE USER ALREADY EXISTS
6004 THE USER IS NOT FOUND
6005 THE ROLE IS NOT FOUND
6006 THE PERMISSION IS NOT FOUND
6007 THE TOKEN IS EXPIRED
6008 THE TOKEN IS NOT FOUND
6009 THE USER IS TEMPORARY BLOCKED
6010 THE PASSWORD IS EXPIRED
6011 THE PASSWORD IS INVALID
6012 THE PASSWORD IS PREVIOUSLY USED
7000 INTERNAL PAYMENT GATE ERROR
7101 INTERNAL PAYMENT GATE SENDER ERROR
7102 EXTERNAL COMMUNICATION ERROR
7103 EXTERNAL COMMUNICATION TIMEOUT

Behavior on response codes

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

API libraries

Maxpay hosted payment page client

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

Magento module

Module for Magento 1.9 is available on GitHub

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

Drupal module

Module for Drupal is available on GitHub

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

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

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

WooCommerce plugin

WooCommerce plugin is available on GitHub

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

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

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