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. Https required.
Live callback url Live callback url is for receiving responses from Maxpay. Https required.
Back button url Url for redirecting a user if the back button was clicked on the payment page

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-midreference='MD000000000023123131'
                data-uniqueTransactionId='transactionId123'
                data-productPublicId='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-backUrl='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-backUrl max - 255 characters parameter for sending a back step url for user
data-midreference max - 50 characters parameter for sending a transaction to determined MID
data-locale constant value from the list parameter for displaying a language on payment page

Send a query to support team in order to get MID reference values. Routing works only for credit card methods.

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-midreference='MD000000000023123131'
        data-uniqueTransactionId='transactionId123'
        data-productPublicId='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-backUrl='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-backUrl max - 255 characters parameter for sending a back step url for user
data-midreference max - 50 characters parameter for sending a transaction to determined MID
data-locale constant value from the list parameter for displaying a language on payment page

Send a query to support team in order to get MID reference values. Routing works only for credit card methods.

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='backUrl' 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
backUrl max - 255 characters parameter for sending a back step url for user
data-midreference max - 50 characters parameter for sending a transaction to determined MID
locale constant value from the list parameter for displaying a language on payment page

Send a query to support team in order to get MID reference values. Routing works only for credit card methods.

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 purpose: callback is a final response by Maxpay regarding a transaction status. HTTPS is required for the callback url.

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

Callback purpose: callback is a final response by Maxpay regarding a transaction status. HTTPS is required for the callback url. Callback 2.0 allows to receive all modifications regarding a processed transaction. For example: callback regarding refund or chargeback transaction.

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
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.
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"
Lithuanian "lt-LT

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 should 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.

Authorization API

Type of payment form Code example
Redirect <input type="hidden" name="transactionFlow" value='{"transactionType":"AUTH", "transactionLength":1, "transactionPeriod":"Day","postTransactionType":"SETTLE"}'>
Pop Up/iFrame data-transactionflow='{"transactionType":"AUTH", "transactionLength":1, "transactionPeriod":"Day","postTransactionType":"SETTLE"}'


PARAMETER REQUIRED TYPE DESCRIPTION
transactionType yes string Type of the transaction. The value should be "AUTH"
transactionLength yes int The length between "AUTH" and next type of the transaction ("SETTLE" or "VOID"). The length depends by acquirer side.
transactionPeriod yes string Transaction period. The value should be "day".
postTransactionType yes string Next type of the transaction after "AUTH". The values can be "VOID" or "SETTLE". "VOID" is to cancel authorization request. "SETTLE" is to capture authorization request.

Notice : You must provide product information in case to use Authorization API. You can use "productPublicId" or "customproduct" parameters.

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.
midReference optional MID reference parameter is for routing a transaction to specific MID.
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

Extended refund

Extended refund allows to issue partial-refunds via API requests.

Sample of the refund request


    array
       (
          'publicKey' => 'pkTest_5617970296ec43c48a2b5446d',
          'transactionId'=> 'hpp1467893228.4626mId571aId0',
          'signature' => '039539489c72f018ab7baee0389f735f',
          'amount' => 9.99,
          'currency' => 'USD'
       );

Request URL: https://hpp.maxpay.com/api/extended_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. Ihe value can be taken from Embed code (Payment forms section)
amount yes Amount of the refund
currency yes Currency of the refund

Sample of the refund response


    {
        "transactionId":"hppAR1495096440.3937mId3126aId1335",
        "reference": "RFF0000000039FDAEGG",
        "timestamp": 1614001691,
        "status": "success",
        "code": 0,
        "message": "Transaction processed successfully"
        "checkSum":"8237d19969c61517c155879c8cf5ce292ce39d948c6bba94364d8c658e4a7f26"
    }

Response parameters:

PARAMETER DESCRIPTION
transactionId Unique transaction Id
reference Reference of the transaction
timestamp Timestamp of the transaction
status Status of the transaction
code Response code
message Response message
checkSum Signature for callback parameters

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

CheckSum calculation for callback 1.0

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:

CheckSum calculation for callback 2.0

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

    <?php
        // Take callback body as a string
        $data = '{"uniqueTransactionId":"hpp121122113557m37186a23056u052f94975853","reference":"SLFF0000000CAA2A73AS","uniqueUserId":"user123","totalAmount":100,"currency":"USD","transactionType":"SALE","status":"success","message":"Transaction processed successfully","code":0,"productList":[{"productId":"Product123","name":"DEMO","amount":100,"currency":"USD"}],"testMode":"1"}'.'skLive_e7vSTkUv7dZJOf97ppasdWe34rCK2ElVb';

        // Count hash
        echo $result = hash('sha256', $data);

    ?>
  1. A callback body should be taken as a string and a private key should be added at the end of the string.
  2. Count a value by the formula: hash('sha256', $data) where $data is a callback body string with the private key.
  3. The counted value should be equal X-Signature value from the callback header.

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
Amount EUR custom_amount_eur /\d+(.\d{1,4})?/ Amount in EUR
Amount GBP custom_amount_gbr /\d+(.\d{1,4})?/ Amount in GBP
Amount USD custom_amount_usd /\d+(.\d{1,4})?/ Amount in USD
Bank advice custom_bank_advice /.{0,65535}/ Advice by the acquirer
Bank authcode custom_bank_authcode /.{0,255}/ Auth code from bank
Bank descriptor custom_bank_descriptor /.{0,255}/ Descriptor of 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 level custom_card_level /.{0,255}/ Level of the 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
Card_mask custom_card_mask /\d{6}*{4}\d{4}/ Bin and the last 4 digits of the card
Card_type custom_card_type /.{0,255}/ Type of the 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
Ds transaction id dsTransactionId /.{0,255}/ Directory server transaction id
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
Merchant advice code custom_merchant_advice_code /.{0,255}/ Merchant advice code obtained from Card Brand
Merchant advice text custom_merchant_advice_text /.{0,255}/ Explanation of Merchant advice code (MAC)
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
Processed_timestamp custom_processed_timestamp /\d+(.\d{1,4})?/ Time of the final transaction status
Sale version custom_sale_version /.{0,65535}/ Sale version of the transaction
Scheme transaction id custom_scheme_transaction_id /.{0,65535}/ Scheme transaction id
Secure storage id secure_storage_id /.{0,45}/ Hashed value of the PAN
Transaction_mode custom_transaction_mode /.{0,255}/ Mode of the transaction
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
User_address custom_user_address /.{0,255}/ Address of the user
User_city custom_user_city /.{0,255}/ City of the user
User_country custom_user_country /.{0,255}/ Country of the user
User_email custom_user_email /.{0,255}/ Email of the user
User_ip_country custom_user_ip_country /.{0,3}/ Country IP of the user
User_zip custom_user_zip /.{0,32}/ ZIP of the user

Maxpay 3DS Server custom parameters (response/callback):

NAME OF THE PARAMETER SEND TO MERCHANT RULES DESCRIPTION
3D version threeDVersion /.{0,255}/ Version of 3D
Cardholder info custom_3ds_cardholderinfo /.{0,128}/ Info on cardholder from bank issuer
CAVV cavv /.{0,65535}/ Cardholder Authentication Verification Value
ECI eci /\d*/ Electronic Commerce Indicator
Status reason custom_3ds_status_reason /.{0,255}/ Status of the 3DS

Validation exposition: MDN web docs

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.

To reproduce a declined status of the transaction, please, input an error code to product name parameter. For Custom product API paste 3100 error code or other from response list into "productName" parameter, it should be "productName":"3100". If product is set up in Merchant portal make changes in Products to sell section.

Postman Test Collection for HPP

Please find our Postman Test Collection for HPP (HPP collection.postman_collection.json) and configuration file (Environment for collection HPP.postman_environment.json) which allows checking different transaction types quickly using the Hosted Payment Page checkout and API solutions.

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" line and production IPs in "Production IPs" line.

e. Click on the button "Save".

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

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

  3. Test all transaction types regarding your bussiness model.

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

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

  6. Implement production credentials.

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

Host to host request formats

Test mode

Be advised: 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.

Postman Test Collection

Please find our Postman Test Collection and configuration file which allows checking different transaction types quickly using the Host to Host API solution. The current collection has:

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

Be advised: test credit cards are available only for test mode.

AUTH3D transaction

Sample code of the AUTH3D request in "application/json" format:

    {
        "api_version": 1,
        "merchant_account": "Account_MP_TRX",
        "merchant_password": "password123",
        "transaction_unique_id": "auth3d_request",
        "transaction_type": "AUTH3D",
        "amount": 9.99,
        "currency": "EUR",
        "card_number": "4012000300001003",
        "card_exp_month": "05",
        "card_exp_year": "2023",
        "cvv": "111",
        "first_name": "John",
        "last_name": "Doe",
        "card_holder": "John Doe",
        "address": "123 Street name.",
        "city": "New York",
        "state": "New York",
        "zip": "12100",
        "country": "USA",
        "user_phone": "+12025550000",
        "user_email": "johndoe@test.com",
        "user_ip": "127.0.0.1",
        "cof_type":"CIT-initial"
    }

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 described below.

Request parameters:

PARAMETER NAME REQUIRED FORMAT and RULE DESCRIPTION
api_version yes int
Possible value: 1		 API version
merchant_account yes string (6-32) Merchant account
merchant_password yes string (6-32) Account password
transaction_unique_id yes string (1-45) Unique transaction Id
transaction_type yes string
Possible value: AUTH3D		 Type of the transaction: AUTH3D
amount yes float (0 - 9999999.9999) Amount of the transaction
currency yes string (3)
ISO 4217 (alfa-3)		 Currency of the transaction
card_number yes string (13-19 digits)
Luhn algorithm		 Number of the card
card_exp_month yes string (2 digits) Card expiration month. Month number from '01' to '12'
card_exp_year yes string (4 digits) Card expiration year
cvv conditional string (3-4 digits) Card Verification Value
card_holder yes string (2-32) Cardholder name
first_name yes string (1-32) The first name of the customer
last_name yes string (1-32) The last name of the customer
address conditional string (2-64) Customer's address
city conditional string (2-32) Customer's city
state conditional string (1-32) Customer's state
zip conditional string (2-10) Customer's zip
country yes string (2-3)
ISO 3166-1 alpha-3		 Customer's country
user_phone conditional string (7-15) Customer's phone number. For testmode the value should be passed with + symbol
user_email yes string (6-255) Customer's email address
user_ip yes string (IPv4, IPv6) Customer's IP address. Not all acquirers support IPv6 format
merchant_user_id optional string (1-64) User Id on merchant's side
merchant_domain_name optional string (0-255) Merchant's domain name
merchant_affiliate_id optional string (0-255) Affiliate identifier
merchant_product_name optional string (0-255) Name of the product
descriptor_merchant optional string (0-255) Descriptor of the merchant
descriptor_phone optional string (0-255) Descriptor phone of the merchant
mid_reference optional string (16) Reference of the MID in Maxpay system
date_of_birth optional string (YYYY-MM-DD) Date of birth of the customer
cof_type optional enum ('CIT-initial', 'CIT-subsequent', 'MIT') The credentials on file(COF) is used to identify authorization requests that use stored credentials for a consumer, in order to improve authorization rates and reduce fraud. 'CIT-initial' - First transactions initiated by customer on your service (e.g. trial product, first subscription, one-time purchase etc.) 'CIT-subsequent' - Subsequent transactions initiated by customer (e.g. one-clicks, cross-sales). 'MIT' - Transactions initiated by merchant (e. g. rebill).

Be advised: In most cases conditional parameters are required for acquirers.

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

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

Sample code of the AUTH3D response in "application/json" format:

    {
        "api_version": 1,
        "merchant_account": "Account_MP_TRX",
        "sessionid": "81g47d-7avb-59103914-14be75ef73f-136e",
        "transaction_unique_id": "auth3d_request",
        "token": "5814f79a-c8fc-40c2-8161-4e0u68cc13ed",
        "reference": "A3FF000000439730A8E",
        "timestamp": 1634235313,
        "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 FORMAT and RULE DESCRIPTION
api_version int
Possible value: 1		 API version
merchant_account string (6-32) Merchant account
sessionid string (36) Id of the session
transaction_unique_id string (1-45) Unique transaction Id
token string (36) Hashed value of card number, expiry date and cardholder name
reference string (20) Reference of the transaction in Maxpay system
timestamp integer (unix timestamp) Timestamp of the transaction
authcode string or null (0-24) Authorization code
pareq string or null (65535) Payment Authentication Request (PaReq). Parameter may not be received
acs_url string or null (0-255) Access Control Server (ACS). Parameter may not be received
eci float
Possible values: 1, 2, 5, 6, 7		 Electronic Commerce Indicators (ECI). Parameter may not be received
status string
Possible values: success, decline, error		 Status of the transaction
code integer (1-4) Response code regarding the transaction result
message string (6-255) Response message regarding the transaction result

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" value="<MD>">
    </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.
MD MD (Merchant Data) – the reference number for the transaction. This parameter will be included in the request to the TermUrl so that the merchant will be able to identify the transaction.

Be advised: 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 by PARes * SETTLE - depends on acquirer side * SALE (with reference and pares as required fields) * VOID - depends on acquirer side * CHECK

AUTH transaction

Sample code of the AUTH request in "application/json" format:

    {
        "api_version":1,
        "merchant_account": "Account_MP_TRX",
        "merchant_password": "password123",
        "transaction_unique_id": "auth_request",
        "transaction_type": "AUTH",
        "amount": 9.99,
        "currency": "EUR",
        "card_number": "4111111111111111",
        "card_exp_month": "05",
        "card_exp_year": "2023",
        "cvv": "111",
        "first_name": "John",
        "last_name": "Doe",
        "card_holder": "John Doe",
        "address": "123 Street name.",
        "city": "New York",
        "state": "New York",
        "zip": "12100",
        "country": "USA",
        "user_phone": "+12025550000",
        "user_email": "johndoe@test.com",
        "user_ip": "127.0.0.1",
        "cof_type": "CIT-initial"
    }

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

Request parameters:

PARAMETER NAME REQUIRED FORMAT and RULE DESCRIPTION
api_version yes int
Possible value: 1		 API version
merchant_account yes string (6-32) Merchant account
merchant_password yes string (6-32) Account password
transaction_unique_id yes string (1-45) Unique transaction Id
transaction_type yes string
Possible value: AUTH		 Type of the transaction: AUTH
amount yes float (0 - 9999999.9999) Amount of the transaction
currency yes string (3)
ISO 4217 (alfa-3)		 Currency of the transaction
card_number yes string (13-19 digits)
Luhn algorithm		 Number of the card
card_exp_month yes string (2 digits) Card expiration month. Month number from '01' to '12'
card_exp_year yes string (4 digits) Card expiration year
cvv conditional string (3-4 digits) Card Verification Value
card_holder yes string (2-32) Cardholder name
first_name yes string (1-32) The first name of the customer
last_name yes string (1-32) The last name of the customer
address conditional string (2-64) Customer's address
city conditional string (2-32) Customer's city
state conditional string (1-32) Customer's state
zip conditional string (2-10) Customer's zip
country yes string (2-3)
ISO 3166-1 alpha-3		 Customer's country
user_phone conditional string (7-15) Customer's phone number. For testmode the value should be passed with + symbol
user_email yes string (6-255) Customer's email address
user_ip yes string (IPv4, IPv6) Customer's IP address. Not all acquirers support IPv6 format
merchant_user_id optional string (1-64) User Id on merchant's side
merchant_domain_name optional string (0-255) Merchant's domain name
merchant_affiliate_id optional string (0-255) Affiliate identifier
merchant_product_name optional string (0-255) Name of the product
descriptor_merchant optional string (0-255) Descriptor of the merchant
descriptor_phone optional string (0-255) Descriptor phone of the merchant
mid_reference optional string (16) Reference of the MID in Maxpay system
date_of_birth optional string (YYYY-MM-DD) Date of birth of the customer
cof_type optional enum('CIT-initial', 'CIT-subsequent', 'MIT') The credentials on file(COF) is used to identify authorization requests that use stored credentials for a consumer, in order to improve authorization rates and reduce fraud. 'CIT-initial' - First transactions initiated by customer on your service (e.g. trial product, first subscription, one-time purchase etc.) 'CIT-subsequent' - Subsequent transactions initiated by customer (e.g. one-clicks, cross-sales). 'MIT' - Transactions initiated by merchant (e. g. rebill).

Be advised: In most cases conditional parameters are required for acquirers.

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

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

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

Sample code of the AUTH response in "application/json" format:

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

Response parameters:

PARAMETER NAME FORMAT and RULE DESCRIPTION
api_version int
Possible value: 1		 API version
merchant_account string (6-32) Merchant account
sessionid string (36) Id of the session
transaction_unique_id string (1-45) Unique transaction Id
token string (36) Hashed value of card number, expiry date and cardholder name
reference string (20) Reference of the transaction in Maxpay system
timestamp integer (unix timestamp) Timestamp of the transaction
authcode string or null (0-24) Authorization code
status string
Possible values: success, decline, error		 Status of the transaction
code integer (1-4) Response code regarding the transaction result
message string (6-255) Response message regarding the transaction result

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 the AUTH (by token) request in "application/json" format:

    {
        "api_version": 1,
        "merchant_account": "Account_MP_TRX",
        "merchant_password": "merchant_password",
        "transaction_unique_id": "auth_by_token_request",
        "transaction_type": "AUTH",
        "amount": 9.99,
        "currency": "EUR",
        "first_name": "John",
        "last_name": "Doe",
        "card_holder": "John Doe",
        "address": "123 Street name.",
        "city": "New York",
        "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",
        "cof_type":"CIT-initial"
    }

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

Request parameters:

PARAMETER NAME REQUIRED FORMAT and RULE DESCRIPTION
api_version yes int
Possible value: 1		 API version
merchant_account yes string (6-32) Merchant account
merchant_password yes string (6-32) Account password
transaction_unique_id yes string (1-45) Unique transaction Id
transaction_type yes string
Possible value: AUTH		 Type of the transaction: AUTH
amount yes float (0 - 9999999.9999) Amount of the transaction
currency yes string (3)
ISO 4217 (alfa-3)		 Currency of the transaction
token yes string (36) Hashed value of card number, expiry date and cardholder name
card_holder yes string (2-32) Cardholder name
first_name yes string (1-32) The first name of the customer
last_name yes string (1-32) The last name of the customer
address conditional string (2-64) Customer's address
city conditional string (2-32) Customer's city
state conditional string (1-32) Customer's state
zip conditional string (2-10) Customer's zip
country yes string (2-3)
ISO 3166-1 alpha-3		 Customer's country
user_phone conditional string (7-15) Customer's phone number. For testmode the value should be passed with + symbol
user_email yes string (6-255) Customer's email address
user_ip yes string (IPv4, IPv6) Customer's IP address. Not all acquirers support IPv6 format
merchant_user_id optional string (1-64) User Id on merchant's side
merchant_domain_name optional string (0-255) Merchant's domain name
merchant_affiliate_id optional string (0-255) Affiliate identifier
merchant_product_name optional string (0-255) Name of the product
descriptor_merchant optional string (0-255) Descriptor of the merchant
descriptor_phone optional string (0-255) Descriptor phone of the merchant
mid_reference optional string (16) Reference of the MID in Maxpay system
date_of_birth optional string (YYYY-MM-DD) Date of birth of the customer
cof_type optional enum('CIT-initial', 'CIT-subsequent', 'MIT') The credentials on file(COF) is used to identify authorization requests that use stored credentials for a consumer, in order to improve authorization rates and reduce fraud. 'CIT-initial' - First transactions initiated by customer on your service (e.g. trial product, first subscription, one-time purchase etc.) 'CIT-subsequent' - Subsequent transactions initiated by customer (e.g. one-clicks, cross-sales). 'MIT' - Transactions initiated by merchant (e. g. rebill).
base_reference no string (20) Reference from the intial transaction

Be advised: In most cases conditional parameters are required for acquirers.

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

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

Be advised: 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 "application/json" format:

    {
        "api_version": 1,
        "merchant_account": "Account_MP_TRX",
        "sessionid": "543e2136-d46c-4d7d-a3b3-075cf9af6dea",
        "transaction_unique_id": "auth_by_token_request",
        "token": "5524fa52-75d8-4c7a-84ec-039d3097ab6f",
        "reference": "ATFF0000000039FDA11F",
        "timestamp": 1618001694,
        "authcode": "authcode_1518565221.44",
        "status": "decline",
        "code": 3100,
        "message": "General bank decline"
    }

Response parameters:

PARAMETER NAME FORMAT and RULE DESCRIPTION
api_version int
Possible value: 1		 API version
merchant_account string (6-32) Merchant account
sessionid string (36) Id of the session
transaction_unique_id string (1-45) Unique transaction Id
token string (36) Hashed value of card number, expiry date and cardholder name
reference string (20) Reference of the transaction in Maxpay system
timestamp integer (unix timestamp) Timestamp of the transaction
authcode string or null (0-24) Authorization code
status string
Possible values: success, decline, error		 Status of the transaction
code integer (1-4) Response code regarding the transaction result
message string (6-255) Response message regarding the transaction result

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 the AUTH (by PARes) request in "application/json" format:

    {
        "api_version": 1,
        "merchant_account": "Account_MP_TRX",
        "merchant_password": "password123",
        "transaction_unique_id": "auth_by_pares_request",
        "transaction_type": "AUTH",
        "amount": 9.99,
        "currency": "EUR",
        "reference": "A3FF000000439730A8E",
        "pares": "pares_value",
        "cof_type": "CIT-initial"
    }

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 FORMAT and RULE DESCRIPTION
api_version yes int
Possible value: 1		 API version
merchant_account yes string (6-32) Merchant account
merchant_password yes string (6-32) Account password
transaction_unique_id yes string (1-45) Unique transaction Id
transaction_type yes string
Possible value: AUTH		 Type of the transaction: AUTH
amount yes float (0 - 9999999.9999) Amount of the transaction
currency yes string (3)
ISO 4217 (alfa-3)		 Currency of the transaction
reference yes string (20) Reference of the base transation (AUTH3D)
cvv optional string (3-4 digits) Card Verification Value
pares optional string (65535) Payer Authentication Response (PARes)
merchant_user_id optional string (1-64) User Id on merchant's side
merchant_domain_name optional string (0-255) Merchant's domain name
merchant_affiliate_id optional string (0-255) Affiliate identifier
merchant_product_name optional string (0-255) Name of the product
descriptor_merchant optional string (0-255) Descriptor of the merchant
descriptor_phone optional string (0-255) Descriptor phone of the merchant
cof_type optional enum('CIT-initial', 'CIT-subsequent', 'MIT') The credentials on file(COF) is used to identify authorization requests that use stored credentials for a consumer, in order to improve authorization rates and reduce fraud. 'CIT-initial' - First transactions initiated by customer on your service (e.g. trial product, first subscription, one-time purchase etc.) 'CIT-subsequent' - Subsequent transactions initiated by customer (e.g. one-clicks, cross-sales). 'MIT' - Transactions initiated by merchant (e. g. rebill).

Be advised: 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.

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

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

Sample code of the AUTH (by PARes) response in "application/json" format:

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

Response parameters:

PARAMETER NAME FORMAT and RULE DESCRIPTION
api_version int
Possible value: 1		 API version
merchant_account string (6-32) Merchant account
sessionid string (36) Id of the session
transaction_unique_id string (1-45) Unique transaction Id
token string (36) Hashed value of card number, expiry date and cardholder name
reference string (20) Reference of the transaction in Maxpay system
timestamp integer (unix timestamp) Timestamp of the transaction
authcode string or null (0-24) Authorization code
eci float
Possible values: 1, 2, 5, 6, 7		 Electronic Commerce Indicators (ECI). Parameter may not be received
status string
Possible values: success, decline, error		 Status of the transaction
code integer (1-4) Response code regarding the transaction result
message string (6-255) Response message regarding the transaction result

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 the SETTLE request in "application/json" format:

    {
        "api_version": 1,
        "merchant_account": "Account_MP_TRX",
        "merchant_password": "password123",
        "transaction_unique_id": "settle_request",
        "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 FORMAT and RULE DESCRIPTION
api_version yes int
Possible value: 1		 API version
merchant_account yes string (6-32) Merchant account
merchant_password yes string (6-32) Account password
transaction_unique_id yes string (1-45) Unique transaction Id
transaction_type yes string
Possible value: SETTLE		 Type of the transaction: SETTLE
amount yes float (0 - 9999999.9999) Amount of the transaction
currency yes string (3)
ISO 4217 (alfa-3)		 Currency of the transaction
reference yes string (20) Reference of the base transation (AUTH)
merchant_user_id optional string (1-64) User Id on merchant's side
merchant_domain_name optional string (0-255) Merchant's domain name
merchant_affiliate_id optional string (0-255) Affiliate identifier
merchant_product_name optional string (0-255) Name of the product
descriptor_merchant optional string (0-255) Descriptor of the merchant
descriptor_phone optional string (0-255) Descriptor phone of the merchant

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

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

Sample code of the SETTLE response in "application/json" format:

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

Response parameters:

PARAMETER NAME FORMAT and RULE DESCRIPTION
api_version int
Possible value: 1		 API version
merchant_account string (6-32) Merchant account
sessionid string (36) Id of the session
transaction_unique_id string (1-45) Unique transaction Id
token string (36) Hashed value of card number, expiry date and cardholder name
reference string (20) Reference of the transaction in Maxpay system
timestamp integer (unix timestamp) Timestamp of the transaction
authcode string or null (0-24) Authorization code
status string
Possible values: success, decline, error		 Status of the transaction
code integer (1-4) Response code regarding the transaction result
message string (6-255) Response message regarding the transaction result

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 the SALE3D request in "application/json" format:

    {
        "api_version": 1,
        "merchant_account": "Account_MP_TRX",
        "merchant_password": "password123",
        "transaction_unique_id": "sale3d_request",
        "transaction_type": "SALE3D",
        "amount": 10,
        "currency": "USD",
        "card_number": "5191330000004415",
        "card_exp_month": "05",
        "card_exp_year": "2023",
        "cvv": "121",
        "first_name": "John",
        "last_name": "Doe",
        "card_holder": "John Doe",
        "address": "123 Street name.",
        "city": "New York",
        "state":"New York",
        "zip": "12100",
        "country": "USA",
        "user_phone": "+12025550000",
        "user_email": "johndoe@test.com",
        "user_ip": "127.0.0.1",
        "callback_url": "https://merchant.com/callback",
        "redirect_url": "https://merchant.com/redirect",
        "cof_type": "CIT-initial"
    }

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 FORMAT and RULE DESCRIPTION
api_version yes int
Possible value: 1		 API version
merchant_account yes string (6-32) Merchant account
merchant_password yes string (6-32) Account password
transaction_unique_id yes string (1-45) Unique transaction Id
transaction_type yes string
Possible value: SALE3D		 Type of the transaction: SALE3D
amount yes float (0 - 9999999.9999) Amount of the transaction
currency yes string (3)
ISO 4217 (alfa-3)		 Currency of the transaction
card_number yes string (13-19 digits)
Luhn algorithm		 Number of the card
card_exp_month yes string (2 digits) Card expiration month. Month number from '01' to '12'
card_exp_year yes string (4 digits) Card expiration year
cvv conditional string (3-4 digits) Card Verification Value
card_holder yes string (2-32) Cardholder name
token conditional string (36) Hashed value of card number, expiry date and cardholder name. Required to use with CVV
first_name yes string (1-32) The first name of the customer
last_name yes string (1-32) The last name of the customer
address conditional string (2-64) Customer's address
city conditional string (2-32) Customer's city
state conditional string (1-32) Customer's state
zip conditional string (2-10) Customer's zip
country yes string (2-3)
ISO 3166-1 alpha-3		 Customer's country
user_phone conditional string (7-15) Customer's phone number. For testmode the value should be passed with + symbol
user_email yes string (6-255) Customer's email address
user_ip yes string (IPv4, IPv6) Customer's IP address. Not all acquirers support IPv6 format
callback_url yes Not Empty String
https required		 Once the order has been processed merchant will receive a final response (callback) regarding the transaction status to this URL
redirect_url yes Not Empty String
https required		 Once the verification process has been done a customer will be redirected to this URL
merchant_user_id optional string (1-64) User Id on merchant's side
merchant_domain_name optional string (0-255) Merchant's domain name
merchant_affiliate_id optional string (0-255) Affiliate identifier
merchant_product_name optional string (0-255) Name of the product
descriptor_merchant optional string (0-255) Descriptor of the merchant
descriptor_phone optional string (0-255) Descriptor phone of the merchant
mid_reference optional string (16) Reference of the MID in Maxpay system
date_of_birth optional string (YYYY-MM-DD) Date of birth of the customer
cof_type optional enum('CIT-initial', 'CIT-subsequent', 'MIT') The credentials on file(COF) is used to identify authorization requests that use stored credentials for a consumer, in order to improve authorization rates and reduce fraud. 'CIT-initial' - First transactions initiated by customer on your service (e.g. trial product, first subscription, one-time purchase etc.) 'CIT-subsequent' - Subsequent transactions initiated by customer (e.g. one-clicks, cross-sales). 'MIT' - Transactions initiated by merchant (e. g. rebill).
dynamic_3d optional string
Possible value: true, false		 This parameter allows transforming the transaction type from SALE3D to SALE based on the payload.

Be advised: In most cases conditional parameters are required for acquirers.

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

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

Sample code of the SALE3D response in "application/json" format:

    {
        "api_version": 1,
        "merchant_account": "Account_MP_TRX",
        "sessionid": "543e2136-d46c-4d7d-a3b3-075cf9adkl21",
        "transaction_unique_id": "sale3d_request",
        "token": "5524fa52-75d8-4c7a-84ec-039d3097ab6g",
        "reference": "S3FF0000000039FDAEGG",
        "timestamp": 1638001694,
        "authcode": "",
        "eci": 5,
        "acs_url": "https://acs.bank.com/authentication",
        "authcode": "",
        "status": "success",
        "code": 0,
        "message": "Transaction processed successfully"
    }

Response parameters:

PARAMETER NAME FORMAT and RULE DESCRIPTION
api_version int
Possible value: 1		 API version
merchant_account string (6-32) Merchant account
sessionid string (36) Id of the session
transaction_unique_id string (1-45) Unique transaction Id
token string (36) Hashed value of card number, expiry date and cardholder name
reference string (20) Reference of the transaction in Maxpay system
timestamp integer (unix timestamp) Timestamp of the transaction
authcode string or null (0-24) Authorization code
acs_url string or null (0-255) Access Control Server (ACS). Parameter may not be received
eci float
Possible values: 1, 2, 5, 6, 7		 Electronic Commerce Indicators (ECI). Parameter may not be received
status string
Possible values: success, decline, error		 Status of the transaction
code integer (1-4) Response code regarding the transaction result
message string (6-255) Response message regarding the transaction result
dynamic_3d string
Possible value: true, false		 The response is related to the transaction transformation. True means that the transaction was transformed. False means that the transaction was not transformed.

Callback

Sample code of the callback request for SALE3D transaction 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 is a final response for SALE3D transaction regarding the status of the transaction. 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 NAME FORMAT and RULE DESCRIPTION
token string (36) Hashed value of card number, expiry date and cardholder name
reference string (20) Reference of the transaction in Maxpay system
transaction_unique_id string (1-45) Unique transaction Id
status string
Possible values: success, decline, error		 Status of the transaction
code integer (1-4) Response code regarding the transaction result
message string (6-255) Response message regarding the transaction result
checkSum string (64) Signature for callback parameters

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

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_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.

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:

Dynamic 3D

Purpose: Dynamic 3D is designed to transform the transaction type from SALE3D to SALE based on the payload data request. The required parts of these transformations are:

Example: Merchant would like to transform all USA card transactions to the SALE transaction type. All initials requests are going as a SALE3D transaction type. In this case, the Merchant should pass "dynamic_3d": "true" in the payload request. Also, the required part is that the Maxpay team should configure the rule based on the payload request to allow the transformation from SALE3D to SALE for the USA cards. If both these actions comply with the requirements - requests with the USA cards will be transformed to the SALE transaction type.

Dynamic 3D sample cases and actions

Case dynamic_3d in the request Ruleset at Maxpay Dynamic 3D execution Result
1 "dynamic_3d": "true" set payload triggered The transaction request will be transformed to SALE. In the API response will be provided "dynamic_3d": "true" which means that Preprocessor rules were triggered and it's a final response for this request. The callback request is not provided.
2 "dynamic_3d": "true" set payload triggered The transaction request won't be transformed to SALE. In the API response will be provided "dynamic_3d": "false" and "acs_url". The merchant should redirect a customer to the ACS URL to perform 3DS verification. The callback request will be the final response for the merchant.
3 "dynamic_3d": "true" not set nothing to trigger The transaction request won't be transformed to SALE, it will be SALE3D. In the API response will be provided "acs_url" without the "dynamic_3d" parameter. The merchant should redirect a customer to the ACS URL to perform 3DS verification. The callback request will be the final response for the merchant.
4 without set nothing to trigger The transaction request won't be transformed to SALE, it will be SALE3D. In the API response will be provided "acs_url" without the "dynamic_3d" parameter. The merchant should redirect a customer to the ACS URL to perform 3DS verification. The callback request will be the final response for the merchant.
5 without not set nothing to trigger The transaction request won't be transformed to SALE, it will be SALE3D. In the API response will be provided "acs_url" without the "dynamic_3d" parameter. The merchant should redirect a customer to the ACS URL to perform 3DS verification. The callback request will be the final response for the merchant.
6 "dynamic_3d": "false" set nothing to trigger The transaction request won't be transformed to SALE, it will be SALE3D. In the API response will be provided "acs_url" without the "dynamic_3d" parameter. The merchant should redirect a customer to the ACS URL to perform 3DS verification. The callback request will be the final response for the merchant.
7 "dynamic_3d": "false" not set nothing to trigger The transaction request won't be transformed to SALE, it will be SALE3D. In the API response will be provided "acs_url" without the "dynamic_3d" parameter. The merchant should redirect a customer to the ACS URL to perform 3DS verification. The callback request will be the final response for the merchant.

SALE transaction

Sample code of the SALE request in "application/json" format:

    {
        "api_version": 1,
        "merchant_account": "Account_MP_TRX",
        "merchant_password": "password123",
        "transaction_unique_id": "sale_request",
        "transaction_type": "SALE",
        "amount": 9.99,
        "currency": "EUR",
        "card_number": "4111111111111111",
        "card_exp_month": "09",
        "card_exp_year": "2023",
        "cvv": "121",
        "first_name": "John",
        "last_name": "Doe",
        "card_holder": "John Doe",
        "address": "123 Street name.",
        "city": "New York",
        "state": "New York",
        "zip": "12100",
        "country": "USA",
        "user_phone": "+12025550000",
        "user_email": "johndoe@test.com",
        "user_ip": "127.0.0.1",
        "cof_type": "CIT-initial"
    }

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 FORMAT and RULE DESCRIPTION
api_version yes int
Possible value: 1		 API version
merchant_account yes string (6-32) Merchant account
merchant_password yes string (6-32) Account password
transaction_unique_id yes string (1-45) Unique transaction Id
transaction_type yes string
Possible value: SALE		 Type of the transaction: SALE
amount yes float (0 - 9999999.9999) Amount of the transaction
currency yes string (3)
ISO 4217 (alfa-3)		 Currency of the transaction
card_number yes string (13-19 digits)
Luhn algorithm		 Number of the card
card_exp_month yes string (2 digits) Card expiration month. Month number from '01' to '12'
card_exp_year yes string (4 digits) Card expiration year
cvv conditional string (3-4 digits) Card Verification Value
card_holder yes string (2-32) Cardholder name
token conditional string (36) Hashed value of card number, expiry date and cardholder name. Required to use with CVV
first_name yes string (1-32) The first name of the customer
last_name yes string (1-32) The last name of the customer
address conditional string (2-64) Customer's address
city conditional string (2-32) Customer's city
state conditional string (1-32) Customer's state
zip conditional string (2-10) Customer's zip
country yes string (2-3)
ISO 3166-1 alpha-3		 Customer's country
user_phone conditional string (7-15) Customer's phone number. For testmode the value should be passed with + symbol
user_email yes string (6-255) Customer's email address
user_ip yes string (IPv4, IPv6) Customer's IP address. Not all acquirers support IPv6 format
merchant_user_id optional string (1-64) User Id on merchant's side
merchant_domain_name optional string (0-255) Merchant's domain name
merchant_affiliate_id optional string (0-255) Affiliate identifier
merchant_product_name optional string (0-255) Name of the product
descriptor_merchant optional string (0-255) Descriptor of the merchant
descriptor_phone optional string (0-255) Descriptor phone of the merchant
mid_reference optional string (16) Reference of the MID in Maxpay system
date_of_birth optional string (YYYY-MM-DD) Date of birth of the customer
cof_type optional enum('CIT-initial', 'CIT-subsequent', 'MIT') The credentials on file(COF) is used to identify authorization requests that use stored credentials for a consumer, in order to improve authorization rates and reduce fraud. 'CIT-initial' - First transactions initiated by customer on your service (e.g. trial product, first subscription, one-time purchase etc.) 'CIT-subsequent' - Subsequent transactions initiated by customer (e.g. one-clicks, cross-sales). 'MIT' - Transactions initiated by merchant (e. g. rebill).
custom_CAVV conditional,
required for 3DS completion		 string (28) CAVV Result Code
custom_XID conditional,
required for 3DS completion		 string (28) Transaction identifier resulting from authentication processing. Base64 encoded.
custom_TransactionStatus conditional,
required for 3DS completion		 string (2) Electronic Commerce Indicator (ECI). The ECI value is part of the two data elements that indicate the transaction was processed electronically. * 02 or 05 - Fully Authenticated Transaction * 01 or 06 - Attempted Authentication Transaction * 00 or 07 - Non 3-D Secure Transaction
custom_DsTransId conditional,
required for 3DS completion		 string (36) Unique transaction identifier assigned by the Directory Server (DS) to identify a single transaction.

Be advised: In most cases conditional parameters are required for acquirers.

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

Sample code of the SALE response in "application/json" format:

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

Response parameters:

PARAMETER NAME FORMAT and RULE DESCRIPTION
api_version int
Possible value: 1		 API version
merchant_account string (6-32) Merchant account
sessionid string (36) Id of the session
transaction_unique_id string (1-45) Unique transaction Id
token string (36) Hashed value of card number, expiry date and cardholder name
reference string (20) Reference of the transaction in Maxpay system
timestamp integer (unix timestamp) Timestamp of the transaction
authcode string or null (0-24) Authorization code
status string
Possible values: success, decline, error		 Status of the transaction
code integer (1-4) Response code regarding the transaction result
message string (6-255) Response message regarding the transaction result

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

Sample code of the SALE (by token) request in "application/json" format:

    {
        "api_version": 1,
        "merchant_account": "Account_MP_TRX",
        "merchant_password": "password123",
        "transaction_unique_id": "sale_by_token_request",
        "transaction_type": "SALE",
        "amount": 9.99,
        "currency": "EUR",
        "first_name": "John",
        "last_name": "Doe",
        "card_holder": "John Doe",
        "address": "123 Street name.",
        "city": "New York",
        "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-039d-97ab6f",
        "cof_type": "MIT"
    }

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

Request parameters:

PARAMETER NAME REQUIRED FORMAT and RULE DESCRIPTION
api_version yes int
Possible value: 1		 API version
merchant_account yes string (6-32) Merchant account
merchant_password yes string (6-32) Account password
transaction_unique_id yes string (1-45) Unique transaction Id
transaction_type yes string
Possible value: SALE		 Type of the transaction: SALE
amount yes float (0 - 9999999.9999) Amount of the transaction
currency yes string (3)
ISO 4217 (alfa-3)		 Currency of the transaction
token yes string (36) Hashed value of card number, expiry date and cardholder name
card_holder yes string (2-32) Cardholder name
first_name yes string (1-32) The first name of the customer
last_name yes string (1-32) The last name of the customer
address conditional string (2-64) Customer's address
city conditional string (2-32) Customer's city
state conditional string (1-32) Customer's state
zip conditional string (2-10) Customer's zip
country yes string (2-3)
ISO 3166-1 alpha-3		 Customer's country
user_phone conditional string (7-15) Customer's phone number. For testmode the value should be passed with + symbol
user_email yes string (6-255) Customer's email address
user_ip yes string (IPv4, IPv6) Customer's IP address. Not all acquirers support IPv6 format
merchant_user_id optional string (1-64) User Id on merchant's side
merchant_domain_name optional string (0-255) Merchant's domain name
merchant_affiliate_id optional string (0-255) Affiliate identifier
merchant_product_name optional string (0-255) Name of the product
descriptor_merchant optional string (0-255) Descriptor of the merchant
descriptor_phone optional string (0-255) Descriptor phone of the merchant
mid_reference optional string (16) Reference of the MID in Maxpay system
date_of_birth optional string (YYYY-MM-DD) Date of birth of the customer
cof_type optional enum('CIT-initial', 'CIT-subsequent', 'MIT') The credentials on file(COF) is used to identify authorization requests that use stored credentials for a consumer, in order to improve authorization rates and reduce fraud. 'CIT-initial' - First transactions initiated by customer on your service (e.g. trial product, first subscription, one-time purchase etc.) 'CIT-subsequent' - Subsequent transactions initiated by customer (e.g. one-clicks, cross-sales). 'MIT' - Transactions initiated by merchant (e. g. rebill).
base_reference no string (20) Reference from the intial transaction

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

Sample code of the SALE (by token) response in "application/json" format:

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

Response parameters:

PARAMETER NAME FORMAT and RULE DESCRIPTION
api_version int
Possible value: 1		 API version
merchant_account string (6-32) Merchant account
sessionid string (36) Id of the session
transaction_unique_id string (1-45) Unique transaction Id
token string (36) Hashed value of card number, expiry date and cardholder name
reference string (20) Reference of the transaction in Maxpay system
timestamp integer (unix timestamp) Timestamp of the transaction
authcode string or null (0-24) Authorization code
status string
Possible values: success, decline, error		 Status of the transaction
code integer (1-4) Response code regarding the transaction result
message string (6-255) Response message regarding the transaction result

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 the SALE (by PARes) transaction request:

    {
        "api_version": 1,
        "merchant_account": "Account_MP_TRX",
        "merchant_password": "password123",
        "transaction_unique_id": "sale_by_pares_request",
        "transaction_type": "SALE",
        "amount": 19.99,
        "currency": "EUR",
        "first_name": "John",
        "last_name": "Doe",
        "address": "123 Street name.",
        "city": "New York",
        "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",
        "cof_type": "CIT-initial"
    }

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 FORMAT and RULE DESCRIPTION
api_version yes int
Possible value: 1		 API version
merchant_account yes string (6-32) Merchant account
merchant_password yes string (6-32) Account password
transaction_unique_id yes string (1-45) Unique transaction Id
transaction_type yes string
Possible value: SALE		 Type of the transaction: SALE
amount yes float (0 - 9999999.9999) Amount of the transaction
currency yes string (3)
ISO 4217 (alfa-3)		 Currency of the transaction
reference yes string (20) Reference of the base transation (AUTH3D)
cvv optional string (3-4 digits) Card Verification Value
pares optional string (65535) Payer Authentication Response (PARes)
merchant_user_id optional string (1-64) User Id on merchant's side
merchant_domain_name optional string (0-255) Merchant's domain name
merchant_affiliate_id optional string (0-255) Affiliate identifier
merchant_product_name optional string (0-255) Name of the product
descriptor_merchant optional string (0-255) Descriptor of the merchant
descriptor_phone optional string (0-255) Descriptor phone of the merchant
cof_type optional enum('CIT-initial', 'CIT-subsequent', 'MIT') The credentials on file(COF) is used to identify authorization requests that use stored credentials for a consumer, in order to improve authorization rates and reduce fraud. 'CIT-initial' - First transactions initiated by customer on your service (e.g. trial product, first subscription, one-time purchase etc.) 'CIT-subsequent' - Subsequent transactions initiated by customer (e.g. one-clicks, cross-sales). 'MIT' - Transactions initiated by merchant (e. g. rebill).

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

Sample code of the SALE (by PARes) response in "application/json" format:

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

Response parameters:

PARAMETER NAME FORMAT and RULE DESCRIPTION
api_version int
Possible value: 1		 API version
merchant_account string (6-32) Merchant account
sessionid string (36) Id of the session
transaction_unique_id string (1-45) Unique transaction Id
token string (36) Hashed value of card number, expiry date and cardholder name
reference string (20) Reference of the transaction in Maxpay system
timestamp integer (unix timestamp) Timestamp of the transaction
authcode string or null (0-24) Authorization code
status string
Possible values: success, decline, error		 Status of the transaction
code integer (1-4) Response code regarding the transaction result
message string (6-255) Response message regarding the transaction result

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

SALE (by encrypted ApplePay token) transaction

Example of encrypted ApplePay token (lines are shortened for readability):

  {
          "paymentData": {
              "data": "2/hHE78JrJjjra0l8BPrLcLb..AW+s5uBTkbmMX1g==",
              "signature": "BIAGCSqGSIb3DQEHAqCAMIACAQ..yfUAAAAAAAA=",
              "header": {
                  "publicKeyHash": "/A7zg7KREnnRKldJv1mYJLPQmtjkjL+xSU59dRZ1Pfo=",
                  "ephemeralPublicKey": "MVkwEwYHKoZIzj0CAQYIKoZIzjDAQ..iC+NvODPA==",
                  "transactionId": "126d29c9d0b184..cfcc144c6fe2279683501b9"
              },
              "version": "EC_v1"
          },
          "paymentMethod": {
              "displayName": "MasterCard 7034",
              "network": "MasterCard",
              "type": "credit"
          },
          "transactionIdentifier": "806D29C221E8C3E..A2FF311ACFCC388C6FE2269683501B1"
  }

Important! Requests for SALE (by encrypted Apple Pay Token) should be made to /api/alternative

Purpose: Interface is used to process ApplePay transactions with previously generated ApplePay tokens without a need to decrypt them. Follow the instructions in ApplePay instructions section to set up ApplePay and generate a token to use in the request. Response on SALE request will be transmitted to Merchant callback URL.

  {
      "api_version": 1,
      "transaction_type": "SALE",
      "merchant_account": "Account_MP_TRX",
      "merchant_password": "password",
      "transaction_unique_id": "transaction_123",
      "payment_method": "ApplePay",
      "amount": 1,
      "currency": "USD",
      "first_name": "John",
      "last_name": "Doe",
      "country": "USA",
      "city": "New York",
      "address": "123 Street",
      "zip": "10005",
      "user_phone": "+12025550000",
      "user_email": "johndoe@test.com",
      "user_ip": "127.0.0.1",
      "encrypted_token": {
          "paymentData": {
              "data": "2/hHE78JrJjjra0l8BPrLcLbvMCl4mkilKrSA9a/PyI5uqfQwL94T/HSOsgaaluQoflsplXVEVxlafp3guQwI3NfClHaQmdjuzogaLwircj4DFe5gmaBgDO9oNwO5mA4ExneD06GZVxaAAfOEMZ1R27sr0WRdappVV5QR3vdkap2oBrlNsa93lKOldPcFGrr7AxAdUQ+JwDXVDQTBm7te8NUjrruN4zA+FnscjoCSvWEkPZXc3U+25dCuFY42OvtOEuwFfWLOMiTrkmZIEQMk4pZSqqjicDeobwCfGTQoxNqVThUdZNHlmCp/K5JavtVsewTwvpSVy0Cyq5+m5Kn8YOv0F7tx0MjxjDxWr8QMOYm1pTenos0otlchSYh+vzAW+s5uBTkbmMX1g==",
              "signature": "BIAGCSqGSIb3DQEHAqCAMIACAQExDzANBglghkgBZQMEAgEFADCABgkqhkiG9w0BBwEAAKCAMIID4zCCA4igAwIBAgIITDBBSVGdVDYwCgYIKoZIzj0EAwIwejEuMCwGA1UEAwwlQXBwbGUgQXBwbGljYXRpb24gSW50ZWdyYXRpb24gQ0EgLSBHMzEmMCQGA1UECwwdQXBwbGUgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMB4XDTE5MDUxODAxMzI1N1oXDTI0MDUxNjAxMzI1N1owXzElMCMGA1UEAwwcZWNjLXNtcC1icm9rZXItc2lnbl9VQzQtUFJPRDEUMBIGA1UECwwLaU9TIFN5c3RlbXMxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEwhV37evWx7Ihj2jdcJChIY3HsL1vLCg9hGCV2Ur0pUEbg0IO2BHzQH6DMx8cVMP36zIg1rrV1O/0komJPnwPE6OCAhEwggINMAwGA1UdEwEB/wQCMAAwHwYDVR0jBBgwFoAUI/JJxE+T5O8n5sT2KGw/orv9LkswRQYIKwYBBQUHAQEEOTA3MDUGCCsGAQUFBzABhilodHRwOi8vb2NzcC5hcHBsZS5jb20vb2NzcDA0LWFwcGxlYWljYTMwMjCCAR0GA1UdIASCARQwggEQMIIBDAYJKoZIhvdjZAUBMIH+MIHDBggrBgEFBQcCAjCBtgyBs1JlbGlhbmNlIG9uIHRoaXMgY2VydGlmaWNhdGUgYnkgYW55IHBhcnR5IGFzc3VtZXMgYWNjZXB0YW5jZSBvZiB0aGUgdGhlbiBhcHBsaWNhYmxlIHN0YW5kYXJkIHRlcm1zIGFuZCBjb25kaXRpb25zIG9mIHVzZSwgY2VydGlmaWNhdGUgcG9saWN5IGFuZCBjZXJ0aWZpY2F0aW9uIHByYWN0aWNlIHN0YXRlbWVudHMuMDYGCCsGAQUFBwIBFipodHRwOi8vd3d3LmFwcGxlLmNvbS9jZXJ0aWZpY2F0ZWF1dGhvcml0eS8wNAYDVR0fBC0wKzApoCegJYYjaHR0cDovL2NybC5hcHBsZS5jb20vYXBwbGVhaWNhMy5jcmwwHQYDVR0OBBYEFJRX22/VdIGGiYl2L35XhQfnm1gkMA4GA1UdDwEB/wQEAwIHgDAPBgkqhkiG92NkBh0EAgUAMAoGCCqGSM49BAMCA0kAMEYCIQC+CVcf5x4ec1tV5a+stMcv60RfMBhSIsclEAK2Hr1vVQIhANGLNQpd1t1usXRgNbEess6Hz6Pmr2y9g4CJDcgs3apjMIIC7jCCAnWgAwIBAgIISW0vvzqY2pcwCgYIKoZIzj0EAwIwZzEbMBkGA1UEAwwSQXBwbGUgUm9vdCBDQSAtIEczMSYwJAYDVQQLDB1BcHBsZSBDZXJ0aWZpY2F0aW9uIEF1dGhvcml0eTETMBEGA1UECgwKQXBwbGUgSW5jLjELMAkGA1UEBhMCVVMwHhcNMTQwNTA2MjM0NjMwWhcNMjkwNTA2MjM0NjMwWjB6MS4wLAYDVQQDDCVBcHBsZSBBcHBsaWNhdGlvbiBJbnRlZ3JhdGlvbiBDQSAtIEczMSYwJAYDVQQLDB1BcHBsZSBDZXJ0aWZpY2F0aW9uIEF1dGhvcml0eTETMBEGA1UECgwKQXBwbGUgSW5jLjELMAkGA1UEBhMCVVMwWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAATwFxGEGddkhdUaXiWBB3bogKLv3nuuTeCN/EuT4TNW1WZbNa4i0Jd2DSJOe7oI/XYXzojLdrtmcL7I6CmE/1RFo4H3MIH0MEYGCCsGAQUFBwEBBDowODA2BggrBgEFBQcwAYYqaHR0cDovL29jc3AuYXBwbGUuY29tL29jc3AwNC1hcHBsZXJvb3RjYWczMB0GA1UdDgQWBBQj8knET5Pk7yfmxPYobD+iu/0uSzAPBgNVHRMBAf8EBTADAQH/MB8GA1UdIwQYMBaAFLuw3qFYM4iapIqZ3r6966/ayySrMDcGA1UdHwQwMC4wLKAqoCiGJmh0dHA6Ly9jcmwuYXBwbGUuY29tL2FwcGxlcm9vdGNhZzMuY3JsMA4GA1UdDwEB/wQEAwIBBjAQBgoqhkiG92NkBgIOBAIFADAKBggqhkjOPQQDAgNnADBkAjA6z3KDURaZsYb7NcNWymK/9Bft2Q91TaKOvvGcgV5Ct4n4mPebWZ+Y1UENj53pwv4CMDIt1UQhsKMFd2xd8zg7kGf9F3wsIW2WT8ZyaYISb1T4en0bmcubCYkhYQaZDwmSHQAAMYIBjTCCAYkCAQEwgYYwejEuMCwGA1UEAwwlQXBwbGUgQXBwbGljYXRpb24gSW50ZWdyYXRpb24gQ0EgLSBHMzEmMCQGA1UECwwdQXBwbGUgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTAghMMEFJUZ1UNjANBglghkgBZQMEAgEFAKCBlTAYBgkqhkiG9w0BCQMxCwYJKoZIhvcNAQcBMBwGCSqGSIb3DQEJBTEPFw0yMjA3MTQwOTEwMzFaMCoGCSqGSIb3DQEJNDEdMBswDQYJYIZIAWUDBAIBBQChCgYIKoZIzj0EAwIwLwYJKoZIhvcNAQkEMSIEIPehyUhNMmgzfHCbtuhJUyCC92F8CkYyFsI6IaPDeefdMAoGCCqGSM49BAMCBEgwRgIhAJx3uTR0+KCni+qFbMTpA+WTrUoAQhuwDZjuJksBC3VnAiEAl3pK4TMINBPCLvYJeth7PeiwufnkWEsTfqFoIx5LyfUAAAAAAAA=",
              "header": {
                  "publicKeyHash": "/A7zg7KREnnRKldJv1mYJLPQmtjkjL+xSU59dRZ1Pfo=",
                  "ephemeralPublicKey": "MVkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEQTCp1BN+2WQSs40HrUT5iH2lkKrKk4PvKmORjfQ0jnkHzHjDCZp3GNuhTJSIp6sqlJWtzfawz7N7SiC+NvODPA==",
                  "transactionId": "126d29c9d0b18421e8c3e8d7fc78a9f19a2ff391acfcc144c6fe2279683501b9"
              },
              "version": "EC_v1"
          },
          "paymentMethod": {
              "displayName": "MasterCard 7034",
              "network": "MasterCard",
              "type": "credit"
          },
          "transactionIdentifier": "806D29C2D0B18421E8C3E8D7FC78A9F19A2FF311ACFCC388C6FE2269683501B1"
      }
  }

Request parameters:

PARAMETER NAME REQUIRED FORMAT and RULE DESCRIPTION
api_version yes int
Possible value: 1		 API version
merchant_account yes string (6-32) Merchant account
merchant_password yes string (6-32) Account password
transaction_unique_id yes string (1-45) Unique transaction Id
transaction_type yes string
Possible value: SALE		 Type of the transaction: SALE
amount yes float (0 - 9999999.9999) Amount of the transaction
currency yes string (3)
ISO 4217 (alfa-3)		 Currency of the transaction
payment_method yes string (2-32) Should be equal to ApplePay
encrypted_token yes array Array with the encrypted token data
paymentData yes array Array with the Token data provided by Apple
data yes string Encrypted payment data
signature yes string Signature of the payment and header data
header yes array Additional version-dependent information to verify the payment
publicKeyHash yes string Hash of the X.509 encoded public key bytes of the merchant’s certificate
ephemeralPublicKey yes string Ephemeral public key bytes
transactionId yes string Transaction identifier, generated on the device
end of the header array -//- -//- end of the header array
version yes string Version information about the payment token
end of the paymentData array -//- -//- End of the paymentData array
paymentMethod yes array Payment method array
displayName yes string Payment method name
network yes string Payment method network
type yes string Payment method type
end of the paymentMethod array -//- -//- End of the paymentMethod array
transactionIdentifier yes string Transaction Identifier
end of the encrypted_token array -//- -//- End of the encrypted_token array
first_name yes string (1-32) The first name of the customer
last_name yes string (1-32) The last name of the customer
address conditional string (2-64) Customer's address
city conditional string (2-32) Customer's city
state conditional string (1-32) Customer's state
zip conditional string (2-10) Customer's zip
country yes string (2-3)
ISO 3166-1 alpha-3		 Customer's country
user_phone conditional string (7-15) Customer's phone number. For testmode the value should be passed with + symbol
user_email yes string (6-255) Customer's email address
user_ip yes string (IPv4, IPv6) Customer's IP address. Not all acquirers support IPv6 format
merchant_user_id optional string (1-64) User Id on merchant's side
merchant_domain_name optional string (0-255) Merchant's domain name
merchant_affiliate_id optional string (0-255) Affiliate identifier
merchant_product_name optional string (0-255) Name of the product
descriptor_merchant optional string (0-255) Descriptor of the merchant
descriptor_phone optional string (0-255) Descriptor phone of the merchant
mid_reference optional string (16) Reference of the MID in Maxpay system
date_of_birth optional string (YYYY-MM-DD) Date of birth of the customer
cof_type optional enum ('CIT-initial', 'CIT-subsequent', 'MIT') The credentials on file(COF) is used to identify authorization requests that use stored credentials for a consumer, in order to improve authorization rates and reduce fraud. 'CIT-initial' - First transactions initiated by customer on your service (e.g. trial product, first subscription, one-time purchase etc.) 'CIT-subsequent' - Subsequent transactions initiated by customer (e.g. one-clicks, cross-sales). 'MIT' - Transactions initiated by merchant (e. g. rebill). 
  {
    "api_version": 1,
    "merchant_account": "Account_MP_TRX",
    "sessionid": "543e2136-d46c-4d7d-a3b3-075cf9adkl11",
    "transaction_unique_id": "transaction_123",
    "token": "5524fa52-75d8-4c7a-84ec-039d3097ab6f",
    "reference": "SLFF0000000039FDAEGG",
    "timestamp": 1628001612,
    "authcode": "",
    "status": "success",
    "code": 0,
    "message": "Transaction processed successfully"
  }

Response parameters:

PARAMETER NAME FORMAT and RULE DESCRIPTION
api_version int
Possible value: 1		 API version
merchant_account string (6-12) Merchant account
sessionid string (36) Id of the session
transaction_unique_id string (1-45) Unique transaction Id
token string (36) Hashed value of card number, expiry date and cardholder name
reference string (20) Reference of the transaction in Maxpay system
timestamp int (unix timestamp) Timestamp of the transaction
authcode string or null (0-24) Authorization code
status string
Possible values: success, decline, error		 Status of the transaction
code int (1-4) Response code regarding the transaction result
message string (6-255) Response message regarding the transaction result

SALE (by decrypted ApplePay token) transaction

Example of ApplePay token after decryption:

  {
    "applicationExpirationDate": "241231",
    "applicationPrimaryAccountNumber": "4111111111111111",
    "currencyCode": "840",
    "deviceManufacturerIdentifier": "060120050273",
    "paymentDataType": "3DSecure",
    "transactionAmount": 1,
    "paymentData": {
        "eciIndicator": null,
        "onlinePaymentCryptogram": "AFba6VV8uB3DAVYqIAtcAoABFA=="
    }
  }

Purpose: Interface is used to process ApplePay transactions with previously generated ApplePay tokens after decryption. Follow the instructions in ApplePay instructions section to set up ApplePay and generate a token to use in the request. Response on SALE request will be transmitted to Merchant callback URL.

Example of request:

  {
    "api_version": "1",
    "merchant_account": "Account_MP_TRX",
    "merchant_password": "password",
    "transaction_unique_id": "transaction_123",
    "transaction_type": "SALE",
    "amount": 0.99,
    "currency": "GBP",
    "first_name": "test",
    "last_name": "test",
    "address": "tst",
    "city": "test",
    "state": "st",
    "zip": "11111",
    "country": "GBR",
    "user_email": "test@test.test",
    "user_ip": "00.000.000.00",
    "user_phone": "00000000",
    "card_number": "4111111111111111",
    "card_holder": "test test",
    "card_exp_month": "12",
    "card_exp_year": "2023",
    "payment_method": "ApplePay",
    "custom_CAVV": "MMhopx..BFOA="
  }

Request parameters:

PARAMETER NAME REQUIRED FORMAT and RULE DESCRIPTION
api_version yes int
Possible value: 1		 API version
merchant_account yes string (6-32) Merchant account
merchant_password yes string (6-32) Account password
transaction_unique_id yes string (1-45) Unique transaction Id
transaction_type yes string
Possible value: SALE		 Type of the transaction: SALE
amount yes float (0 - 9999999.9999) Amount of the transaction
currency yes string (3)
ISO 4217 (alfa-3)		 Currency of the transaction
card_number yes string (13-19 digits)
Luhn algorithm		 applicationPrimaryAccountNumber value from decrypted ApplePay token
card_exp_month yes string (2 digits) first two digits of applicationExpirationDate value from decrypted ApplePay token
card_exp_year yes string (4 digits) thirds and fourths digits of applicationExpirationDate value from decrypted ApplePay token in YYYY format
card_holder yes string (2-32) Cardholder name
payment_method yes string (2-32) Should be equal to ApplePay
token conditional string (36) Hashed value of card number, expiry date and cardholder name. Required to use with CVV
first_name yes string (1-32) The first name of the customer
last_name yes string (1-32) The last name of the customer
address conditional string (2-64) Customer's address
city conditional string (2-32) Customer's city
state conditional string (1-32) Customer's state
zip conditional string (2-10) Customer's zip
country yes string (2-3)
ISO 3166-1 alpha-3		 Customer's country
user_phone conditional string (7-15) Customer's phone number. For test mode the value should be passed with + symbol
user_email yes string (6-255) Customer's email address
user_ip yes string (IPv4, IPv6) Customer's IP address. Not all acquirers support IPv6 format
merchant_user_id optional string (1-64) User Id on merchant's side
merchant_domain_name optional string (0-255) Merchant's domain name
merchant_affiliate_id optional string (0-255) Affiliate identifier
merchant_product_name optional string (0-255) Name of the product
descriptor_merchant optional string (0-255) Descriptor of the merchant
descriptor_phone optional string (0-255) Descriptor phone of the merchant
date_of_birth optional string (YYYY-MM-DD) Date of birth of the customer
cof_type optional enum ('CIT-initial', 'CIT-subsequent', 'MIT') The credentials on file(COF) is used to identify authorization requests that use stored credentials for a consumer, in order to improve authorization rates and reduce fraud. 'CIT-initial' - First transactions initiated by customer on your service (e.g. trial product, first subscription, one-time purchase etc.) 'CIT-subsequent' - Subsequent transactions initiated by customer (e.g. one-clicks, cross-sales). 'MIT' - Transactions initiated by merchant (e. g. rebill).
custom_CAVV yes string (28) onlinePaymentCryptogram value from decrypted ApplePay token 
  {
    "api_version": 1,
    "merchant_account": "Account_MP_TRX",
    "sessionid": "543e2136-d46c-4d7d-a3b3-075cf9adkl11",
    "transaction_unique_id": "transaction_123",
    "token": "5524fa52-75d8-4c7a-84ec-039d3097ab6f",
    "reference": "SLFF0000000039FDAEGG",
    "timestamp": 1628001612,
    "authcode": "",
    "status": "success",
    "code": 0,
    "message": "Transaction processed successfully"
  }

Response parameters:

PARAMETER NAME FORMAT and RULE DESCRIPTION
api_version int
Possible value: 1		 API version
merchant_account string (6-32) Merchant account
sessionid string (36) Id of the session
transaction_unique_id string (1-45) Unique transaction Id
token string (36) Hashed value of card number, expiry date and cardholder name
reference string (20) Reference of the transaction in Maxpay system
timestamp int (unix timestamp) Timestamp of the transaction
authcode string or null (0-24) Authorization code
status string
Possible values: success, decline, error		 Status of the transaction
code int (1-4) Response code regarding the transaction result
message string (6-255) Response message regarding the transaction result

REFUND transaction

Sample code of the REFUND request in "application/json" format:

    {
        "api_version": 1,
        "merchant_account": "Account_MP_TRX",
        "merchant_password": "password123",
        "transaction_unique_id": "refund_request",
        "transaction_type": "REFUND",
        "amount": 9.99,
        "currency": "EUR",
        "reference": "SLFF0000000039FDAEAW"
    }

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

Request parameters:

PARAMETER NAME REQUIRED FORMAT and RULE DESCRIPTION
api_version yes int
Possible value: 1		 API version
merchant_account yes string (6-32) Merchant account
merchant_password yes string (6-32) Account password
transaction_unique_id yes string (1-45) Unique transaction Id
transaction_type yes string
Possible value: REFUND		 Type of the transaction: REFUND
amount yes float (0 - 9999999.9999) Amount of the transaction
currency yes string (3)
ISO 4217 (alfa-3)		 Currency of the transaction
reference yes string (20) Reference of the base transation (SALE, SALE3D, SETTLE)
merchant_user_id optional string (1-64) User Id on merchant's side
descriptor_merchant optional string (0-255) Descriptor of the merchant
descriptor_phone optional string (0-255) Descriptor phone of the merchant

Sample code of the REFUND response in "application/json" format:

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

Response parameters:

PARAMETER NAME FORMAT and RULE DESCRIPTION
api_version int
Possible value: 1		 API version
merchant_account string (6-32) Merchant account
sessionid string (36) Id of the session
transaction_unique_id string (1-45) Unique transaction Id
token string (36) Hashed value of card number, expiry date and cardholder name
reference string (20) Reference of the transaction in Maxpay system
timestamp integer (unix timestamp) Timestamp of the transaction
authcode string or null (0-24) Authorization code
status string
Possible values: success, decline, error		 Status of the transaction
code integer (1-4) Response code regarding the transaction result
message string (6-255) Response message regarding the transaction result

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 the VOID request in "application/json" format:

    {
        "api_version": 1,
        "merchant_account": "Account_MP_TRX",
        "merchant_password": "password123",
        "transaction_unique_id": "void_request",
        "transaction_type": "VOID",
        "reference": "ATFF0000000039FDAEAQ"
    }

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

Request parameters:

PARAMETER NAME REQUIRED FORMAT and RULE DESCRIPTION
api_version yes int
Possible value: 1		 API version
merchant_account yes string (6-32) Merchant account
merchant_password yes string (6-32) Account password
transaction_unique_id yes string (1-45) Unique transaction Id
transaction_type yes string
Possible value: VOID		 Type of the transaction: VOID
reference yes string (20) Reference of the base transation (AUTH or AUTH3D)
merchant_user_id optional string (1-64) User Id on merchant's side
descriptor_merchant optional string (0-255) Descriptor of the merchant
descriptor_phone optional string (0-255) Descriptor phone of the merchant

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

Sample code of the VOID response in "application/json" format:

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

Response parameters:

PARAMETER NAME FORMAT and RULE DESCRIPTION
api_version int
Possible value: 1		 API version
merchant_account string (6-32) Merchant account
sessionid string (36) Id of the session
transaction_unique_id string (1-45) Unique transaction Id
token string (36) Hashed value of card number, expiry date and cardholder name
reference string (20) Reference of the transaction in Maxpay system
timestamp integer (unix timestamp) Timestamp of the transaction
authcode string or null (0-24) Authorization code
status string
Possible values: success, decline, error		 Status of the transaction
code integer (1-4) Response code regarding the transaction result
message string (6-255) Response message regarding the transaction result

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 the CHECK request with reference, "application/json" format:

    {
        "api_version": 1,
        "merchant_account": "Account_MP_TRX",
        "merchant_password": "password123",
        "transaction_type": "CHECK",
        "reference": "ATFF00000000395AD690"
    }

Sample code of the CHECK request with transaction id, "application/json" format:

    {
        "api_version": 1,
        "merchant_account": "Account_MP_TRX",
        "merchant_password": "password123",
        "transaction_type": "CHECK",
        "transaction_unique_id": "check_request"
    }

Purpose: Interface should be used to check transaction status.

Request parameters:

PARAMETER NAME REQUIRED FORMAT and RULE DESCRIPTION
api_version yes int
Possible value: 1		 API version
merchant_account yes string (6-32) Merchant account
merchant_password yes string (6-32) Account password
transaction_type yes string
Possible value: CHECK		 Type of the transaction: CHECK
transaction_unique_id conditional string (1-45) Unique transaction Id
reference conditional string (20) Reference of the transation to check

transaction_unique_id or reference can be passed for CHECK request.

Sample code of the CHECK response in "application/json" format:

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

Response parameters:

PARAMETER NAME FORMAT and RULE DESCRIPTION
api_version int
Possible value: 1		 API version
merchant_account string (6-32) Merchant account
sessionid string (36) Id of the session
transactions array Contains of transaction data array
reference string (20) Reference of the transaction in Maxpay system
transaction_unique_id string (1-45) Unique transaction Id
transaction_type string
Possible values: AUTH3D, AUTH, SALE3D, SALE, VOID, REFUND		 Type of the transaction
status string
Possible values: success, decline, error		 Status of the transaction
code integer (1-4) Response code regarding the transaction result
message string (6-255) Response message regarding the transaction result
token string (36) Hashed value of card number, expiry date and cardholder name
timestamp integer (unix timestamp) Timestamp of the transaction
authcode string or null (0-24) Authorization code
transactions end of the array ** -//- **
status string
Possible values: success, decline, error		 Status of the transaction
code integer (1-4) Response code regarding the transaction result
message string (6-255) Response message regarding the transaction result

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 of the TOKENIZE request in "application/json" format:

    {
        "api_version": 1,
        "merchant_account": "Account_MP_TRX",
        "merchant_password": "password123",
        "transaction_type": "TOKENIZE",
        "card_number": "4111111111111111",
        "card_exp_month": "09",
        "card_exp_year": "2023",
        "card_holder": "John Doe"
    }

Purpose: Interface is used to tokenize card number with randomly generated series of digits and symbols. Be advised: that not all acquirers support token (credit card data without cvv) as for initial payment.

Request parameters:

PARAMETER NAME REQUIRED FORMAT and RULE DESCRIPTION
api_version yes int
Possible value: 1		 API version
merchant_account yes string (6-32) Merchant account
merchant_password yes string (6-32) Account password
transaction_type yes string
Possible value: TOKENIZE		 Type of the transaction: TOKENIZE
card_number yes string (13-19 digits)
Luhn algorithm		 Number of the card
card_exp_month yes string (2 digits) Card expiration month. Month number from '01' to '12'
card_exp_year yes string (4 digits) Card expiration year
card_holder yes string (2-32) Cardholder name

Sample code of the TOKENIZE response in "application/json" format:

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

Response parameters:

PARAMETER NAME FORMAT and RULE DESCRIPTION
api_version int
Possible value: 1		 API version
merchant_account string (6-32) Merchant account
sessionid string (36) Id of the session
transaction_unique_id null or string (1-45) Unique transaction Id
token string (36) Hashed value of card number, expiry date and cardholder name
reference null or string (20) Reference of the transaction in Maxpay system
timestamp integer (unix timestamp) Timestamp of the transaction
authcode null or string (0-24) Authorization code
status string
Possible values: success, decline, error		 Status of the transaction
code integer (1-4) Response code regarding the transaction result
message string (6-255) Response message regarding the transaction result

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.

    {
        "api_version": 1,
        "merchant_account": "Account_MP_TRX",
        "sessionid": "de9c68-4268-5c348829-1682d33e1f5-53a1",
        "transactions": [
            {
                "reference": "SLFF000000000AQ22101",
                "transaction_unique_id": "sale_request",
                "transaction_type": "SALE",
                "status": "DECLINED",
                "mode": "CC",
                "code": 3100,
                "message": "General bank decline",
                "token": "5c34879c-d814-4285-8a26-1cc399b234441",
                "amount": 1,
                "currency": "USD",
                "timestamp": 1616946460,
                "authcode": ""
            },
            {
                "reference": "SLFF000000000AQ22109",
                "transaction_unique_id": "sale_request",
                "transaction_type": "SALE",
                "status": "SUCCESS",
                "mode": "CASCADE",
                "code": 0,
                "message": "SUCCESS",
                "token": "5c34879c-d814-4285-8a26-1cc393425550",
                "amount": 1,
                "currency": "USD",
                "timestamp": 1616946461,
                "authcode": ""
            }
        ],
        "status": "success",
        "code": 0,
        "message": "Transaction processed successfully"
    }

Be advised: if cascade mode has been activated on the merchant account you can receive an array of transactions - consisting of the primary transaction array and its second response which was sent to another MID, according to the cascade settings. In this case, the check must be carried out on the embedded array, in which mode = cascade. The cascade is an internal setting, for more information, please contact support team

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 request formats

Postman Test Collection

Please find our Postman Test Collection and configuration file which allows checking different transaction types quickly using the Host to Host API solution. The current collection has:

Payout Methods

Sample code of the payout methods request in "application/json" format:

    {
        "api_version": 1,
        "method": "list",
        "merchant_account": "Account_MP_TRX",
        "merchant_password": "password123"
    }

This API call allows to get all available payout methods.

Request parameters:

PARAMETER NAME REQUIRED FORMAT and RULE DESCRIPTION
api_version yes int (1)
Possible value: 1		 API version
merchant_account yes string (6-32) Merchant account
merchant_password yes string (6-32) Account password
method yes string
Possible value: list		 Method to get all payout methods

Sample code of the payout methods response in "application/json" format:

    {
       "sessionid": "de9c68-4268-5c348829-1682d33e1f5-53a1",
       "timestamp": 1521771183,
       "methods": [
            {
                "type": "card",
                "mid_name": "my_credit_card_mid",
                "mid_reference": "0001234567J",
                "bank_code": null,
                "currencies": ["USD"]
            },
            {
                "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:

PARAMETER NAME FORMAT and RULE DESCRIPTION
sessionid string (36) Unique session Id of the request
timestamp integer
unix timestamp		 Payout API response time
methods array Array which contains of type, mid_name, mid_reference, bank_code, currencies
methods[type] string (2-64) Type of the payout method
methods[mid_name] string (2-32) MID name in Maxpay system
methods[mid_reference] string (16) MID reference in Maxpay system
methods[bank_code] string (2-64) Bank code is used for routing. Always null for type=card.
methods[currencies] array Supported currencies
status string
Possible values: success, decline, error		 Response status
code integer (1-4) Response code of the request to Balance API
message string (6-255) Response message of the request to Balance API

Notice for init method In case of successful request merchant will receive status=pending and code=0 in response. In other cases, merchant can get decline or error status. Be advised that the final status of the payout request merchant will receive in callback data.

To check the full list of response codes and messages follow the link Response codes

Payout on credit card

Sample code of the Payout by Credit card request in application/json format:

    {
        "api_version": 1,
        "method": "init",
        "merchant_account": "Account_MP_TRX",
        "merchant_password": "password123",
        "transaction_unique_id": "payout_via_cc",
        "amount": 10,
        "currency": "USD",
        "callback_url": "https://merchant.com/callback",
        "user_id": "user123",
        "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:

PARAMETER NAME REQUIRED FORMAT and RULE DESCRIPTION
api_version yes int
Possible value: 1		 API version
merchant_account yes string (6-32) Merchant account
merchant_password yes string (6-32) Account password
method yes string
Possible value: init		 Method for the payout request
transaction_unique_id yes string (1-45) Transaction unique identifier in Merchant system.
mid_reference optional string (16) MID reference in Maxpay system
amount yes float (0 - 9999999.9999) Payout transaction amount
currency yes string (3)
ISO 4217 (alfa-3)		 Payout transaction currency
callback_url yes Not Empty String
https required		 Once the order has been processed merchant will receive a final response (callback) regarding the transaction status to this URL
user_id yes string (1-32) User Id on merchant's side
user_email yes string (6-255) Customer's email address
user_ip yes string (IPv4, IPv6) Customer's IP address. Not all acquirers support IPv6 format
user_first_name optional string (1-32) The first name of the customer
user_last_name optional string (1-32) The last name of the customer
user_address optional string (2-64) Customer's address
user_city optional string (2-32) Customer's city
user_state optional string (1-32) Customer's state
user_country yes string (2-3)
ISO 3166-1 alpha-3		 Customer's country
user_zip optional string (2-10) Customer's zip
user_phone optional string (7-15) Customer's phone number. For testmode the value should be passed with + symbol
card[card_number] yes string (13-19 digits)
Luhn algorithm		 Number of the card
card[card_exp_month] yes string (2 digits) Card expiration month. Month number from '01' to '12'
card[card_exp_year] yes string (4 digits) Card expiration year
card[card_cvv] optional string (3-4 digits) Card Verification Value
card[card_holder] yes string (2-32) Cardholder name
base_reference conditional string (20) Reference of the last successful 3D Secure transaction. For some acquirers it’s a required parameter.

Sample code of the Payout by Credit card response in application/json format:

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

Response parameters:

PARAMETER NAME FORMAT and RULE DESCRIPTION
session_id string (36) Unique session Id of the request
timestamp integer
unix timestamp		 Payout API response time
status string
Possible values: pending, decline, error		 Status of the request to Payout API
code integer (1-4) Response code of the request
message string (6-255) Response message of the request

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

Notice: Response is not a finished status of the transaction. Finished status will be sent in callback request.

Notice: Some of the optional parameters can be required for the acquirer side depending on the MCC code.

Payout via Token

Sample code of the Payout by Token request in application/json format:

    {
        "api_version": 1,
        "method": "init",
        "merchant_account": "Account_MP_TRX",
        "merchant_password": "password123",
        "transaction_unique_id": "payout_via_token",
        "amount": 10,
        "currency": "USD",
        "callback_url": "https://merchant.com/callback",
        "user_id": "user123",
        "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:

PARAMETER NAME REQUIRED FORMAT and RULE DESCRIPTION
api_version yes int
Possible value: 1		 API version
merchant_account yes string (6-32) Merchant account
merchant_password yes string (6-32) Account password
method yes string
Possible value: init		 Method for the payout request
transaction_unique_id yes string (1-45) Transaction unique identifier in Merchant system.
mid_reference optional string (16) MID reference in Maxpay system
amount yes float (0 - 9999999.9999) Payout transaction amount
currency yes string (3)
ISO 4217 (alfa-3)		 Payout transaction currency
callback_url yes Not Empty String
https required		 Once the order has been processed merchant will receive a final response (callback) regarding the transaction status to this URL
user_id yes string (1-32) User Id on merchant's side
user_email yes string (6-255) Customer's email address
user_ip yes string (IPv4, IPv6) Customer's IP address. Not all acquirers support IPv6 format
user_first_name optional string (1-32) The first name of the customer
user_last_name optional string (1-32) The last name of the customer
user_address optional string (2-64) Customer's address
user_city optional string (2-32) Customer's city
user_state optional string (1-32) Customer's state
user_country yes string (2-3)
ISO 3166-1 alpha-3		 Customer's country
user_zip optional string (2-10) Customer's zip
user_phone optional string (7-15) Customer's phone number. For testmode the value should be passed with + symbol
card[card_token] yes string (36) Hashed value of card number, expiry date and cardholder name
card[card_holder] yes string (2-32) Cardholder name
base_reference conditional string (20) Reference of the last successful 3D Secure transaction. For some acquirers it’s a required parameter.

Sample code of the Payout by Token response in application/json format:

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

Response parameters:

PARAMETER NAME FORMAT and RULE DESCRIPTION
session_id string (36) Unique session Id of the request
timestamp integer
unix timestamp		 Payout API response time
status string
Possible values: pending, decline, error		 Status of the request to Payout API
code integer (1-4) Response code of the request
message string (6-255) Response message of the request

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

Notice: Response is not a finished status of the transaction. Finished status will be sent in callback request.

Notice: Some of the optional parameters can be required for the acquirer side depending on the MCC code.

Payout via Paysafecard

Sample code of the Payout via Paysafecard request in application/json format:

    {
        "api_version": 1,
        "method": "init",
        "merchant_account": "Account_MP_TRX",
        "merchant_password": "password123",
        "transaction_unique_id": "payout_paysafecard",
        "mid_reference": "MD0000000D37A843",
        "amount": 10,
        "currency": "EUR",
        "callback_url": "https://merchant.com/callback",
        "user_ip": "127.0.0.1",
        "paysafecard": {
            "user_id": "user123",
            "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:

PARAMETER NAME REQUIRED FORMAT and RULE DESCRIPTION
api_version yes int
Possible value: 1		 API version
merchant_account yes string (6-32) Merchant account
merchant_password yes string (6-32) Account password
method yes string
Possible value: init		 Method for the payout request
transaction_unique_id yes string (1-45) Transaction unique identifier in Merchant system.
mid_reference conditional string (16) MID reference in Maxpay system
bank_code conditional string Bank code is used for routing
amount yes float (0 - 9999999.9999) Payout transaction amount
currency yes string (3)
ISO 4217 (alfa-3)		 Payout transaction currency
callback_url yes Not Empty String
https required		 Once the order has been processed merchant will receive a final response (callback) regarding the transaction status to this URL
user_ip yes string (IPv4, IPv6) Customer's IP address. Not all acquirers support IPv6 format
paysafecard[user_id] yes string (1-60) An unique Id of the user
paysafecard[user_email] yes string (6-255) Customer's email address
paysafecard[user_first_name] yes string (1-32) The first name of the customer
paysafecard[user_last_name] yes string (1-32) The last name of the customer
paysafecard[user_date_of_birth] yes string (YYYY-MM-DD) Date of birth of the customer

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

Sample code of the Payout via Paysafecard response in application/json format:

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

Response parameters:

PARAMETER NAME FORMAT and RULE DESCRIPTION
session_id string (36) Unique session Id of the request
timestamp integer
unix timestamp		 Payout API response time
status string
Possible values: pending, decline, error		 Status of the request to Payout API
code integer (1-4) Response code of the request
message string (6-255) Response message of the request

Notice: Response is not a finished status of the transaction. Finished status will be sent in callback request.

Payout via Skrill

Sample code of the Payout via Skrill request in application/json format:

    {
        "api_version": 1,
        "method": "init",
        "merchant_account": "Account_MP_TRX",
        "merchant_password": "password123",
        "transaction_unique_id": "payout_skrill",
        "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"
    }

Sample code of the Payout via Skrill by Token request in "application/json" format:

    {
        "api_version": 1,
        "method": "init",
        "merchant_account": "Account_MP_TRX",
        "merchant_password": "password123",
        "transaction_unique_id": "payout_skrill_by_token",
        "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:

PARAMETER NAME REQUIRED FORMAT and RULE DESCRIPTION
api_version yes int
Possible value: 1		 API version
merchant_account yes string (6-32) Account of the merchant. Given by MaxPay.
merchant_password yes string (6-32) Password of the merchant. Given by MaxPay.
method yes string
Possible value: init		 Method for the payout request
transaction_unique_id yes string (1-45) Transaction unique identifier in Merchant system
mid_reference conditional string (16) MID reference in Maxpay system
amount yes float (0 - 9999999.9999) Payout transaction amount
currency yes string (3)
ISO 4217 (alfa-3)		 Payout transaction currency
callback_url yes Not Empty String
https required		 Once the order has been processed merchant will receive a final response (callback) regarding the transaction status to this URL
type yes string
Possible value: skrill		 Type of the payout request
user_ip yes string (IPv4, IPv6) Customer's IP address. Not all acquirers support IPv6 format
user_id yes string (1-60) User Id on merchant's side
user_first_name optional string (1-32) The first name of the customer
user_last_name optional string (1-32) The last name of the customer
user_date_of_birth optional string (YYYY-MM-DD) Date of birth of the customer
user_email yes string (6-255) Customer's email address
wallet_id conditional string Skrill wallet id. Pass this value in order to make a payout to Skrill wallet. Pass only one of these fields
base_reference conditional string (20) Reference of base Sale transaction. Pass this value in order to make a payout to customer account where sale transaction was made (accepts all Skrill sale types except sale from Skrill wallet).
token conditional string (36) Value of the Token. Pass this value in order to repeat a previous payout or to make payout after Skrill Sale (accepts all Skrill sale types, including Skrill Wallet).

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

Sample code of the Payout via Skrill response in "application/json" format:

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

Response parameters:

PARAMETER NAME FORMAT and RULE DESCRIPTION
session_id string (36) Unique session Id of the request
timestamp integer
unix timestamp		 Payout API response time
status string
Possible values: pending, decline, error		 Status of the request to Payout API
code integer (1-4) Response code of the request
message string (6-255) Response message of the request

Notice: Response is not a finished status of the transaction. Finished status will be sent in callback request.

Payout via Neteller

Sample code of the Payout via Neteller request in "application/json" format:

    {
        "api_version": 1,
        "method": "init",
        "merchant_account": "Account_MP_TRX",
        "merchant_password": "password123",
        "transaction_unique_id": "payout_neteller",
        "mid_reference": "MD0000000D37A8C1",
        "amount": 29,
        "currency": "USD",
        "callback_url": "https://merchant.com/callback",
        "user_id": "user123",
        "user_ip": "127.0.0.1",
        "user_email": "john.doe@test.com",
        "type": "neteller"
    }

Parameters of the payout request via Neteller:

PARAMETER NAME REQUIRED FORMAT and RULE DESCRIPTION
api_version yes int
Possible value: 1		 API version
merchant_account yes string (6-32) Merchant account
merchant_password yes string (6-32) Account password
method yes string
Possible value: init		 Method for the payout request
transaction_unique_id yes string (1-45) Transaction unique identifier in Merchant system.
mid_reference conditional string (16) MID reference is used to pass a payout transaction to specific MID. If "user_email" specified, it should be passed exactly one of these fields. If "token" specified, it should be passed only "mid_reference" or passed nothing (previous MID by token will be used)
bank_code conditional string Bank code is used for routing
amount yes float (0 - 9999999.9999) Payout transaction amount
currency yes string (3)
ISO 4217 (alfa-3)		 Payout transaction currency
callback_url yes Not Empty String
https required		 Once the order has been processed merchant will receive a final response (callback) regarding the transaction status to this URL
user_email conditional string (6-255) Customer's email address
token conditional string (36) Value of the Token. Mandatory if "user_email" not specified. Don't pass "token" and "user_email" fields together.
user_ip yes string (IPv4, IPv6) Customer's IP address. Not all acquirers support IPv6 format
type yes string
Possible value: neteller		 Type of the payout request
user_id optional string (1-32) User Id on merchant's side
user_first_name optional string (1-32) The first name of the customer
user_last_name optional string (1-32) The last name of the customer
user_date_of_birth optional string (YYYY-MM-DD) Date of birth of the customer

Sample code of the Payout via Neteller by Token request in "application/json" format:

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

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

Sample code of the Payout via Neteller response in "application/json" format:

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

Response parameters:

PARAMETER NAME FORMAT and RULE DESCRIPTION
session_id string (36) Unique session Id of the request
timestamp integer
unix timestamp		 Payout API response time
status string
Possible values: pending, decline, error		 Status of the request to Payout API
code integer (1-4) Response code of the request
message string (6-255) Response message of the request

Notice: Response is not a finished status of the transaction. Finished status will be sent in callback request.

Payout via Ecopayz

Sample code of the Payout via Ecopayz request in "application/json" format:

"Content-type: JSON, POST" --data

    {
        "api_version": 1,
        "method": "init",
        "merchant_account": "Account_MP_TRX",
        "merchant_password": "password123",
        "transaction_unique_id": "payout_ecopayz",
        "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:

PARAMETER NAME REQUIRED FORMAT and RULE DESCRIPTION
api_version yes int
Possible value: 1		 API version
merchant_account yes string (6-32) Merchant account
merchant_password yes string (6-32) Account password
method yes string
Possible value: init		 Method for the payout request
transaction_unique_id yes string (1-45) Transaction unique identifier in Merchant system.
mid_reference conditional string (16) MID reference is used to pass a payout transaction to specific MID. If "wallet_id" specified, it should be passed exactly one of these fields. If "token" specified, it should be passed only "mid_reference" or passed nothing (previous MID by token will be used).
bank_code conditional string Bank code is used for routing
amount yes float (0 - 9999999.9999) Payout transaction amount
currency yes string (3)
ISO 4217 (alfa-3)		 Payout transaction currency
callback_url yes Not Empty String
https required		 Once the order has been processed merchant will receive a final response (callback) regarding the transaction status to this URL
user_email yes string (6-255) Customer's email address
token conditional string (36) Value of the Token. It's required if "user_email" not specified. Don't pass "token" and "user_email" fields together.
wallet_id conditional string ID of the customer's wallet
user_ip yes string (IPv4, IPv6) Customer's IP address. Not all acquirers support IPv6 format
type yes string
Possible value: ecopayz		 Type of the payout request
user_id yes string (1-60) User Id on merchant's side
user_first_name optional string (1-32) The first name of the customer
user_last_name optional string (1-32) The last name of the customer
user_date_of_birth optional string (YYYY-MM-DD) Date of birth of the customer

Sample code of the Payout via Ecopayz by Token request in "application/json" format:

    {
        "api_version": 1,
        "method": "init",
        "merchant_account": "Account_MP_TRX",
        "merchant_password": "password123",
        "transaction_unique_id": "payout_ecopayz_by_token",
        "mid_reference": "MD00000000000001",
        "amount": 29,
        "currency": "USD",
        "callback_url": "https://merchant.com/callback",
        "user_id": "user123",
        "user_ip": "127.0.0.1",
        "user_email": "john.doe@test.com",
        "token": "token_value",
        "type": "ecopayz"
    }

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

Sample code of the Payout via Ecopayz response in "application/json" format:

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

Response parameters:

PARAMETER NAME FORMAT and RULE DESCRIPTION
session_id string (36) Unique session Id of the request
timestamp integer
unix timestamp		 Payout API response time
status string
Possible values: pending, decline, error		 Status of the request to Payout API
code integer (1-4) Response code of the request
message string (6-255) Response message of the request

Notice: Response is not a finished status of the transaction. Finished status will be sent in callback request.

Payout via Ebanx

Sample code of the Payout via Ebanx request in "application/json" format:

    {
        "api_version": 1,
        "method": "init",
        "merchant_account": "Account_MP_TRX",
        "merchant_password": "password123",
        "transaction_unique_id": "payout_ebanx",
        "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:

PARAMETER NAME REQUIRED FORMAT and RULE DESCRIPTION
api_version yes int
Possible value: 1		 API version
merchant_account yes string (6-32) Merchant account
merchant_password yes string (6-32) Account password
method yes string
Possible value: init		 Method for the payout request
transaction_unique_id yes string (1-45) Transaction unique identifier in Merchant system.
mid_reference conditional string (16) MID reference is used to pass a payout transaction to specific MID. It should be passed exactly one of these fields.
bank_code conditional string Bank code is used for routing
amount yes float (0 - 9999999.9999) Payout transaction amount
currency yes string (3)
ISO 4217 (alfa-3)		 Payout transaction currency
callback_url yes Not Empty String
https required		 Once the order has been processed merchant will receive a final response (callback) regarding the transaction status to this URL
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 (1-32) The first name of the customer
user_last_name yes string (1-32) The last name of the customer
user_email yes string (6-255) Customer's email address
user_document yes string
Possible values: CPF, CNPJ, RUT, CC, CE, DNI		 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
Possible values: CPF, CNPJ, RUT, CC, CE, DNI		 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
Possible value: ebanx		 Type of the payout request
user_date_of_birth conditional string (YYYY-MM-DD) 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 yes string (1-60) User Id on merchant's side
user_ip yes string (IPv4, IPv6) Customer's IP address. Not all acquirers support IPv6 format
user_phone optional string (7-15) Customer's phone number. For testmode the value should be passed with + symbol

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

Sample code of the Payout via Ebanx response in "application/json" format:

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

Response parameters:

PARAMETER NAME FORMAT and RULE DESCRIPTION
session_id string (36) Unique session Id of the request
timestamp integer
unix timestamp		 Payout API response time
status string
Possible values: pending, decline, error		 Status of the request to Payout API
code integer (1-4) Response code of the request
message string (6-255) Response message of the request

Notice: Response is not a finished status of the transaction. Finished status will be sent in callback request.

Payout via Trustly

Sample code of the Payout via Trustly request in "application/json" format:

    {
        "api_version": 1,
        "method": "init",
        "merchant_account": "Account_MP_TRX",
        "merchant_password": "password123",
        "transaction_unique_id": "payout_trustly",
        "mid_reference": "MD00000000000003",
        "clearing_house": "SWEDEN",
        "bank_number": "5329",
        "account_number": "6000011",
        "amount": 1,
        "currency": "EUR",
        "callback_url": "https://merchant.com/callback.php",
        "user_id": "user123",
        "user_date_of_birth": "2017-01-01",
        "user_first_name": "fname",
        "user_last_name": "lname",
        "type": "TRUSTLY"
    }

Parameters of the payout request via Trustly:

PARAMETER NAME REQUIRED FORMAT and RULE DESCRIPTION
api_version yes int
Possible value: 1		 API version
merchant_account yes string (6-32) Merchant account
merchant_password yes string (6-32) Account password
method yes string
Possible value: init		 Method for the payout request
transaction_unique_id yes string (1-45) Transaction unique identifier in Merchant system.
mid_reference optional string (16) MID reference is used to pass a payout transaction to specific MID.
clearing_house yes string The clearing house of the end-user's bank account. Typically the name of a country in uppercase letters.
bank_number yes string The bank number identifying the end-user's bank in the given clearing house. For bank accounts in IBAN format you should just provide an empty string ("").
account_number yes string The account number, identifying the end-user's account in the bank. Can be either IBAN or country-specific format, see table* below.
amount yes float (0 - 9999999.9999) Payout transaction amount
currency yes string (3)
ISO 4217 (alfa-3)		 Payout transaction currency
callback_url yes Not Empty String
https required		 Once the order has been processed merchant will receive a final response (callback) regarding the transaction status to this URL
user_id yes string (1-60) User Id on merchant's side
user_first_name yes string (1-32) The first name of the customer
user_last_name yes string (1-32) The last name of the customer
user_date_of_birth yes string (YYYY-MM-DD) Date of birth of the customer
type yes string
Possible value: TRUSTLY		 Type of the payout request
user_email optional string (6-255) Customer's email address
user_ip yes string (IPv4, IPv6) Customer's IP address. Not all acquirers support IPv6 format
user_country yes string (2-3)
ISO 3166-1 alpha-3		 Customer's country
user_phone optional string (7-15) Customer's phone number. For testmode the value should be passed with + symbol

For other countries the AccountNumber and BankNumber should be provided in the local country-specific format. AccountNumbers that start with 2 letters are IBAN numbers, while the ones starting with numbers are country-specific.

ClearingHouse BankNumber [regex] AccountNumber [regex]
AUSTRIA ^AT[0-9]{18}$
BELGIUM ^BE[0-9]{14}$
BULGARIA ^BG[0-9]{2}[A-Z]{4}[0-9]{4}[0-9]{2}[A-Z0-9]{8}$
CROATIA ^HR[0-9]{2}[0-9]{7}[0-9]{10}$
CYPRUS ^CY[0-9]{10}[0-9A-Z]{16}$
CZECH_REPUBLIC ^[0-9]{4}$ ^[0-9]{16}$
DENMARK ^[0-9]{4}$ ^[0-9]{4,10}$
ESTONIA ^[0-9]{2}$ ^[0-9]{4,14}$
FINLAND ^FI[0-9]{16}$
FRANCE ^FR[0-9]{12}[0-9A-Z]{11}[0-9]{2}$
GERMANY ^DE[0-9]{20}$
GREECE ^GR[0-9]{25}$
HUNGARY ^[0-9]{8}$ ^[0-9]{24}$
IRELAND ^IE[0-9]{2}[A-Z]{4}[0-9]{14}$
ITALY ^IT[0-9]{2}[A-Z][0-9]{10}[0-9A-Z]{12}$
LATVIA ^LV[0-9]{2}[A-Z]{4}[0-9A-Z]{13}$
LITHUANIA ^LT[0-9]{18}$
LUXEMBOURG ^LU[0-9]{18}$
MALTA ^MT[0-9]{2}[A-Z]{4}[0-9]{5}[0-9A-Z]{18}$
NETHERLANDS ^NL[0-9]{2}[A-Z]{4}[0-9]{10}$
NORWAY ^[0-9]{4}$ ^[0-9]{7}$
POLAND ^PL[0-9]{26}$
PORTUGAL ^[0-9]{8}$ ^[0-9]{13}$
ROMANIA ^RO[0-9]{2}[A-Z]{4}[0-9A-Z]{16}$
SLOVAKIA ^SK[0-9]{22}$
SLOVENIA ^SI56[0-9]{15}$
SPAIN ^ES[0-9]{22}$
SWEDEN ^[0-9]{4,5}$ ^[0-9]{1,15}$
UNITED_KINGDOM ^[0-9]{6}$ ^[0-9]{8}$

Sample code of the Payout via Trustly response in "application/json" format:

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

Response parameters:

PARAMETER NAME FORMAT and RULE DESCRIPTION
session_id string (36) Unique session Id of the request
timestamp integer
unix timestamp		 Payout API response time
status string
Possible values: pending, decline, error		 Status of the request to Payout API
code integer (1-4) Response code of the request
message string (6-255) Response message of the request

Notice: Response is not a finished status of the transaction. Finished status will be sent in callback request.

Payout via SEPA

Sample code of the Payout via SEPA request in application/json format with mandatory parameters only:

    {
        "api_version": 1,
        "method": "init",
        "merchant_account": "Account_MP_TRX",
        "merchant_password": "password123",
        "transaction_unique_id": "payout_sepa",
        "mid_reference": "MD0000000D37A5F7",
        "amount": 100,
        "currency": "EUR",
        "callback_url": "https://merchant.com/callback",
        "receiver_iban":"1000000001200012",
        "type":"sepa",
        "receiver_bic":"BCXX12345",
        "receiver_name":"John Doe",
        "transfer_description":"Payment for request no. 123456"
    }

Sample code of the Payout via SEPA request in application/json format for receiver_type "PERSONAL":

    {
        "api_version": 1,
        "method": "init",
        "merchant_account": "Account_MP_TRX",
        "merchant_password": "password123",
        "transaction_unique_id": "payout_sepa",
        "mid_reference": "MD0000000D37A5F7",
        "amount": 100,
        "currency": "EUR",
        "callback_url": "https://merchant.com/callback",
        "receiver_iban":"1000000001200012",
        "type":"sepa",
        "receiver_type":"PERSONAL",
        "receiver_code":"AB12345",
        "receiver_bic":"BCXX12345",
        "receiver_name":"John Doe",
        "transfer_description":"Payment for request no. 123456"
    }

Sample code of the Payout via SEPA request in application/json format for receiver_type "LEGAL":

    {
        "api_version": 1,
        "method": "init",
        "merchant_account": "Account_MP_TRX",
        "merchant_password": "password123",
        "transaction_unique_id": "payout_sepa",
        "mid_reference": "MD0000000D37A5F7",
        "amount": 100,
        "currency": "EUR",
        "callback_url": "https://merchant.com/callback",
        "receiver_iban":"1000000001200012",
        "type":"sepa",
        "receiver_type":"LEGAL",
        "receiver_code":"AB12345",
        "receiver_bic":"BCXX12345",
        "receiver_name":"Company Ltd.",
        "transfer_description":"Payment for request no. 123456"
    }

Parameters of the payout request via SEPA:

PARAMETER NAME REQUIRED FORMAT and RULE DESCRIPTION
api_version yes int
Possible value: 1		 API version
merchant_account yes string (6-32) Merchant account
merchant_password yes string (6-32) Account password
method yes string
Possible value: init		 Method for the payout request
transaction_unique_id yes string (1-45) Transaction unique identifier in Merchant system.
amount yes float (0 - 9999999.9999) Payout transaction amount
currency yes string (3)
ISO 4217 (alfa-3)		 Payout transaction currency
callback_url yes Not Empty String
https required		 Once the order has been processed merchant will receive a final response (callback) regarding the transaction status to this URL
type yes string
Possible value: sepa		 Type of the payout method
bank_code conditional string Bank code is used for routing
mid_reference conditional string (16) MID reference
receiver_iban yes string max - 64 Receiver IBAN number
receiver_type conditional enum ('PERSONAL', 'LEGAL') Mandatory if parameter receiver_code is provided, otherwise parameter is optional
LEGAL if receiver is legal entity
PERSONAL if receiver is physical person
receiver_code optional string (1 - 20) Receiver personal code or receiver company code
receiver_name yes string (1 - 70) Receiver name. Can be as physical person name as legal entity name
receiver_bic yes string (max - 32) Receiver SEPA BIC number
transfer_description yes string (1 - 140) Payment purpose
transfer_priority optional enum ('HIGH', 'NORMAL')  Will be 'NORMAL' by default if the parameter is not provided
transfer_perform_date optional string (YYYY-MM-DD)  Payout execution date. Date when the booking on the bank-side should be executed
receiver_address optional string (2 - 64) Receiver address
receiver_city optional string (2 - 32) Receiver city
receiver_country optional string (3) Receivers country in ISO 3166-1 alpha-3 format
receiver_zip optional string (2 - 10) Receiver zip
receiver_email optional string (6 - 255) Receiver email address
receiver_ip optional string (IPv4, IPv6) Receiver IP address. Not all acquirers support IPv6 format
receiver_id optional string (1 - 60) Customer Id on merchant's side
receiver_phone optional string (7 - 15) Receiver phone number

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

Sample code of the Payout via SEPA response in application/json format:

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

Response parameters:

PARAMETER NAME FORMAT and RULE DESCRIPTION
session_id string (36) Unique session Id of the request
timestamp integer
unix timestamp		 Payout API response time
status string
Possible values: success, decline, error		 Status of the request to Payout API
code integer (1-4) Response code of the request
message string (6-255) Response message of the request

Notice: Response is not a finished status of the transaction. Finished status will be sent in callback request.

Payout cancellation

Example of payout cancellation request in "application/json" format:

    {
        "api_version": 1,
        "method": "cancel",
        "merchant_account": "Account_MP_TRX",
        "merchant_password": "password123",
        "transaction_unique_id": "payout_cancellation"
    }

Request parameters of payout cancellation:

PARAMETER NAME REQUIRED FORMAT and RULE DESCRIPTION
api_version yes int
Possible value: 1		 API version
merchant_account yes string (6-32) Merchant account
merchant_password yes string (6-32) Account password
method yes string
Possible value: cancel		 Method for the payout request cancellation
transaction_unique_id yes string (1-45) 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:

PARAMETER NAME FORMAT and RULE DESCRIPTION
session_id string (36) Unique session Id of the request
timestamp integer
unix timestamp		 Payout API response time
status string
Possible values: success, decline, error		 Status of the request to Payout API
code integer (1-4) Response code of the request
message string (6-255) Response message of the request

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:

PARAMETER NAME FORMAT and RULE DESCRIPTION
token string (36) Hashed value of card number, expiry date and cardholder name
reference string (20) Reference of the transaction in Maxpay system
transaction_unique_id string (1-45) Unique transaction Id
status string
Possible values: success, decline, error		 Status of the transaction
code integer (1-4) Response code regarding the transaction result
message string (6-255) Response message regarding the transaction result
checkSum string (64) Signature for callback parameters

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.

To check the full list of response codes and messages follow the link Response codes

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_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.

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

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

Transaction statuses

Payout transaction statuses:

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

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.

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

Request parameters are general for all request types

PARAMETER NAME REQUIRED FORMAT and RULE DESCRIPTION
api_version yes int (1)
Possible value: 1		 API version
merchant_account yes string (6-32) Merchant account
merchant_password yes string (6-32) Account password
time_from yes string (unix timestamp) Processing transaction time FROM
time_to yes string (unix timestamp) Processing transaction time TO, maximum time range till 31 days
qod_type yes string
Possible values: transactions, chargebacks, modifications, fraudalerts, vmpiAlerts, verifiRdr, ethocaAlertsHistory, mastercardAlertsHistory		 Transaction types are used for the request: transactions, chargebacks, modifications, fraudalerts, vmpiAlerts, verifiRdr, ethocaAlertsHistory, mastercardAlertsHistory
order no1 string
Possible values: acs, desc		 Ordering ASC (by default)/DESC
page no2 string (1-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 no3 string (1-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.

Sample code of the Transaction request in "application/json" format:

    {
        "api_version": 1,
        "merchant_account": "Account_MP_TRX",
        "merchant_password": "password123",
        "time_from": "1508001644",
        "time_to": "1808001645",
        "qod_type": "transactions",
        "order": "asc",
        "page": "1",
        "limit": "50"
    }

Postman Test Collection

Please find our Postman Test Collection and configuration file which allows checking different transaction types quickly using the Host to Host API solution. The current collection has:

QoD Response formats

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

Transactions

Sample code of the Transaction response in "application/json" format:

    {
        "api_version": 1,
        "timestamp": 1545117788.019275,
        "session_id": "de7a5f-67f1-5c18a05b-167c0326604-113b",
        "merchant_account": "Account_MP_TRX",
        "transactions": [
            {
                "transaction_type": "AUTH",
                "status": "SUCCESS",
                "mode": "CC",
                "reference": "ATFF00000000395376F6",
                "base_reference": null,
                "amount": 10,
                "currency": "GBP",
                "merchant": {
                    "merchant_account": "Account_MP_TRX",
                    "descriptor_merchant": "",
                    "descriptor_phone": "",
                    "merchant_domain_name": "",
                    "merchant_product_name": "",
                    "merchant_affiliate_id": "",
                    "merchant_user_id": ""
                },
                "user": {
                    "first_name": "John",
                    "last_name": "Doe",
                    "country": "GBR",
                    "state": "",
                    "city": "London",
                    "address": "123 Streetname",
                    "zip": "11111",
                    "user_ip": "127.0.0.1",
                    "user_email": "johndoe@test.com",
                    "user_phone": "+123456789012"
                },
                "card": {
                    "card_holder": "John Doe",
                    "brand": "VISA",
                    "bank": "TEST BANK",
                    "level": "CLASSIC",
                    "type": "DEBIT",
                    "brand": "VISA",
                    "bin": "400002",
                    "last": "1234",
                    "exp_month": "06",
                    "exp_year": "2023"
                },
                "bank": {
                    "id": 1,
                    "authcode": "111737",
                    "time": 1532542316.3496
                },
                "time": 1520447215.4163,
                "token": "54817d79-8b5c-4c6f-a266-7f2264ed02ad",
                "transaction_unique_id": "accept.1420447212.1505680771",
                "pares": "",
                "code": 0,
                "message": "SUCCESS"
            }
        ],
        "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 REQUIRED FORMAT and RULE DESCRIPTION
api_version yes int (1)
Possible value: 1		 API version
timestamp yes integer
unix timestamp		 Query on Demand API response time
session_id yes string (36) Unique session Id of the request
merchant_account yes string (6-32) Merchant account
transactions yes array Contains of transactions data
transaction_type yes string
Possible values: SALE, AUTH, AUTH3D, SALE3D, SETTLE, REFUND, VOID PAYOUT		 Type of the transaction
status yes string
Possible values: SUCCESS, DECLINED, ERROR, MALFORMED, FRAUDED, CHARGEDBACK, REFUNDED, VOIDED, PARTIAL-REFUNDED, WRONGREF		 Status of the transaction
mode yes string
Possible values: CC, TOKEN, REF, CASCADE, modification		 Transaction mode.
  • CC - by credit card.
  • TOKEN - by token.
  • REF - by reference.
  • CASCADE - by cascade mode.
reference yes string (20) Reference of the transaction in Maxpay system.
base_reference yes null or string (20) Base reference of the transaction in Maxpay system if exists.
amount yes float (0 - 9999999.9999) Transaction amount
currency yes string (3)
ISO 4217 (alfa-3)		 Transaction currency
change_reason_type no string
Possible value: verifiRefund		 It helps to analyze the reason of change status for a transaction after RDR modification
merchant yes array or null Contains of merchant data
merchant_account yes string (6-32) Merchant account
descriptor_merchant yes null or string (0-255) Merchant descriptor
descriptor_phone yes null or string (0-255) Merchant descriptor phone
merchant_domain_name yes null or string (0-255) Merchant website name
merchant_product_name yes null or string (0-255) Merchant product name
merchant_affiliate_id yes null or string (0-255) Merchant affiliate identifier
merchant_user_id yes null or string (0-32) Unique user Id in Merchant system
end of the merchant array -//- -//- End of the merchant array
user yes array or null Contains of user data
first_name yes string (1-32) The first name of the customer
last_name yes string (1-32) The last name of the customer
country yes string (2-3)
ISO 3166-1 alpha-3		 Customer's country
state yes null or string (1-32) Customer's state
city yes null or string (2-32) Customer's city
address yes null or string (2-64) Customer's address
zip yes null or string (2-10) Customer's zip
user_ip yes string (IPv4, IPv6) Customer's IP address
user_email yes string (6-255) Customer's email
user_phone yes null or string (7-15) Customer's phone number
end of the user array -//- -//- End of the user array
card yes array or null Contains of custmer's card data
card_holder yes string (2-32) Card holder name
brand yes string (0-255) Card brand - VISA, MASTERCARD, AMEX, JCB etc
bank yes string (0-255) Issuer bank
level yes string (0-255) Level of the card - ELECTRON, CLASSIC etc
type yes string (0-255) Type of the card - CREDIT, DEBIT etc
bin yes string (6) The first 6 digits of the card
last yes string (4) The last 4 digits of the card
exp_month yes string (2) Card expiration month
exp_year yes string (4) Card expiration year
end of the card array -//- -//- End of the card array
bank yes array or null Contains of acquirer data
id yes integer (0-20) Bank identifier code
authcode yes string (0-45) Bank authorization code
time yes float or null Bank transaction time
end of the bank array -//- -//- End of the bank array
time yes float or null Transaction time in Maxpay system, UTC timezone
token yes string (36) Hashed value of card number, expiry date and cardholder name.
transaction_unique_id yes string (1-45) Transaction unique identifier in Merchant system.
pares yes string (0-65535) The hashed value of the result of 3D Secure authorization
code yes null or integer(1-4) Transaction response code, check the response codes table below
message yes null or string (6-255) Transaction response message, check the response codes table below
end of transactions array -//- -//- End of the transactions array
status yes string
Possible values: success, error		 Status of the request to QoD API
code yes integer (1-4) Response code of the request to QoD API
message yes string (6-255) Response message of the request to QoD API

Chargebacks

Sample code of the Chargebacks response in "application/json" format:

    {
        "api_version": 1,
        "timestamp": 1545117788.019275,
        "session_id": "de7a5f-67f1-5c18a05b-167c0326604-113b",
        "merchant_account": "Account_MP_TRX",
        "chargebacks": [
            {
                "transaction": {
                    "transaction_type": "SETTLE",
                    "status": "CHARGEDBACK",
                    "mode": "REF",
                    "reference": "STFF0000000039546C12",
                    "base_reference": "ATFF0000000039546BBF",
                    "amount": 10,
                    "currency": "GBP",
                    "merchant": {
                        "merchant_account": "Account_MP_TRX",
                        "descriptor_merchant": "",
                        "descriptor_phone": "",
                        "merchant_domain_name": "",
                        "merchant_product_name": "",
                        "merchant_affiliate_id": "",
                        "merchant_user_id": ""
                    },
                    "user": {
                        "first_name": "John",
                        "last_name": "Doe",
                        "country": "GBR",
                        "state": "",
                        "city": "London",
                        "address": "123 Streetname",
                        "zip": "11111",
                        "user_ip": "127.0.0.1",
                        "user_email": "johndoe@test.com",
                        "user_phone": "+123456789012"
                    },
                    "card": {
                        "card_holder": "John Doe",
                        "brand": "VISA",
                        "bank": "TEST BANK",
                        "level": "CLASSIC",
                        "type": "DEBIT",
                        "brand": "VISA",
                        "bin": "400002",
                        "last": "1234",
                        "exp_month": "06",
                        "exp_year": "2023"
                    },
                    "bank": {
                        "id": 1,
                        "authcode": "111575",
                        "time": null
                    },
                    "time": 1621938805.751,
                    "token": "",
                    "transaction_unique_id": "transaction_52525251",
                    "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,
                    "currency": "GBP",
                    "transaction_unique_id": "transaction_52525251",
                    "arn": "",
                    "case_id": "",
                    "bank": {
                      "id": 1,
                      "authcode": "",
                      "time": 1628576548.6336,
                      "update_time": 1628576548.6336
                    },
                "time": 1728576550.499
                }
            }
        ],
        "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 REQUIRED FORMAT and RULE DESCRIPTION
api_version yes float (1)
Possible value: 1		 API version
timestamp yes integer
unix timestamp		 Query on Demand API response time
session_id yes string (36) Unique session Id of the request
merchant_account yes string (6-32) Merchant account
chargebacks yes array Contains of chargebacks data
transaction yes array Contains of transaction data
transaction_type yes string
Possible values: SALE, SALE3D, SETTLE		 Type of the transaction
status yes string
Possible value: CHARGEDBACK		 Status of the transaction
mode yes string
Possible values: CC, TOKEN, REF, CASCADE		 Transaction mode.
  • CC - by credit card.
  • TOKEN - by token.
  • REF - by reference.
  • CASCADE - by cascade mode.
reference yes string (20) Reference of the transaction in Maxpay system.
base_reference yes null or string (20) Base reference of the transaction in Maxpay system if exists.
amount yes float (0 - 9999999.9999) Transaction amount
currency yes string (3)
ISO 4217 (alfa-3)		 Transaction currency
merchant yes array or null Contains of merchant data
merchant_account yes string (6-32) Merchant account
descriptor_merchant yes null or string (0-255) Merchant descriptor
descriptor_phone yes null or string (0-255) Merchant descriptor phone
merchant_domain_name yes null or string (0-255) Merchant website name
merchant_product_name yes null or string (0-255) Merchant product name
merchant_affiliate_id yes null or string (0-255) Merchant affiliate identifier
merchant_user_id yes null or string (0-32) Unique user Id in Merchant system
end of the merchant array -//- -//- End of the merchant array
user yes array or null Contains of user data
first_name yes string (1-32) The first name of the customer
last_name yes string (1-32) The last name of the customer
country yes string (2-3)
ISO 3166-1 alpha-3		 Customer's country
state yes null or string (1-32) Customer's state
city yes null or string (2-32) Customer's city
address yes null or string (2-64) Customer's address
zip yes null or string (2-10) Customer's zip
user_ip yes string (IPv4, IPv6) Customer's IP address
user_email yes string (6-255) Customer's email
user_phone yes null or string (7-15) Customer's phone number
end of the user array -//- -//- End of the user array
card yes array or null Contains of custmer's card data
card_holder yes string (2-32) Card holder name
brand yes string (0-255) Card brand - VISA, MASTERCARD, AMEX, JCB etc
bank yes string (0-255) Issuer bank
level yes string (0-255) Level of the card - ELECTRON, CLASSIC etc
type yes string (0-255) Type of the card - CREDIT, DEBIT etc
bin yes string (6) The first 6 digits of the card
last yes string (4) The last 4 digits of the card
exp_month yes string (2) Card expiration month
exp_year yes string (4) Card expiration year
end of the card array -//- -//- End of the card array
bank yes array or null Contains of acquirer data
id yes integer (0-20) Bank identifier code
authcode yes string (0-45) Bank authorization code
time yes float or null Bank transaction time
end of the bank array -//- -//- End of the bank array
time yes float or null Transaction time in Maxpay system, UTC timezone
token yes string (36) Hashed value of card number, expiry date and cardholder name.
transaction_unique_id yes string (1-45) Transaction unique identifier in Merchant system.
pares yes string ( 0-65535) The hashed value of the result of 3D Secure authorization
code yes null or integer(1-4) Transaction response code, check the response codes table below
message yes null or string (6-255) Transaction response message, check the response codes table below
end of transaction array -//- -//- End of the transaction array
chargeback yes array Contains of chargeback data
status yes string Possible values: OPENED, REVERSED, CLOSED, REPRESENTED Chargeback status
type yes string Possible values: FIRST_CHARGEBACK, SECOND_THIRD_CHARGEBACK, CHARGEBACK_REVERSAL, LOST_REPRESENTMENT, REPRESENTMENT, RETRIEVAL_REQUEST Chargeback type
reason yes string (0-255) Chargeback reason
description yes string (0-255) Chargeback description
transaction_type yes string
Possible value: CHARGEBACK		 Chargeback transaction type
transaction_status yes string
Possible values: SUCCESS, ERROR		 Chargeback transaction status
mode yes string
Possible value: REF		 Chargeback transaction mode
reference yes string (20) Reference of the chargebacked transaction in Maxpay system
base_reference yes string (20) Base reference of the chargebacked transaction in Maxpay system
amount yes float (0 - 9999999.9999) Amount of the chargebacked transaction
currency yes string (3)
ISO 4217 (alfa-3)		 Currency of the chargebacked transaction
transaction_unique_id yes string (1-45) Unique chargebacked transaction identifier in Merchant system.
arn yes null or string (0-255) Actual Reference number
case_id yes null or string (0-255) Identifier from acquirer side.
bank yes array or null Contains of acquirer data
id yes integer (0- 20) Bank identifier code
authcode yes string (0-45) Bank authorization code
time yes float or null Chargeback time by bank
update_time yes float or null Transaction status updated time by bank
end of the bank array -//- -//- End of the bank array
time yes float or null Time of updating a transaction status at Maxpay system
end of the chargeback array -//- -//- End of the chargeback array
end of the chargebacks array -//- -//- End of the chargebacks array
status yes string
Possible values: success, error		 Status of the request to QoD API
code yes integer (1-4) Response code of the request to QoD API
message yes string (6-255) Response message of the request to QoD API

Modifications

Sample code of the Modification response in "application/json" format:

    {
      "api_version": 1,
      "timestamp": 1545117788.019275,
      "session_id": "de7a5f-67f1-5c18a05b-167c0326604-113b",
      "merchant_account": "Account_MP_TRX",
      "modifications": [
            {
                "transaction": {
                    "transaction_type": "AUTH",
                    "status": "SUCCESS",
                    "mode": "CASCADE",
                    "reference": "ATFF0000000039545997",
                    "base_reference": null,
                    "amount": 10,
                    "currency": "GBP",
                    "merchant": {
                        "merchant_account": "Account_MP_TRX",
                        "descriptor_merchant": "",
                        "descriptor_phone": "",
                        "merchant_domain_name": "",
                        "merchant_product_name": "",
                        "merchant_affiliate_id": "",
                        "merchant_user_id": ""
                    },
                    "user": {
                        "first_name": "John",
                        "last_name": "Doe",
                        "country": "GBR",
                        "state": "",
                        "city": "London",
                        "address": "123 Streetname",
                        "zip": "11111",
                        "user_ip": "127.0.0.1",
                        "user_email": "johndoe@test.com",
                        "user_phone": "+123456789012"
                    },
                    "card": {
                        "card_holder": "John Doe",
                        "brand": "VISA",
                        "bank": "TEST BANK",
                        "level": "CLASSIC",
                        "type": "DEBIT",
                        "brand": "VISA",
                        "bin": "400002",
                        "last": "1234",
                        "exp_month": "06",
                        "exp_year": "2023"
                    },
                    "bank": {
                        "id": 356,
                        "authcode": "authCode_1421931998.6174",
                        "time": 1532544175.6856
                    },
                    "time": 1521931997.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": 1632544175.6856
                    },
                    "time": 1622280865.0313,
                    "update_time": 1622280865.0313,
                    "code": 3100,
                    "message": "Decline"
                }
            }
        ],
        "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 REQUIRED FORMAT and RULE DESCRIPTION
api_version yes float (1)
Possible value: 1		 API version
timestamp yes integer
unix timestamp		 Query on Demand API response time
session_id yes string (36) Unique session Id of the request
merchant_account yes string (6-32) Merchant account
modifications yes array Contains of modifications data
transaction yes array Contains of transaction data
transaction_type yes string
Possible values: SALE, SALE3D, SETTLE, AUTH, AUTH3D		 Type of the transaction
status yes string
Possible values: SUCCESS, DECLINED, ERROR, REFUNDED, VOIDED, PARTIAL-REFUNDED		 Status of the transaction
mode yes string
Possible values: CC, TOKEN, REF, CASCADE		 Transaction mode.
  • CC - by credit card.
  • TOKEN - by token.
  • REF - by reference.
  • CASCADE - by cascade mode.
reference yes string (20) Reference of the transaction in Maxpay system.
base_reference yes null or string (20) Base reference of the transaction in Maxpay system if exists.
amount yes float (0 - 9999999.9999) Transaction amount
currency yes string (3)
ISO 4217 (alfa-3)		 Transaction currency
merchant yes array or null Contains of merchant data
merchant_account yes string (6-32) Merchant account
descriptor_merchant yes null or string (0-255) Merchant descriptor
descriptor_phone yes null or string (0-255) Merchant descriptor phone
merchant_domain_name yes null or string (0-255) Merchant website name
merchant_product_name yes null or string (0-255) Merchant product name
merchant_affiliate_id yes null or string (0-255) Merchant affiliate identifier
merchant_user_id yes null or string (0-32) Unique user Id in Merchant system
end of the merchant array -//- -//- End of the merchant array
user yes array or null Contains of user data
first_name yes string (1-32) The first name of the customer
last_name yes string (1-32) The last name of the customer
country yes string (2-3)
ISO 3166-1 alpha-3		 Customer's country
state yes null or string (1-32) Customer's state
city yes null or string (2-32) Customer's city
address yes null or string (2-64) Customer's address
zip yes null or string (2-10) Customer's zip
user_ip yes string (IPv4, IPv6) Customer's IP address
user_email yes string (6-255) Customer's email
user_phone yes null or string (7-15) Customer's phone number
end of the user array -//- -//- End of the user array
card yes array or null Contains of custmer's card data
card_holder yes string (2-32) Card holder name
brand yes string (0-255) Card brand - VISA, MASTERCARD, AMEX, JCB etc
bank yes string (0-255) Issuer bank
level yes string (0-255) Level of the card - ELECTRON, CLASSIC etc
type yes string (0-255) Type of the card - CREDIT, DEBIT etc
bin yes string (6) The first 6 digits of the card
last yes string (4) The last 4 digits of the card
exp_month yes string (2) Card expiration month
exp_year yes string (4) Card expiration year
end of the card array -//- -//- End of the card array
bank yes array or null Contains of acquirer data
id yes integer (0-20) Bank identifier code
authcode yes string (0-45) Bank authorization code
time yes float or null Bank transaction time
end of the bank array -//- -//- End of the bank array
time yes float or null Transaction time in Maxpay system, UTC timezone
token yes string (36) Hashed value of card number, expiry date and cardholder name.
transaction_unique_id yes string (1-45) Transaction unique identifier in Merchant system.
pares yes string ( 0-65535) The hashed value of the result of 3D Secure authorization
code yes null or integer (1-4) Transaction response code, check the response codes table below
message yes null or string (6-255) Transaction response message, check the response codes table below
end of transaction array -//- -//- End of the transaction array
modification yes array Contains of modification data
reason yes string (0-255) Modification reason
description yes string (0-255) Modification description
transaction_type yes string
Possible values: REFUND, VOID, SALE, SALE3D, SETTLE, AUTH, AUTH3D		 Modification transaction type
transaction_status yes string
Possible values: SUCCESS, ERROR, DECLINED, REFUNDED, VOIDED, PARTIAL-REFUNDED		 Modification transaction status
mode yes string
Possible value: MODIFICATION		 Mode of the modification
reference yes string (20) Reference of the modified transaction in Maxpay system
base_reference yes string (20) Base reference of the modified transaction in Maxpay system
amount yes float (0 - 9999999.9999) Amount of the modified transaction
currency yes string (3)
ISO 4217 (alfa-3)		 Currency of the modified transaction
bank yes array or null Contains of acquirer data
id yes integer (0-20) Bank identifier code
authcode yes string (0-45) Bank authorization code
time yes float or null Modification time by bank
end of the bank array -//- -//- End of the bank array
time yes float or null Modification time at Maxpay
update_time yes float or null Modification status updated at Maxpay
code yes null or integer(1-4) Modification response code, check the response codes table below
message yes null or string (6-255) Modification response message, check the response codes table below
end of the modification array -//- -//- End of the modification array
end of the modifications array -//- -//- End of the modifications array
status yes string
Possible values: success, error		 Status of the request to QoD API
code yes integer (1-4) Response code of the request to QoD API
message yes string (6-255) Response message of the request to QoD API

Fraud alerts

Sample code of the Fraudalerts response in "application/json" format:

    {
        "api_version": 1,
        "timestamp": 1545117788.019275,
        "session_id": "de7a5f-67f1-5c18a05b-167c0326604-113b",
        "merchant_account": "Account_MP_TRX",
        "fraudalerts": [
            {
                "fraud_alert": {
                    "transaction": {
                        "transaction_type": "SALE",
                        "status": "SUCCESS",
                        "mode": "CC",
                        "reference": "SLFF00000000395BB0C3",
                        "base_reference": null,
                        "amount": 10.0,
                        "currency": "GBP",
                        "merchant": {
                            "merchant_account": "Account_MP_TRX",
                            "descriptor_merchant": "",
                            "descriptor_phone": "",
                            "merchant_domain_name": "",
                            "merchant_product_name": "",
                            "merchant_affiliate_id": "",
                            "merchant_user_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": 1572785332.0,
                        "token": "57c6cf4e-86e0-449d-b790-66cec8812686",
                        "transaction_unique_id": "transaction_5353535351",
                        "pares": "",
                        "code": 0,
                        "message": "SUCCESS"
                    },
                    "source": "ethoca",
                    "alert_id": 123,
                    "alert_timestamp": 1586986433.0,
                    "receive_timestamp": 1586986433.6219,
                    "reason_code": "0",
                    "reason_description": "test",
                    "arn": null,
                    "bank_auth_code": "845697"
                }
            }
        ],
        "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 REQUIRED FORMAT and RULE DESCRIPTION
api_version yes int (1)
Possible value: 1		 API version
timestamp yes integer
unix timestamp		 Query on Demand API response time
session_id yes string (36) Unique session Id of the request
merchant_account yes string (6-32) Merchant account
fraudalerts yes array Contains of fraud alerts data
fraud_alert yes array Contains of fraud alert data
transaction yes array Contains of transaction data
transaction_type yes string
Possible values: SALE, SALE3D, SETTLE, AUTH		 Type of the transaction
status yes string
Possible values: SUCCESS, DECLINED, REFUNDED, VOIDED, PARTIAL-REFUNDED		 Status of the transaction
mode yes string
Possible values: CC, TOKEN, REF, CASCADE		 Transaction mode.
  • CC - by credit card.
  • TOKEN - by token.
  • REF - by reference.
  • CASCADE - by cascade mode.
reference yes string (20) Reference of the transaction in Maxpay system.
base_reference yes null or string (20) Base reference of the transaction in Maxpay system if exists.
amount yes float (0 - 9999999.9999) Transaction amount
currency yes string (3)
ISO 4217 (alfa-3)		 Transaction currency
merchant yes array or null Contains of merchant data
merchant_account yes string (6-32) Merchant account
descriptor_merchant yes null or string (0-255) Merchant descriptor
descriptor_phone yes null or string (0-255) Merchant descriptor phone
merchant_domain_name yes null or string (0-255) Merchant website name
merchant_product_name yes null or string (0-255) Merchant product name
merchant_affiliate_id yes null or string (0-255) Merchant affiliate identifier
merchant_user_id yes null or string (0-32) Unique user Id in Merchant system
end of the merchant array -//- -//- End of the merchant array
user yes array or null Contains of user data
first_name yes string (1-32) The first name of the customer
last_name yes string (1-32) The last name of the customer
country yes string (2-3)
ISO 3166-1 alpha-3		 Customer's country
state yes null or string (1-32) Customer's state
city yes null or string (2-32) Customer's city
address yes null or string (2-64) Customer's address
zip yes null or string (2-10) Customer's zip
user_ip yes string (IPv4, IPv6) Customer's IP address
user_email yes string (6-255) Customer's email
user_phone yes null or string (7-15) Customer's phone number
end of the user array -//- -//- End of the user array
card yes array or null Contains of custmer's card data
card_holder yes string (2-32) Card holder name
brand yes string (0-255) Card brand - VISA, MASTERCARD, AMEX, JCB etc
bank yes string (0-255) Issuer bank
level yes string (0-255) Level of the card - ELECTRON, CLASSIC etc
type yes string (0-255) Type of the card - CREDIT, DEBIT etc
bin yes string (6) The first 6 digits of the card
last yes string (4) The last 4 digits of the card
exp_month yes string (2) Card expiration month
exp_year yes string (4) Card expiration year
end of the card array -//- -//- End of the card array
bank yes array or null Contains of acquirer data
id yes integer (0-20) Bank identifier code
authcode yes string (0-45) Bank authorization code
time yes float or null Bank transaction time
end of the bank array -//- -//- End of the bank array
time yes float or null Transaction time in Maxpay system, UTC timezone
token yes string (36) Hashed value of card number, expiry date and cardholder name
transaction_unique_id yes string (1-45) Transaction unique identifier in Merchant system
pares yes string (0-65535) The hashed value of the result of 3D Secure authorization
code yes null or integer(1-4 digits) Transaction response code, check the response codes table below
message yes null or string (6-255) Transaction response message, check the response codes table below
end of transaction array -//- -//- End of the transaction array
source yes string (0-255) Fraud alert source
alert_id yes integer (0-255) Identifier of the alert from acquirer side.
alert_timestamp yes float or null Time of the fraud alert creation
receive_timestamp yes float or null Time of the fraud alert receiving from acquirer
reason_code yes string or null (0-255) Reason code of the fraud alert
reason_description yes string or null (0-255) Reason description of the fraud alert
arn yes null or string (0-255) Actual Reference number
bank_auth_code no string (6) Authorization code from original transaction referenced by the Case is provided if available
end of fraud_alert array -//- -//- End of the fraud alert array
end of fraudalerts array -//- -//- End of the fraud alerts array
status yes string
Possible values: success, error		 Status of the request to QoD API
code yes integer (1-4) Response code of the request to QoD API
message yes string (6-255) Response message of the request to QoD API

Historical Verify alerts

The code sample is provided below:

{
    "api_version": 1,
    "timestamp": 1633598519.210273,
    "session_id": "7e4695-b-615ebc36-17c5a0f3534-06de",
    "merchant_account": "Account_MP_TRX",
    "verifiRdr": [
        {
            "verifi_rdr": {
                "transaction": {
                    "transaction_type": "SALE3D",
                    "status": "SUCCESS",
                    "mode": "CC",
                    "reference": "S3FF00000000395F591B",
                    "base_reference": null,
                    "amount": 0.0,
                    "currency": "EUR",
                    "merchant": {
                        "merchant_account": "Account_MP_TRX",
                        "descriptor_merchant": "",
                        "descriptor_phone": "",
                        "merchant_domain_name": "",
                        "merchant_product_name": "demo-product",
                        "merchant_affiliate_id": "",
                        "merchant_user_id": ""
                    },
                    "user": {
                        "first_name": "John",
                        "last_name": "Doe",
                        "country": "USA",
                        "state": "",
                        "city": "New York",
                        "address": "123 Avn",
                        "zip": "12100",
                        "user_ip": "127.0.0.1",
                        "user_email": "johndoe@test.com",
                        "user_phone": "+380505555555"
                    },
                    "card": {
                        "card_holder": "John Doe",
                        "brand": "VISA",
                        "bank": "Bank",
                        "level": "GOLD",
                        "type": "CREDIT",
                        "bin": "411111",
                        "last": "1111",
                        "exp_month": "02",
                        "exp_year": "2024"
                    },
                    "bank": {
                        "id": 426,
                        "authcode": null,
                        "time": 1625680855.4195
                    },
                    "time": 1625680811.0,
                    "token": "60ddb94e-4d90-42a4-87bb-0001154a42a3",
                    "transaction_unique_id": "0426e720-8a4d-4965-85af-e21ca94904ad",
                    "pares": "",
                    "code": 0,
                    "message": "SUCCESS"
                },
                "source": "Verifi",
                "alert_id": 40,
                "alert_timestamp": 1598527050.0,
                "receive_timestamp": 1603106250.1754,
                "reason_code": "6",
                "reason_description": "Fraudulent Use of Account Number",
                "arn": "74171690206000197725748",
                "bank_auth_code": "845686"
            }
        }
    ],
    "status": "success",
    "code": 0,
    "message": "Transaction processed successfully"
}

Purpose: verifiRdr request qod_type allows to get all historical Verify alerts on the merchant account

Response parameters:

PARAMETER NAME REQUIRED FORMAT and RULE DESCRIPTION
api_version yes float (1)
Possible value: 1		 API version
timestamp yes integer
unix timestamp		 Query on Demand API response time
session_id yes string (36) Unique session Id of the request
merchant_account yes string (6-32) Merchant account
verifiRdr yes array Contains of historical Verify alerts data
verifi_rdr yes array Contains of historical verifi_rdr alert data
transaction yes array Contains of transaction data
transaction_type yes string
Possible values: SALE, SALE3D, SETTLE, AUTH , REFUND		 Type of the transaction
status yes string
Possible values: SUCCESS, DECLINED, REFUNDED, VOIDED, PARTIAL-REFUNDED		 Status of the transaction
mode yes string
Possible values: CC, TOKEN, REF, CASCADE		 Transaction mode.
  • CC - by credit card.
  • TOKEN - by token.
  • REF - by reference.
  • CASCADE - by cascade mode.
reference yes string (20) Reference of the transaction in Maxpay system.
base_reference yes null or string (20) Base reference of the transaction in Maxpay system if exists.
amount yes float (0 - 9999999.9999) Transaction amount
currency yes string (3)
ISO 4217 (alfa-3)		 Transaction currency
merchant yes array or null Contains of merchant data
merchant_account yes string (6-32) Merchant account
descriptor_merchant yes null or string (0-255) Merchant descriptor
descriptor_phone yes null or string (0-255) Merchant descriptor phone
merchant_domain_name yes null or string (0-255) Merchant website name
merchant_product_name yes null or string (0-255) Merchant product name
merchant_affiliate_id yes null or string (0-255) Merchant affiliate identifier
merchant_user_id yes null or string (0-32) Unique user Id in Merchant system
end of the merchant array -//- -//- End of the merchant array
user yes array or null Contains of user data
first_name yes string (1-32) The first name of the customer
last_name yes string (1-32) The last name of the customer
country yes string (2-3)
ISO 3166-1 alpha-3		 Customer's country
state yes null or string (1-32) Customer's state
city yes null or string (2-32) Customer's city
address yes null or string (2-64) Customer's address
zip yes null or string (2-10) Customer's zip
user_ip yes string (IPv4, IPv6) Customer's IP address
user_email yes string (6-255) Customer's email
user_phone yes null or string (7-15) Customer's phone number
end of the user array -//- -//- End of the user array
card yes array or null Contains of custmer's card data
card_holder yes string (2-32) Card holder name
brand yes string (0-255) Card brand - VISA, MASTERCARD, AMEX, JCB etc
bank yes string (0-255) Issuer bank
level yes string (0-255) Level of the card - ELECTRON, CLASSIC etc
type yes string (0-255) Type of the card - CREDIT, DEBIT etc
bin yes string (6) The first 6 digits of the card
last yes string (4) The last 4 digits of the card
exp_month yes string (2) Card expiration month
exp_year yes string (4) Card expiration year
end of the card array -//- -//- End of the card array
bank yes array or null Contains of acquirer data
id yes integer (0-20) Bank identifier code
authcode yes string (0-45) Bank authorization code
time yes float or null Bank transaction time
end of the bank array -//- -//- End of the bank array
time yes float or null Transaction time in Maxpay system, UTC timezone
token yes string (36) Hashed value of card number, expiry date and cardholder name
transaction_unique_id yes string (1-45) Transaction unique identifier in Merchant system
pares yes string (0-65535) The hashed value of the result of 3D Secure authorization
code yes null or integer Transaction response code, check the response codes table below
message yes null or string (6-255) Transaction response message, check the response codes table below
end of transaction array -//- -//- End of the transaction array
source yes string
Possible value: Verifi		 The source of the alert
alert_id yes int The alert ID
alert_timestamp yes float or null The time when alert was created on 3rd side
receive_timestamp yes float or null The time when alert was received
reason_code yes string The reason code
reason_description yes string The reason description
arn yes string Acquire reference number
bank_auth_code no string (6) Authorization code from original transaction referenced by the Case is provided if available
end of the verifi_rdr -//- -//- end of the verifi_rdr array
end of the verifiRdr -//- -//- end of the verifiRdr array
status yes string
Possible values: success, error		 Status of the request to QoD API
code yes integer (1-4) Response code of the request to QoD API
message yes string (6-255) Response message of the request to QoD API

Ethoca alerts

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

Sample code of the request for receiving Ethoca fraud alerts in "application/json" format:

    {
        "api_version": 1,
        "merchant_account": "Account_MP_TRX",
        "merchant_password": "password123",
        "qod_type": "ethocaFraudAlerts",
        "order": "asc",
        "page": "1",
        "limit": "1"
    }

Request parameters

PARAMETER NAME REQUIRED FORMAT and RULE DESCRIPTION
api_version yes int (1)
Possible value: 1		 API version
merchant_account yes string (6-32) Merchant account
merchant_password yes string (6-32) Account password
qod_type yes string
Possible value: ethocaFraudAlerts, mastercardFraudAlerts		 QoD types: ethocaFraudAlerts, mastercardFraudAlerts
order no1 string
Possible values: acs , desc		 Ordering ASC (by default)/DESC
page no2 string
Possible values: 1-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 no3 string
Possible values: 1-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.

Sample code of the response for receiving Ethoca fraud alerts in "application/json" format:

    {
       "api_version": 1,
       "timestamp": 1545117788.019275,
       "session_id": "de7a5f-67f1-5c18a05b-167c0326604-113b",
       "merchant_account": "Account_MP_TRX",
       "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": "",
             "bankAuthCode": "null"
          },
                {
             "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",
             "bankAuthCode": "null"
          }
       ],
       "status": "success",
       "code": 0
    }

Response parameters:

PARAMETER NAME REQUIRED FORMAT and RULE DESCRIPTION
api_version yes int (1)
Possible value: 1		 API version
timestamp yes integer
unix timestamp		 Query on Demand API response time
session_id yes string (36) Unique session Id of the request
merchant_account yes string (6-32) Merchant account
message yes null or string (6-255) Description message
ethocaFraudAlerts yes array or null Contains of Ethoca fraud alerts data
id yes integer (0- 255) Fraud alert identifier
source yes string (0-255) Source of the alert
externalId yes integer (0- 255) External fraud alert identifier
type yes string (0- 255) Fraud alert type
state yes string (0- 255) Current fraud alert state
cardBin yes string (6) The first 6 digits of the card
cardLast4 yes string (4) The last 4 digits of the card
alertTimestamp yes integer
unix timestamp		 Alert time
transactionTimestampp yes integer
unix timestamp		 Original transaction time
transactionAmount yes float (0 - 9999999.9999) Original transaction amount
transactionCurrency yes string (3)
ISO 4217 (alfa-3)		 Original transaction currency
is3dSecure yes boolean or null Possible values: true, false, null Was the transaction processed via 3D Secure flow or not (true, false, null for unknown).
arn yes null or string (0-255) Actual Reference number
chargebackAmount yes float or null (0 - 9999999.9999) Amount of the chargebacked transaction
chargebackCurrency yes string or null (3)
ISO 4217(alfa-3)		 Currency of the chargebacked transaction
chargebackReasonCode yes integer or null Chargeback reason code
merchantDescriptor yes null or string (0-255) Merchant descriptor
ethocaId yes string (0- 255) Ethoca identifier
bankAuthCode yes string or null Authorization code of issuer bank
end of ethocaFraudAlerts array -//- -//- End of the ethocaFraudAlerts array
status yes string
Possible values: success, error		 Status of the request to QoD API
code yes integer (1-4) Response code of the request to QoD API

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

    {
      "api_version": 1,
      "merchant_account": "Account_MP_TRX",
      "merchant_password": "password123",
      "qod_type": "ethocaFraudAlertConfirm",
      "alertId": "15"
    }

Request parameters for alert confirmation

PARAMETER NAME FORMAT and RULE DESCRIPTION
api_version int (1)
Possible value: 1		 API version
merchant_account string (6-32) Merchant account
merchant_password string (6-32) Account password
qod_type string
Possible value: ethocaFraudAlertConfirm, mastercardFraudAlertConfirm		 QOD types: ethocaFraudAlertConfirm, mastercardFraudAlertConfirm
alertId string ID of the alert, received from the list

Example of the confirmation response in "application/json" format:

    {
      "api_version": 1,
      "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 FORMAT and RULE DESCRIPTION
api_version int (1)
Possible value: 1		 API version
timestamp integer
unix timestamp		 Query on Demand API response time
session_id string (36) Unique session Id of the request
message null or string (6-255) Response message
status string
Possible values: success, error		 Response status
code integer (1-4) Response code of the request to QoD API

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

Sample code request of Bulk alert confirmation in "application/json" format:

    {
      "api_version": 1,
      "merchant_account": "Account_MP_TRX",
      "merchant_password": "password123",
      "qod_type": "ethocaBulkFraudAlertConfirm",
      "alertIds": [15]
    }

Request parameters for Bulk alert confirmation

PARAMETER NAME FORMAT and RULE DESCRIPTION
api_version int (1)
Possible value: 1		 API version
merchant_account string (6-32) Merchant account
merchant_password string (6-32) Account password
qod_type string
Possible value: ethocaBulkFraudAlertConfirm, mastercardBulkFraudAlertConfirm		 QOD types: ethocaBulkFraudAlertConfirm, mastercardBulkFraudAlertConfirm
alertIds array IDs of the Alerts

Sample code response of Bulk alert confirmation in "application/json" format:

    {
      "api_version": 1,
      "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 FORMAT and RULE DESCRIPTION
api_version int (1)
Possible value: 1		 API version
timestamp integer
unix timestamp		 Query on Demand API response time
session_id string (36) Unique session Id of the request
message null or string (6-255) Response message
status string
Possible values: success, error		 Response status
code integer (1-4) Response code of the request to QoD API

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

Sample code of the request for alert feedback in "application/json" format:

    {
      "api_version": 1,
      "merchant_account": "Account_MP_TRX",
      "merchant_password": "password123",
      "qod_type": "ethocaFraudAlertFeedback",
      "alertId": "15",
      "state": "none",
      "refunded": "not_refunded"
    }

Request parameters for alert feedback

PARAMETER NAME REQUIRED FORMAT and RULE DESCRIPTION
api_version yes int (1)
Possible value: 1		 API versionAPI version
merchant_account yes string (6-32) Merchant account
merchant_password yes string (6-32) Account password
qod_type yes string
Possible value: ethocaFraudAlertFeedback, mastercardFraudAlertFeedback		 QOD types: ethocaFraudAlertFeedback, mastercardFraudAlertFeedback
alertId yes string ID of the alert, received from the list
state yes string New alert state
refunded yes string
Possible values: none, refunded, not_refunded, not_settled		 Whether transaction was refunded: none, refunded, not_refunded, not_settled
reference no string (20) 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

Sample code of the response for alert feedback in "application/json" format:

    {
      "api_version": 1,
      "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 FORMAT and RULE DESCRIPTION
api_version int (1)
Possible value: 1		 API version
timestamp integer
unix timestamp		 Query on Demand API response time
session_id string (36) Unique session Id of the request
message null or string (6-255) Response message
status string
Possible values: success, error		 Response status
code integer (1-4) Response code of the request to QoD API

Historical Ethoca alerts

The code sample is provided below:

{
    "api_version": 1,
    "timestamp": 1633598526.537609,
    "session_id": "7e4695-c-615ebc3e-17c5a0f524f-2071",
    "merchant_account": "Account_MP_TRX",
    "ethocaAlertsHistory": [
        {
            "ethoca_alerts_history": {
                "transaction": {
                    "transaction_type": "SALE3D",
                    "status": "SUCCESS",
                    "mode": "CC",
                    "reference": "S3FF00000000395F58C8",
                    "base_reference": null,
                    "amount": 0.0,
                    "currency": "EUR",
                    "merchant": {
                        "merchant_account": "Account_MP_TRX",
                        "descriptor_merchant": "",
                        "descriptor_phone": "",
                        "merchant_domain_name": "",
                        "merchant_product_name": "demo-product",
                        "merchant_affiliate_id": "",
                        "merchant_user_id": ""
                    },
                    "user": {
                        "first_name": "John",
                        "last_name": "Doe",
                        "country": "USA",
                        "state": "",
                        "city": "New York",
                        "address": "123 Avn",
                        "zip": "12100",
                        "user_ip": "127.0.0.1",
                        "user_email": "johndoe@test.com",
                        "user_phone": "+380505555555"
                    },
                    "card": {
                        "card_holder": "John Doe",
                        "brand": "VISA",
                        "bank": "Bank",
                        "level": "GOLD",
                        "type": "CREDIT",
                        "bin": "411111",
                        "last": "1111",
                        "exp_month": "02",
                        "exp_year": "2024"
                    },
                    "bank": {
                        "id": 426,
                        "authcode": null,
                        "time": 1625680464.2448
                    },
                    "time": 1625680430.0,
                    "token": "60ddb94e-4d90-42a4-87bb-0001154a42a3",
                    "transaction_unique_id": "6db7bfee-eb25-44d5-9ae2-8276cf5feb63",
                    "pares": "",
                    "code": 0,
                    "message": "SUCCESS",
                    "custom_fields": {
                        "custom_descriptor_merchant": "",
                        "custom_mid_id": "7",
                        "custom_mid_name": "BamboraTest",
                        "custom_mid_reference": "MD0000000D379FE5"
                    }
                },
                "source": "covery",
                "alert_id": 41,
                "alert_timestamp": 1598527050.0,
                "receive_timestamp": 1603106250.2218,
                "reason_code": "6",
                "reason_description": "Fraudulent Use of Account Number",
                "arn": "74171690162000163368277",
                "bank_auth_code": "745617"
            }
        }
    ],
    "status": "success",
    "code": 0,
    "message": "Transaction processed successfully"
}

Purpose: ethocaAlertsHistory request qod_type allows to get all historical Ethoca alerts on the merchant account

Response parameters:

PARAMETER NAME REQUIRED FORMAT and RULE DESCRIPTION
api_version yes float (1)
Possible value: 1		 API version
timestamp yes integer
unix timestamp		 Query on Demand API response time
session_id yes string (36) Unique session Id of the request
merchant_account yes string (6-32) Merchant account
ethocaAlertsHistory yes array Contains of historical Ethoca alerts data
ethoca_alerts_history yes array Contains of historical Ethoca alert data
transaction yes array Contains of transaction data
transaction_type yes string
Possible values: SALE, SALE3D, SETTLE, AUTH , REFUND		 Type of the transaction
status yes string
Possible values: SUCCESS, DECLINED, REFUNDED, VOIDED, PARTIAL-REFUNDED		 Status of the transaction
mode yes string
Possible values: CC, TOKEN, REF, CASCADE		 Transaction mode.
  • CC - by credit card.
  • TOKEN - by token.
  • REF - by reference.
  • CASCADE - by cascade mode.
reference yes string (20) Reference of the transaction in Maxpay system.
base_reference yes null or string (20) Base reference of the transaction in Maxpay system if exists.
amount yes float (0 - 9999999.9999) Transaction amount
currency yes string (3)
ISO 4217 (alfa-3)		 Transaction currency
merchant yes array or null Contains of merchant data
merchant_account yes string (6-32) Merchant account
descriptor_merchant yes null or string (0-255) Merchant descriptor
descriptor_phone yes null or string (0-255) Merchant descriptor phone
merchant_domain_name yes null or string (0-255) Merchant website name
merchant_product_name yes null or string (0-255) Merchant product name
merchant_affiliate_id yes null or string (0-255) Merchant affiliate identifier
merchant_user_id yes null or string (0-32) Unique user Id in Merchant system
end of the merchant array -//- -//- End of the merchant array
user yes array or null Contains of user data
first_name yes string (1-32) The first name of the customer
last_name yes string (1-32) The last name of the customer
country yes string (2-3)
ISO 3166-1 alpha-3		 Customer's country
state yes null or string (1-32) Customer's state
city yes null or string (2-32) Customer's city
address yes null or string (2-64) Customer's address
zip yes null or string (2-10) Customer's zip
user_ip yes string (IPv4, IPv6) Customer's IP address
user_email yes string (6-255) Customer's email
user_phone yes null or string (7-15) Customer's phone number
end of the user array -//- -//- End of the user array
card yes array or null Contains of custmer's card data
card_holder yes string (2-32) Card holder name
brand yes string (0-255) Card brand - VISA, MASTERCARD, AMEX, JCB etc
bank yes string (0-255) Issuer bank
level yes string (0-255) Level of the card - ELECTRON, CLASSIC etc
type yes string (0-255) Type of the card - CREDIT, DEBIT etc
bin yes string (6) The first 6 digits of the card
last yes string (4) The last 4 digits of the card
exp_month yes string (2) Card expiration month
exp_year yes string (4) Card expiration year
end of the card array -//- -//- End of the card array
bank yes array or null Contains of acquirer data
id yes integer (0-20) Bank identifier code
authcode yes string (0-45) Bank authorization code
time yes float or null Bank transaction time
end of the bank array -//- -//- End of the bank array
time yes float or null Transaction time in Maxpay system, UTC timezone
token yes string (36) Hashed value of card number, expiry date and cardholder name
transaction_unique_id yes string (1-45) Transaction unique identifier in Merchant system
pares yes string (0-65535) The hashed value of the result of 3D Secure authorization
code yes null or integer(1-4) Transaction response code, check the response codes table below
message yes null or string (6-255) Transaction response message, check the response codes table below
end of transaction array -//- -//- End of the transaction array
source yes string
Possible value: covery		 The source of the alert
alert_id yes int The alert ID
alert_timestamp yes float or null The time when alert was created on 3rd side
receive_timestamp yes float or null The time when alert was received
reason_code yes string The reason code
reason_description yes string The reason description
arn yes string Acquire reference number
bank_auth_code no string (6) Authorization code from original transaction referenced by the Case is provided if available
end of the ethoca_alerts_history -//- -//- ethoca_alerts_history array
end of the ethocaAlertsHistory -//- -//- end of the ethocaAlertsHistory array
status yes string
Possible values: success, error		 Status of the request to QoD API
code yes integer (1-4) Response code of the request to QoD API
message yes string (6-255) Response message of the request to QoD API

Historical Mastercard alerts

Sample code of the Historical Mastercard alerts response in "application/json" format:

    {
      "api_version": 1,
      "timestamp": 1647868801.263569,
      "session_id": "de9c68-1788-62387b7f-17faca26958-32d4",
      "merchant_account": "Account_MP_TRX",
      "mastercardAlertsHistory": [
          {
              "mastercard_alerts_history": {
                  "transaction": {
                      "transaction_type": "SALE",
                      "status": "SUCCESS",
                      "mode": "CC",
                      "reference": "SLFF000000006D65F34B",
                      "base_reference": null,
                      "amount": 1000.0,
                      "currency": "USD",
                      "merchant": {
                          "merchant_account": "Account_MP_TRX",
                          "descriptor_merchant": "",
                          "descriptor_phone": "",
                          "merchant_domain_name": "",
                          "merchant_product_name": "",
                          "merchant_affiliate_id": "",
                          "merchant_user_id": ""
                      },
                      "user": {
                          "first_name": "John",
                          "last_name": "Doe",
                          "country": "USA",
                          "state": "",
                          "city": "New York",
                          "address": "123 Avn",
                          "zip": "12100",
                          "user_ip": "127.0.0.1",
                          "user_email": "johndoe@test.com",
                          "user_phone": "+380505555555"
                      },
                      "card": {
                          "card_holder": "John Doe",
                          "brand": "MASTERCARD",
                          "bank": "Bank",
                          "level": "GOLD",
                          "type": "CREDIT",
                          "bin": "555555",
                          "last": "4444",
                          "exp_month": "02",
                          "exp_year": "2024"
                      },
                      "bank": {
                          "id": 7,
                          "authcode": null,
                          "time": 1647851578.732
                      },
                      "time": 1647851578.0,
                      "token": "5fdca0b2-957c-4bc1-806e-3624f72d6e8b",
                      "transaction_unique_id": "sale_request1647851578",
                      "pares": "",
                      "code": 0,
                      "message": "SUCCESS",
                      "custom_fields": {
                          "custom_card_bank": "MILLENIUM BCP (BANCO COMERCIAL PORTUGUES S.A.)",
                          "custom_card_bin": "555555",
                          "custom_card_brand": "MASTERCARD",
                          "custom_card_country": "PORTUGAL",
                          "custom_card_country_iso3": "PRT",
                          "custom_card_type": "CREDIT",
                          "custom_mid_name": "testmid",
                          "custom_mid_reference": "MD0000000D379F67",
                          "custom_sale_version": "",
                          "custom_scheme_transaction_id": "scheme_transaction_id_557286510",
                          "custom_transaction_mode": "CC"
                      }
                  },
                  "source": "covery",
                  "status": "matched",
                  "alert_id": 127103,
                  "alert_timestamp": 1647852300.0,
                  "receive_timestamp": 1647867947.7161,
                  "transaction_reference": "SLFF000000006D65F34B",
                  "acquirer_transaction_id": null,
                  "reason_code": null,
                  "reason_description": null,
                  "arn": null,
                  "alert_cardBin": "555555",
                  "alert_cardLast4": "4444",
                  "alert_transactionAmount": 1000.0,
                  "alert_transactionCurrency": "USD",
                  "alert_transactionTimestamp": 1647851460.0,
                  "alert_Caid": null,
                  "bank_auth_code": null
              }
          }
      ],
      "status": "success",
      "code": 0,
      "message": "Transaction processed successfully"
  }

Purpose: mastercardAlertsHistory request qod_type allows to get all historical Mastercard alerts on the merchant account

Response parameters:

PARAMETER NAME REQUIRED FORMAT and RULE DESCRIPTION
api_version yes float (1)
Possible value: 1		 API version
timestamp yes integer
unix timestamp		 Query on Demand API response time
session_id yes string (36) Unique session Id of the request
merchant_account yes string (6-32) Merchant account
mastercardAlertsHistory yes array Contains of historical Mastercard alerts data
mastercard_alerts_history yes array Contains of historical Mastercard alert data
transaction yes array Contains of transaction data
transaction_type yes string
Possible values: SALE, SALE3D, SETTLE, AUTH , REFUND		 Type of the transaction
status yes string
Possible values: SUCCESS, DECLINED, REFUNDED, VOIDED, PARTIAL-REFUNDED		 Status of the transaction
mode yes string
Possible values: CC, TOKEN, REF, CASCADE		 Transaction mode.
  • CC - by credit card.
  • TOKEN - by token.
  • REF - by reference.
  • CASCADE - by cascade mode.
reference yes string (20) Reference of the transaction in Maxpay system.
base_reference yes null or string (20) Base reference of the transaction in Maxpay system if exists.
amount yes float (0 - 9999999.9999) Transaction amount
currency yes string (3)
ISO 4217 (alfa-3)		 Transaction currency
merchant yes array or null Contains of merchant data
merchant_account yes string (6-32) Merchant account
descriptor_merchant yes null or string (0-255) Merchant descriptor
descriptor_phone yes null or string (0-255) Merchant descriptor phone
merchant_domain_name yes null or string (0-255) Merchant website name
merchant_product_name yes null or string (0-255) Merchant product name
merchant_affiliate_id yes null or string (0-255) Merchant affiliate identifier
merchant_user_id yes null or string (0-32) Unique user Id in Merchant system
end of the merchant array -//- -//- End of the merchant array
user yes array or null Contains of user data
first_name yes string (1-32) The first name of the customer
last_name yes string (1-32) The last name of the customer
country yes string (2-3)
ISO 3166-1 alpha-3		 Customer's country
state yes null or string (1-32) Customer's state
city yes null or string (2-32) Customer's city
address yes null or string (2-64) Customer's address
zip yes null or string (2-10) Customer's zip
user_ip yes string (IPv4, IPv6) Customer's IP address
user_email yes string (6-255) Customer's email
user_phone yes null or string (7-15) Customer's phone number
end of the user array -//- -//- End of the user array
card yes array or null Contains of custmer's card data
card_holder yes string (2-32) Card holder name
brand yes string (0-255) Card brand - MASTERCARD, MAESTRO
bank yes string (0-255) Issuer bank
level yes string (0-255) Level of the card - ELECTRON, CLASSIC etc
type yes string (0-255) Type of the card - CREDIT, DEBIT etc
bin yes string (6) The first 6 digits of the card
last yes string (4) The last 4 digits of the card
exp_month yes string (2) Card expiration month
exp_year yes string (4) Card expiration year
end of the card array -//- -//- End of the card array
bank yes array or null Contains of acquirer data
id yes integer (0-20) Bank identifier code
authcode yes string (0-45) Bank authorization code
time yes float or null Bank transaction time
end of the bank array -//- -//- End of the bank array
time yes float or null Transaction time in Maxpay system, UTC timezone
token yes string (36) Hashed value of card number, expiry date and cardholder name
transaction_unique_id yes string (1-45) Transaction unique identifier in Merchant system
pares yes string (0-65535) The hashed value of the result of 3D Secure authorization
code yes null or integer(1-4) Transaction response code, check the response codes table below
message yes null or string (6-255) Transaction response message, check the response codes table below
end of transaction array -//- -//- End of the transaction array
source yes string
Possible value: covery		 The source of the alert
alert_id yes int The alert ID
alert_timestamp yes float or null The time when alert was created on 3rd side
receive_timestamp yes float or null The time when alert was received
reason_code yes string The reason code
reason_description yes string The reason description
arn yes string Acquire reference number
bank_auth_code no string (6) Authorization code from original transaction referenced by the Case is provided if available
end of the mastercard_alerts_history -//- -//- mastercard_alerts_history array
end of the mastercardAlertsHistory -//- -//- end of the mastercardAlertsHistory array
status yes string
Possible values: success, error		 Status of the request to QoD API
code yes integer (1-4) Response code of the request to QoD API
message yes string (6-255) Response message of the request to QoD API

VMPI alerts

Sample code of the VMPI alerts response in "application/json" format:

    {
      "api_version": 1,
      "timestamp": 1545117788.019275,
      "session_id": "de7a5f-67f1-5c18a05b-167c0326604-113b",
      "merchant_account": "Account_MP_TRX",
      "vmpiAlerts": [
          {
              "vmpi_alert": {
                  "transaction": {
                      "transaction_type": "SALE",
                      "status": "SUCCESS",
                      "mode": "CC",
                      "reference": "SLFF00000000395BB0C3",
                      "base_reference": null,
                      "amount": 10.0,
                      "currency": "GBP",
                      "merchant": {
                          "merchant_account": "Account_MP_TRX",
                          "descriptor_merchant": "",
                          "descriptor_phone": "",
                          "merchant_domain_name": "",
                          "merchant_product_name": "",
                          "merchant_affiliate_id": "",
                          "merchant_user_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": 1572785332.0,
                      "token": "57c6cf4e-86e0-449d-b790-66cec8812686",
                      "transaction_unique_id": "transaction_5353535351",
                      "pares": "",
                      "code": 0,
                      "message": "SUCCESS"
                  },
                  "source": "VMPI",
                  "alert_id": 123,
                  "alert_timestamp": 1586986433.0,
                  "receive_timestamp": 1586986433.6219,
                  "reason_code": "0",
                  "reason_description": "test",
                  "arn": null,
                  "bank_auth_code": "445688"
              }
          }
      ],
      "status": "success",
      "code": 0,
      "message": "Transaction processed successfully"
    }

Purpose: This subset of API dedicated for VMPI alert notification handling.

Response parameters:

PARAMETER NAME REQUIRED FORMAT and RULE DESCRIPTION
api_version yes int (1)
Possible value: 1		 API version
timestamp yes integer
unix timestamp		 Query on Demand API response time
session_id yes string (36) Unique session Id of the request
merchant_account yes string (6-32) Merchant account
vmpiAlerts yes array Contains of alerts data
vmpi_alert yes array Contains of alert data
transaction yes array Contains of transaction data
transaction_type yes string
Possible values: SALE, SALE3D, SETTLE, AUTH		 Type of the transaction
status yes string
Possible values: SUCCESS, DECLINED, REFUNDED, VOIDED, PARTIAL-REFUNDED		 Status of the transaction
mode yes string
Possible values: CC, TOKEN, REF, CASCADE		 Transaction mode.
  • CC - by credit card.
  • TOKEN - by token.
  • REF - by reference.
  • CASCADE - by cascade mode.
reference yes string (20) Reference of the transaction in Maxpay system.
base_reference yes null or string (20) Base reference of the transaction in Maxpay system if exists.
amount yes float (0 - 9999999.9999) Transaction amount
currency yes string (3)
ISO 4217 (alfa-3)		 Transaction currency
merchant yes array or null Contains of merchant data
merchant_account yes string (6-32) Merchant account
descriptor_merchant yes null or string (0-255) Merchant descriptor
descriptor_phone yes null or string (0-255) Merchant descriptor phone
merchant_domain_name yes null or string (0-255) Merchant website name
merchant_product_name yes null or string (0-255) Merchant product name
merchant_affiliate_id yes null or string (0-255) Merchant affiliate identifier
merchant_user_id yes null or string (0-32) Unique user Id in Merchant system
end of the merchant array -//- -//- End of the merchant array
user yes array or null Contains of user data
first_name yes string (1-32) The first name of the customer
last_name yes string (1-32) The last name of the customer
country yes string (2-3)
ISO 3166-1 alpha-3		 Customer's country
state yes null or string (1-32) Customer's state
city yes null or string (2-32) Customer's city
address yes null or string (2-64) Customer's address
zip yes null or string (2-10) Customer's zip
user_ip yes string (IPv4, IPv6) Customer's IP address
user_email yes string (6-255) Customer's email
user_phone yes null or string (7-15) Customer's phone number
end of the user array -//- -//- End of the user array
card yes array or null Contains of custmer's card data
card_holder yes string (2-32) Card holder name
brand yes string (0-255) Card brand - VISA, MASTERCARD, AMEX, JCB etc
bank yes string (0-255) Issuer bank
level yes string (0-255) Level of the card - ELECTRON, CLASSIC etc
type yes string (0-255) Type of the card - CREDIT, DEBIT etc
bin yes string (6) The first 6 digits of the card
last yes string (4) The last 4 digits of the card
exp_month yes string (2) Card expiration month
exp_year yes string (4) Card expiration year
end of the card array -//- -//- End of the card array
bank yes array or null Contains of acquirer data
id yes integer (0-20) Bank identifier code
authcode yes string (0-45) Bank authorization code
time yes float or null Bank transaction time
end of the bank array -//- -//- End of the bank array
time yes float or null Transaction time in Maxpay system, UTC timezone
token yes string (36) Hashed value of card number, expiry date and cardholder name
transaction_unique_id yes string (1-45) Transaction unique identifier in Merchant system
pares yes string (0-65535) The hashed value of the result of 3D Secure authorization
code yes null or integer(1-4 digits) Transaction response code, check the response codes table below
message yes null or string (6-255) Transaction response message, check the response codes table below
end of transaction array -//- -//- End of the transaction array
source yes string (0-255) Alert source ( VMPI )
alert_id yes integer (0-255) Identifier of the alert from acquirer side.
alert_timestamp yes float or null Time of the alert creation
receive_timestamp yes float or null Time of the alert receiving from acquirer
reason_code yes string or null (0-255) Reason code of the alert
reason_description yes string or null (0-255) Reason description of the alert
arn yes null or string (0-255) Actual Reference number
bank_auth_code no string (6) Authorization code from original transaction referenced by the Case is provided if available
end of vmpi_alert array -//- -//- End of the alert array
end of vmpiAlerts array -//- -//- End of the alerts array
status yes string
Possible values: success, error		 Status of the request to QoD API
code yes integer (1-4) Response code of the request to QoD API
message yes string (6-255) Response message of the request to QoD API

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 REQUIRED FORMAT and RULE DESCRIPTION
api_version yes int (1)
Possible value: 1		 API versionAPI version
merchant_account yes string (6-32) Merchant account
timestamp yes integer
unix timestamp		 Query on Demand API response time
transactions \ chargebacks \ modifications yes array or null QOD type
status yes string
Possible values: success, error		 Status of the request to QoD API
code yes integer (1-4) Response code of the request to QoD API
message yes string (6-255) Response message of the request to QoD API

Erroneous response

Example of response in JSON:

    {
      "api_version": 1,
      "transactions": [],
      "merchant_account": "Account_MP_TRX",
      "timestamp": 1532216783.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 REQUIRED FORMAT and RULE DESCRIPTION
api_version yes int (1)
Possible value: 1		 API versionAPI version
merchant_account yes string (6-32) Merchant account
timestamp yes integer
unix timestamp		 Query on Demand API response time
transactions \ chargebacks \ modifications yes array or null QOD type
status yes string
Possible value: error		 Status of the request to QoD API
code yes integer (1-4) Response code of the request to QoD API
message yes string (6-255) Response message of the request to QoD API

Response statuses

CODE DESCRIPTION
success Succesful QOD response
error Unsuccesful QOD response

QoD API specified response codes

CODE MESSAGE DESCRIPTION (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.

Balance request formats

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

Sample code of the balance request in "application/json" format: "Content-type: JSON, POST" --data

    {
        "api_version": 1,
        "method": "MERCHANT_BALANCE",
        "merchant_account": "Account_MP_TRX",
        "merchant_password": "password123",
        "time": 1604044107
    }

Parameters of balance request:

PARAMETER NAME REQUIRED FORMAT and RULE DESCRIPTION
api_version yes int
Possible value: 1		 API version
merchant_account yes string (6-32) Merchant account
merchant_password yes string (6-32) Account password
method yes string
Possible value: MERCHANT_BALANCE		 Method for the balance request
time yes integer (unix timestamp) Selected time

Sample code of the balance response in "application/json" format:

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

Parameters of balance response:

PARAMETER NAME FORMAT and RULE DESCRIPTION
sessionid string (36) Unique session Id of the request
timestamp integer (unix timestamp) Balance response time
balance[currency] string (3)
ISO 4217 (alfa-3)		 Processing currency
balance[amount] float or integer Processing amount
status string
Possible values: success, error		 Status of the request to Balance API
code integer (1-4) Response code of the request to Balance API
message string (6-255) Response message of the request to Balance API

Balance per MID

Sample code of the balance request per MID in "application/json" format:

    {
        "api_version": 1,
        "method": "MERCHANT_BALANCE_PER_MID",
        "merchant_account": "Account_MP_TRX",
        "merchant_password": "password123",
        "time": 1604044107
    }

Parameters of balance request:

PARAMETER NAME REQUIRED FORMAT and RULE DESCRIPTION
api_version yes int
Possible value: 1		 API version
merchant_account yes string (6-32) Merchant account
merchant_password yes string (6-32) Account password
method yes string
Possible value: MERCHANT_BALANCE_PER_MID		 Method for the balance request per MID
time yes integer (unix timestamp) Selected time

Sample code of the balance response per MID in "application/json" format:

    {
        "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": "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": "UAH",
                        "amount": 0
                    },
                    {
                        "currency": "USD",
                        "amount": -10
                    }
                ]
            ],
        "status": "success",
        "code": 0,
        "message": "Request processed successfully"
    }

Parameters of balance response:

PARAMETER NAME FORMAT and RULE DESCRIPTION
sessionid string (36) Unique session Id of the request
timestamp integer (unix timestamp) Balance response time
balance[mid_name] string (2-32) MID name in Maxpay system
balance[mid_reference] string (16) MID reference in Maxpay system
balance[mid_balance] array MID balance array
balance.mid_balance[currency] string (3)
ISO 4217 (alfa-3)		 Processing currency
balance.mid_balance[amount] float or integer Processing amount
status string
Possible values: success, error		 Status of the request to Balance API
code integer (1-4) Response code of the request to Balance API
message string (6-255) Response message of the request to Balance API

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.

CODE MESSAGE (CAN BE EXTENDED DEPENDING ON CASE)
0 Transaction processed successfully
1 General internal service error
2 Internal DB error
3 General service error
4 Access denied
10 General internal service communication error
11 Internal timeout
12 Internal SSL error
1000 Merchant gate error
1001 Request format error
1002 [field] not present in request
1003 Internal communication error
1004 Invalid [field] in request message
1005 Unsupported API version
1006 [field] should not be present in request
2000 General MMS error
2001 Incorrect value in merchant account or pass field
2002 Country is not available
2003 Merchant account exists but not active
2004 Transaction is not allowed to account
2005 MID is not active
2006 There is no currency configured for account
2007 Amount is below or above amount restrictions
2008 Access from this IP-address is not available
2009 Merchant is not activated
2010 Gate is not active
2011 Entity already exists
2012 Entity not found
2013 Bad API credentials
3000 General processing error
3001 Transaction ID/Order ID is already used
3002 Token not found or invalid
3003 Reference not found or invalid
3004 It is not possible to void the the provided reference
3005 It is not possible to refund the provided reference
3006 Transaction is chargebacked
3007 Illegal interval between AUTH and SETTLE/VOID, between AUTH 3D and SETTLE/SALE
3008 Transaction was already voided
3009 Transaction was already refunded
3010 Transaction was already settled
3011 MID doesn't support the card type
3012 Account doesn't support 3D secure
3013 Account support only 3D secure transaction
3014 There was no transaction found on your Check request
3015 Bank MID doesn't support the currency
3016 Amount in settle transaction is incorrect
3017 Bank MID access credentials are incorrect
3018 Bank refused the connection
3019 Request cannot be validated
3020 Chargeback is invalid
3021 Transaction is blocked by routing
3022 The amount is incorrect
3023 Transaction is aborted by the customer
3024 Transaction is expired
3025 Transaction is completed
3026 Declined by modification
3027 Pending MSISDN found
3100 Transaction declined by bank network
3101 Insufficient funds
3102 Card lost or stolen
3103 3d secure authentication failed
3104 Invalid CVV
3105 Card expired due to expiry date or expiry date is not correct
3106 Bank cannot process selected amount
3107 Invalid card number
3108 It is not possible to issue refund due to bank limit
3109 Timeout between PSP and bank
3110 Not all required data was provided to the specific bank
3111 Access error to a bank acquirer
3112 Card type is not supported by MID
3113 Transaction type is not supported by MID
3114 Currency is not supported by MID
3115 Refund not possible by bank
3116 Country is not supported by MID
3117 Malformed bank response
3118 Connection error between PSP and bank
3119 Referal or restricted card
3120 Risk Bank Decline
3121 Invalid acquirer token
3122 Invalid acquirer reference
3123 Card 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
3130 Revocation of authorization order
3131 Repeats not allowed by operator
3132 Recurring is stopped by the customer
3133 Unexpected acquirer behavior
3134 Transaction is expired (by bank)
3135 Verification required by issuer
3140 General bank decline
3150 Invalid transaction
3157 Transaction not permitted
3170 Invalid or closed account
3200 Declined by anti-fraud system
3201 Sent for manual review by anti-fraud system
3202 Volume limit exceeded
3203 Refund limit exceeded
3220 Declined by anti-fraud trust lists
3221 Sent for manual review by anti-fraud trust lists
3300 General payout error
3310 Payout validation error
3311 Invalid mid reference
3330 Unregistered card
4000 General reconciliation error
4001 Reconciliation data is not ready
4002 Reconciliation total amount doesn't match
4003 Reconciliation total count doesn't match
4004 General FRS error
4005 Balance is not available
4006 Currency is not available
4007 Exceeded amount
5000 General QoD error
5001 Unsupported QoD API version
5002 Invalid [time] fields order
6000 General 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
6013 Recovery key have been used
6014 Request totp from user
7000 Internal payment gate error
7101 Internal payment gate sender error
7102 External communication error
7103 External communication timeout
8000 General internal stats failure
8001 Date range is too long for selected aggregation interval

Behavior on response codes

RC TRANSACTION RESULT ACTION
0 SUCCESS
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

Decline Code Management and Authorization Consistency

Consistency The Visa Rules require Issuers to use descriptive response codes to help Merchants or Acquirers identify the reason for a transaction decline. Increased visibility into the cause of declines will allow Merchants or Acquirers to create improved authorization reattempt strategies and will minimize issuer impacts associated with reattempts for transactions they will never approve. To make response codes more useful, Visa has grouped existing decline codes into categories. Issuers must use descriptive response codes across all groupings when responding to authorization requests.

Category Code Title Description Action
1 Issuer Will Never Approve Response codes that indicate the account never existed or is permanently blocked including lost or stolen account numbers. This category also includes decline codes that indicate the transaction is not permitted due to permanent product/regulatory restrictions or transaction error. Do not reattempt
2 Issuer Cannot Approve at This Time Response codes that indicate the Issuer cannot approve due to temporary decline condition such as insufficient funds, Issuer velocity controls or other temporary account restrictions. These temporary decline decisions made by Issuers that may change over time and the Issuer may approve a future authorization attempt. In some cases, cardholder action is required to remove the restriction before an approval can be obtained. Reattempt permitted up to 15 times in 30 days
3 Data Quality (Revalidate Data Prior To Reattempt) Response codes that indicate data quality issues where invalid payment or authentication data has been provided and the Issuer may approve if valid information is provided. High occurrences of response codes in these categories may indicate insufficient Merchant risk protection controls such as velocity checks and pre-validation of basic account information (e.g. Mod-10 or expiry date). Reattempt permitted up to 15 times in 30 days
4 Generic Response Codes This category includes all other decline response codes, many of which provide little to no value to Acquirers or Merchants in determining their reattempt strategy. Issuer usage should remain minimal. Reattempt permitted up to 15 times in 30 days

Please, contact your account manager in order to provide an automated risk policy for the declines above. Or, do it on your side:

Card brand Category title Action

VISA
Category 1 - Issuer Will Never Approve
3102 Card lost or stolen
3107 Invalid card number
3119 Referal or restricted card
3127 Bank negative list
3150 Invalid transaction
3157 Transaction not permitted 		Re-attempt not permitted
Category 2 - Issuer Cannot Approve at this Time
3100 Declined
3101 Insufficient funds
3106 Bank cannot process selected amount
3118 Connection error between PSP and bank
3126 Withdrawal frequency limit exceeded
3128 Fraud bank decline
3132 Recurring is stopped by the customer
3170 Invalid or closed account 		Reattempt permitted up to 15 times in 30 days
Category 3 - Issuer Cannot Approve based on Details Provided
3104 Invalid CVV
3105 Card expired due to expiry date or expiry date is not correct
3135 Verification required by issuer 		Reattempt permitted up to 15 times in 30 days
Category 4 - Generic Response Codes
Other decline codes Reattempt permitted up to 15 times in 30 days

MasterCard
Category 1 - Issuer Will Never Approve
3102 Card lost or stolen
3105 Card expired due to expiry date or expiry date is not correct
3107 Invalid card number
3119 Referal or restricted card
3128 Fraud Bank Decline
3150 Invalid transaction
3157 Transaction not permitted
 Re-attempt not permitted
Category 4 - Generic Response Codes
Other decline codes Permitted up to 10 times within 24 hours

API libraries and plugins

PLUGIN or LIBRARY NAME REFERENCE to GITHUB
Maxpay hosted payment page client (PHP) MAXPAY HOSTED PAYMENT PAGE
Module for Magento 1.9 MAGENTO
WooCommerce (Wordpress) WOOCOMMERCE
Drupal DRUPAL
PrestaShop PRESTASHOP
OXID OXID
OpenCart OPENCART
Magento V2.0 Magento V2.0
Shopify Shopify
iOS Mobile SDK iOS Mobile SDK
Android Mobile SDK Android Mobile SDK

ApplePay instructions

ApplePay enrollment and merchant ID creating

Create an Apple ID

A merchant needs to register at https://appleid.apple.com/account to create an Apple ID. Apple ID is an identifier that allows working within the Apple ecosystem.

Create an Apple ID

Create a Merchant ID

This ID identifies your merchant in the Apple Pay system.

The guide steps to creating a Merchant ID are provided below:

  1. Sign in to Apple Developer Account (developer.apple.com/account.) and choose the Identifiers section Create a Merchant ID
  2. Click on the plus symbol to add a new one. Create a Merchant ID Create a Merchant ID
  3. Choose the Merchant IDs option and click on the Continue button.
  4. Enter Description and Identifier values, then click on the Continue button. Create a Merchant ID
  5. When the values are entered, click on Continue and then Register

Generating a Payments Processing Certificate

This certificate is associated with your Merchant ID and is used to secure transaction data. Before creating, ask Maxpay's support team (support@maxpay.com) to provide a .csr file.

The guide steps to creating a Payments Processing Certificate are provided below:

  1. In the Apple Developer Account, choose Certificates Generating a Payments Processing Certificate
  2. Click on the plus symbol to add a new one. Generating a Payments Processing Certificate
  3. Choose the Apple Pay Payment Processing Certificate and click on the Continue button. Generating a Payments Processing Certificate
  4. Choose the Merchant ID for the Payment Processing Certificate and click on the Continue button. Generating a Payments Processing Certificate
  5. Under the Apple Pay Payment Processing Certificate headline, click on the Create Certificate button. Generating a Payments Processing Certificate Generating a Payments Processing Certificate
  6. Click on the Choose File link to upload the CSR file.
  7. In the pop-up window, choose the CSR file previously provided by the support team.
  8. Click on the Continue button.
  9. Then click on the Download button to get the CER file.
  10. Convert the CER file from Apple to PEM and provide it to Maxpay's support team.

Generating a Merchant Identity Certificate

It's a Transport Layer Security (TLS) certificate associated with your merchant ID, used to authenticate your sessions with the Apple Pay servers. Before creating, generate a CSR file that will be needed for Merchant Identity Certificate creation.

The guide steps to creating a Merchant Identity Certificate are provided below:

  1. Sign in to the Apple Developer Account and choose the Certificates. Generating a Merchant Identity Certificate
  2. Click on the plus button. Generating a Merchant Identity Certificate
  3. Choose the Apple Pay Merchant Identity Certificate and click on the Continue button. Generating a Merchant Identity Certificate
  4. Choose the Merchant ID for the Merchant Identity Certificate and click on the Continue button. Generating a Merchant Identity Certificate
  5. Then click on the Choose File link. Generating a Merchant Identity Certificate
  6. In the pop-up window, choose the previously-generated CSR file.
  7. Click on the Continue button.
  8. Then click on the Download button to get the CER file.

ApplePay Domain(s) verification

Register and verify all domains and subdomains where the Apple Pay button is presented.

These are the requirements for incorporating Apple Pay on your website:

Registration features:

The guide steps to Register and Verify Your Domain(s) are provided below:

  1. Sign in to the Apple Developer Account with Admin or Account Holder access.
  2. Choose the Identifiers. ApplePay Domain(s) verification
  3. Click on the App IDs link on the right side and choose the Merchant IDs link from the menu. ApplePay Domain(s) verification
  4. Click on the Merchant Identifier value. ApplePay Domain(s) verification
  5. Under the Merchant Domains headline, click on the Add Domain button. ApplePay Domain(s) verification
  6. Enter the domain name and click on the Save button. ApplePay Domain(s) verification
  7. Click on the Download button to save the verification file.
  8. Create the location on your server for this file. The path should be https://<your domain>/.well-known/
  9. Add the downloaded file to https://<your domain>/.well-known/
  10. When the file is placed, click on the Verify button at the Apple Developer Account.
  11. If the process passes correctly, click on the Done button. That's it!

ApplePay integration references

To generate an ApplePay token:

  1. Follow the integration guide by Apple - https://developer.apple.com/apple-pay/
  2. In Xcode, you need to enable Apple Pay for your application. In the Capabilities, panel click on the switch near Apple Pay and select from the list the Merchant ID for this application.
  3. For the PKPaymentRequest you need to pass only PKMerchantCapability3DS, request.merchantCapabilities = PKMerchantCapability3DS

To decrypt an ApplePay token follow a guide

Cookies
Maxpay website uses cookies to deliver the best service to you. You can disable cookies at any time. Otherwise, we’ll assume you’re OK to continue. Read more in our Cookie Policy.