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 and Query on demand API.

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

Hosted payment pages

Overview

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

General

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

Create product

You can sell goods by using Maxpay payment flow or either send us the custom products by using custom product API.

Payment methods

Here you can manage payment methods available on your payment widget. Currently the only available payment method is ‘credit card’, more payment methods coming soon!

Payment form customizer

Maxpay’s payment form customizer allows you to:

iFrame, external payment page

Example callback:

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

URL Sample (it’s actually works, try to open it)

GET https://hpp.maxpay.com/hpp?uniqueUserId={{aUniqueUserIdInYourSystem}}&key=pkTest_56137fd80ffc4a639cf91e81941d1f51&signature=bac1c2876f98149d225da91c85956ece1d695809d2a32fff81459c04ff77580b
In order to receive payments from your customers you simply need to pass “uniqueUserId” in the URL. External payment page, “Buy” button pop-up or iFrame could be found in the “Widget” settings of “Application” settings.

Simple popup integration (it’s actually works, try to open it)

Example popup integration:

<div>
    <form class='maxpayPaymentForm'>
        <script
            src="https://hpp.maxpay.com/client.js" 
            class="maxpayScript" 
            data-iframesrc="https://hpp.maxpay.com/hpp" 
            data-key="pkTest_56137fd80ffc4a639cf91e81941d1f51" 
            data-signature="bac1c2876f98149d225da91c85956ece1d695809d2a32fff81459c04ff77580b" 
            data-uniqueuserid="testUserId" 
            data-type="popup">
        </script>
    </form>
</div>



Going live

In order to switch the processing to live mode simply send us your integration for review by clicking on ‘send for review’ button in your ‘application’ section. Our Integration Team will review your application carefully and get back to you as soon as possible.

Custom product API

Example of payment page with custom product

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


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

Request parameters:

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

Example callback:

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

Callback values

Description of callback fields

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


Rebilling API

Example request:

<?php
    array (
      'publicKey' => 'pkTest_56137fd80ffc4a639cf91e81941d1f51',
      'signature' => 'bac1c2876f98149d225da91c85956ece1d695809d2a32fff81459c04ff77580b',
      'rebillToken' => '575955d2-5818-4806-8498-7855f3666259',
      'productId' => 'myproductId',
      'uniqueUserId' => 'subscriptionfull',
      'amount' => 100,
      'productName' => 'Monthlysubscription',
      'currency' => 'USD',
      'productType' => 'subscriptionProduct',
      'subscriptionLength' => 1,
      'subscriptionPeriod' => '24H',
      'subscriptionTrialPrice' => 99.9,
      'subscriptionTrialStart' => 1447337995,
      'subscriptionTrialEnd' => 1497339252,
      'subscriptionEndDate' => 1498030452,
    )
?>

Example callback:

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

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

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

Parameters explanation

PARAMETER REQUIRED DESCRIPTION
publicKey yes The public key of the application. Could be found in the general settings of the application.
uniqueUserId yes The unique id of the user in your system.
rebillToken yes The unique payment token which is received after the customer made the initial payment.
productId yes A unique ID of the product. Could be found in the “Product” settings of the application. In case product is created in Maxpay merchant portal you can simply send the ‘productId’, all other parameters Maxpay will handle for you. In case you’re sending the product from your database you should pass the product parameters below.
productName yes The name of the product.
productDescription optional The description of the product.
productType yes The type of product which merchant is planning to sell. Values:
  • fixedProduct - simple one time product;
  • subscriptionProduct - recurring type product;
  • trialProduct - special trial product which will transform in the indicated product.
currency optional Default EUR string. ISO 3 currencies.
amount yes The price of the product.
discount optional The discount for the product. Applicable only for ‘fixed’ and ‘subscription’ type products.
discountType required if ‘discount’ was set up. Discount could be set in percent of original price or in fixed amount. Applicable only for ‘fixed’ and ‘subscription’ type products. Values:
  • amountOff;
  • percentOff.
subscriptionLength optional Applicable only if the product type is ‘subscriptionProduct’ numeric. The length of the subscription product.
subscriptionPeriod optional Applicable only if the product type is ‘subscriptionProduct’ string. The period of subscription. Values:
  • 24H;
  • 7D;
  • 30D;
  • 365D.
subscriptionEndDate optional Applicable only if the product type is ‘subscriptionProduct’ float. The end date of the subscription. After this date end user won’t be charged again.
subscriptionTrialPrice optional If the product type is ‘subscriptionProduct’ float. The price of subscription’s trial period. This price will be charged only during ‘trialStart’, ‘trialEnd’ indicated periods.
subscriptionTrialStart optional Applicable only if the product type is ‘subscriptionProduct’ float, micro time ‘true’.
subscriptionTrialEnd optional Applicable only if the product type is ‘subscriptionProduct’ float, micro time ‘true’.
trialLength optional Applicable only if the product type is ‘trialProduct’ numeric. The length of the trial product.
trialPeriod optional Applicable only if the product type is ‘trialProduct’ string. The period of trial. Values:
  • 24H;
  • 7D;
  • 30D;
  • 365D.
postTrialProductId optional Applicable only if the product type is ‘trialProduct’ string. The following product will be charged after the trial product will expire . Note: In order to use post trial product it should be created in maxpay merchant portal.
signature yes Maxpay signature. Calculation is described above.

Callback values

Description of callback fields

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

Cancel subscription API

Example request:

<?php

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

?>

Example callback:

{
"requestSuccess": true,
"payload": {
"transactionId": "hpp1467893228.4626mId571aId0",
"message": "Subscription products successfully stopped.",
"status": "Success",
"productList": [ {
"productId": "p_a98f28b23a",
"name": "subscription",
"amount": 2,
"currency": "EUR" 
}
],
"checkSum": "810ed9abe39347211665d403fdea62919aa4d5fe4cb0077bbb8b47db160248da" 
}
}

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

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

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 Maxpay signature. Calculation is described above.

Callback values

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

HPP signature calculation

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

<?php
$signature = new SignatureHelper();
$checkSum = $signature->generate(
                $data,
                $privateKey
            );
?>

Maxpay hpp signature is calculated as:

hash('sha256', $publicKey . $privateKey);

You can find your test and live application keys under the “General” tab of application settings.

The callback is encrypted using “checkSum” parameter.

Maxpay.js

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

Response codes

The table below provides the response codes information which you could receive via callback url.

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

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.

Auth transaction

Example of AUTH transaction request:

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

“Content-type: application/json” –data

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

Example of AUTH response in JSON format:

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

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

Request parameters:

Parameter Name Type Mandatory Rules Example
api_version float/string yes maxLength: { max: 32 } 1
merchant_account string yes minLength: { min: 6 }, maxLength: { max: 32 } Testshop.com
merchant_password string yes minLength: { min: 6 }, maxLength: { max: 32 } testpassword
transaction_unique_id string yes minLength: { min: 6 }, maxLength: { max: 32 } NwAkrkcPAmEcGzghnBwMeDRpXAPFsINg
transaction_type string yes validTransType, enum: { values: [”AUTH”]} AUTH
amount float yes float, maxLength: [0 - 9999999999.999] 5800
currency string yes length: { size: 3 }, ISO 4217 (alfa-3) GBP
card_number string yes minLength: { min: 13 }, maxLength: { max: 19 } only digits, Luhn algorithm 4864369454425300
card_exp_month string yes length: { size: 2 }, only digits 05
card_exp_year string yes length: { size: 4 }, only digits 2016
cvv string no minLength: { min: 3}, maxLength: { max: 4 }, only digits 911
first_name string yes minLength: { min: 1}, maxLength: { max: 32 } Card
last_name string yes minLength: { min: 1 }, maxLength: { max: 32 } Holder
card_holder string yes minLength: { min: 2 }, maxLength: { max: 32 } Card Holder
address string no minLength: { min: 2 } maxLength: { max: 32 } Billing address
city string no minLength: { min: 2 }, maxLength: { max: 32 } New Castle
state string no minLength: { min: 1 }, maxLength: { max: 32 } Texas
zip string yes minLength: { min: 2 }, maxLength: { max: 10 } 235467
country string yes minLength: { min: 2 }, maxLength: { max: 3 }, ISO 3166-1 alpha-3 GBR
user_phone string no minLength: { min: 7 }, maxLength: { max: 15 } 380111111111
user_ email string yes minLength: { min: 6 }, maxLength: { max: 255 }, valid email 14848ff0308f8a396041ddde45de5f8a@gmail.com
user_ip string yes Ipv4Address 192.168.0.1
merchant_user_id string no maxLength: { max: 32 } 6d4a5d94821279725ecb3b0da9319d9b
merchant_domain_name string no maxLength: { max: 255 } vertu.com
merchant_affiliate_id string no maxLength: { max: 255 } 1234
merchant_product_name string no maxLength: { max: 255 } Chips
descriptor_merchant string no maxLength: { max: 255 } merchant.com
descriptor_phone string no maxLength: { max: 255 } 180012345678
pares string no NotEmptyString ABJASDKA+SDKAJ/SGDSAD

Response parameters:

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

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

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

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

Auth (with token) transaction

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

Request parameters:

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

Response parameters:

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

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

Sale transaction

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

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

Request parameters:

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

Response parameters:

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

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

Sale (with token) transaction

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

Request parameters:

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

Response parameters:

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

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

Auth3D transaction

Sample code example of AUTH3D transaction request:

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

“Content-type: application/json” –data

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

Sample code example of AUTH3D response in JSON format:

{
    "api_version":1,
    "merchant_account":"emulator",
    "sessionid": "543e2136-d46c-4d7d-a3b3-075cf9af6dea",
    "transaction_unique_id":"myUniqId1",
    "token":"55a28a26-92e8-4026-bdc8-2e2f58a0e038",
    "reference":"A3FF00000000333AE719",
    "timestamp":1408001694,
    "authcode":"1438818146.4364",
    "eci":1,
    "pareq":"6497906a9649ca2d7a4f2d32d8179d0e",
    "acs_url":"http://merchant.com",
    "status":"success",
    "code":0,
    "message":"transaction processed successfully"
}

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

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

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

Request parameters:

Parameter Name Type Mandatory Rules Example
api_version float/string yes maxLength: { max: 32 } 1
merchant_account string yes minLength: { min: 6 }, maxLength: { max: 32 } Testshop.com
merchant_password string yes minLength: { min: 6 }, maxLength: { max: 32 } testpassword
transaction_unique_id string yes minLength: { min: 6 }, maxLength: { max: 32 } NwAkrkcPAmEcGzghnBwMeDRpXAPFsINg
transaction_type string yes validTransType, enum: { values: [”AUTH3D”]} AUTH3D
amount float yes float, maxLength: [0 - 9999999999.999] 5800
currency string yes length: { size: 3 }, ISO 4217 (alfa-3) GBP
card_number string yes minLength: { min: 13 }, maxLength: { max: 19 } only digits, Luhn algorithm
  • 4012000300001003
  • 5191330000004415
card_exp_month string yes length: { size: 2 }, only digits 05
card_exp_year string yes length: { size: 4 }, only digits 2016
cvv string no minLength: { min: 3}, maxLength: { max: 4 }, only digits 911
first_name string yes minLength: { min: 1}, maxLength: { max: 32 } Card
last_name string yes minLength: { min: 1 }, maxLength: { max: 32 } Holder
card_holder string yes minLength: { min: 2 }, maxLength: { max: 32 } Card Holder
address string no minLength: { min: 2 } maxLength: { max: 32 } Billing address
city string no minLength: { min: 2 }, maxLength: { max: 32 } New Castle
state string no minLength: { min: 1 }, maxLength: { max: 32 } Texas
zip string yes minLength: { min: 2 }, maxLength: { max: 10 } 235467
country string yes minLength: { min: 2 }, maxLength: { max: 3 }, ISO 3166-1 alpha-3 GBR
user_phone string no minLength: { min: 7 }, maxLength: { max: 15 } 380111111111
user_ email string yes minLength: { min: 6 }, maxLength: { max: 255 }, valid email 14848ff0308f8a396041ddde45de5f8a@gmail.com
user_ip string yes Ipv4Address 192.168.0.1
merchant_user_id string no maxLength: { max: 32 } 6d4a5d94821279725ecb3b0da9319d9b
merchant_domain_name string no maxLength: { max: 255 } vertu.com
merchant_affiliate_id string no maxLength: { max: 255 } 1234
merchant_product_name string no maxLength: { max: 255 } Chips
descriptor_merchant string no maxLength: { max: 255 } merchant.com
descriptor_phone string no maxLength: { max: 255 } 180012345678

Response parameters:

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

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

Auth3D (with token) transaction

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

Request parameters:

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

Response parameters:

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

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

Sale3D transaction

To check if the $signature is calculated correct please refer the following example:

Sample PHP code example of signature value calcualtion

<?php
/* Example of callbacked response */

array (
    'api_version' => '1',
    'sessionid' => '55882952-a344-40ce-af84-173c025bd8bd',
    'token' => '55880d83-3fb0-43eb-a18f-173c025bd8bd',
    'authcode' => '1434986845.693',
    'reference' => 'SLFF00000000395DA2C3',
    'transaction_unique_id' => '1434986821.1471529083',
    'timestamp' => '1434986844',
    'status' => 'success',
    'code' => '0',
    'message' => 'Transaction processed successfully',
    'signature' => '7be7f8abad70931c177bedb88993405ab88aee79e0a54b8411f02eadc27f3476'
)

/* To validate signature from response do the following */

$signature =  ksort($mixed); /* sorts fields alphabetically */

foreach ($mixed as $key => $value) {
    if ($key === 'signature') {
        continue;
    }
    $signature .= $key . '=' . $value;
}

$signature .= hash('sha512', $secret); /*  adds hashed Merchant account password, for example used ‘testpassword’ */

/* Example of signature prepared fieldset 

$signature = ‘api_version=1authcode=1434986845.693code=0message=Transaction processed successfullyreference=SLFF00000000395DA2C3sessionid=55882952-a344-40ce-af84-173c025bd8bdstatus=successtimestamp=1434986844token=55880d83-3fb0-43eb-a18f-173c025bd8bdtransaction_unique_id=1434986821.1471529083e9e633097ab9ceb3e48ec3f70ee2beba41d05d5420efee5da85f97d97005727587fda33ef4ff2322088f4c79e8133cc9cd9f3512f4d3a303cbdb5bc585415a00’;

*/

    return hash('sha256', $signature); /* calculates $signature value */

    /* Example of calculated signature field value 

$signature = ‘7be7f8abad70931c177bedb88993405ab88aee79e0a54b8411f02eadc27f3476’;

*/

?>

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

Request parameters:

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

Response parameters:

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

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

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

Call back SALE response parameters:

Parameter Name Type Mandatory Rules Example
api_version float yes maxLength: { max: 32 } 1
merchant_account string yes minLength: { min: 6 }, maxLength: { max: 32 } Testshop.com
sessionid string yes maxLength: { max: 36 } 55882952-a344-40ce-af84-173c025bd8bd
transaction_unique_id string yes maxLength: { max: 32 }, minLength: { min: 1 } 1434986821.1471529083
token string yes length: { size: 36 } 55880d83-3fb0-43eb-a18f-173c025bd8bd
reference string yes length: { size: 20 } SLFF00000000395DA2C3
timestamp string yes unix timestamp 1434986844
authcode string yes maxLength: { max: 24 } 1434986845.693
status string yes { SUCCESS, DECLINE, ERROR } SUCCESS
code numeric yes Returns response code for the transaction Response codes table
message string yes Returns explanation of the response code Response codes table
signature * string yes maxLength: { max: 32 } 7be7f8abad70931c177bedb88993405ab88aee79e0a54b8411f02eadc27f3476

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

Merchant depending on business requirements has ability but not forced to send the following transactons:

Sale3D (with token) transaction

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

Request parameters:

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

Response parameters:

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

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

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

Refund transaction

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

Request parameters:

Parameter Name Type Mandatory Rules Example
api_version float yes maxLength: { max: 32 } 1
merchant_account string yes minLength: { min: 6 } maxLength: { max: 32 } Testshop.com
merchant_password string yes minLength: { min: 6 } maxLength: { max: 32 } testpassword
transaction_unique_id string yes minLength: { min: 1 } maxLength: { max: 32 } NwAkrkcPAmEcGzghnBwMeDRpXAPFsINg
transaction_type string yes validTransType, enum: { values: [“REFUND”]} REFUND
amount float yes float, maxLength: [0 - 9999999999.999] 5800
currency string yes length: { size: 3 }, ISO 4217 (alfa-3) GBP
reference string yes length: { size: 20 } 14848ff0308f8a396041ddde45de5f8ffffa
merchant_user_id string no maxLength: { max: 32} 6d4a5d94821279725ecb3b0da9319d9b
descriptor_merchant string no maxLength: { max: 255 } merchant.com
descriptor_phone string no maxLength: { max: 255 } 180012345678

Response parameters:

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

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

Void transaction

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

Request parameters:

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

Response parameters:

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

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

Settle transaction

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

Request parameters:

Parameter Name Type Mandatory Rules Example
api_version float yes maxLength: { max: 32 } 1
merchant_account string yes minLength: { min: 6 } maxLength: { max: 32 } Testshop.com
merchant_password string yes minLength: { min: 6 }, maxLength: { max: 32 } testpassword
transaction_unique_id string yes minLength: { min: 6 }, maxLength: { max: 32 } NwAkrkcPAmEcGzghnBwMeDRpXAPFsINg
transaction_type string yes validTransType, enum: { values: ["SETTLE”]} SETTLE
amount float yes float, maxLength: [0 - 9999999999.999] 5800
currency string yes length: { size: 3 }, ISO 4217 (alfa-3) GBP
reference string yes length: { size: 20 } 14848ff0308f8a396041ddde45de5f8ffffa
merchant_domain_name string no maxLength: { max: 255} merchant.com
merchant_affiliate_id string no maxLength: { max: 255} 1
merchant_user_id string no maxLength: { max: 32} 6d4a5d94821279725ecb3b0da9319d9b
merchant_product_name string no maxLength: { max: 255} Test product
descriptor_merchant string no maxLength: { max: 255} merchant.com
descriptor_phone string no maxLength: { max: 255} 180012345678

Response parameters:

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

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

Check transaction

Sample code example of CHECK request:

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

“Content-type: application/json” –data

{
    "api_version":1,
    "merchant_account":"test_account ",
    "merchant_password":"test_passw",
    "transaction_type":"AUTH",
    "reference":"ATFF00000000395AD690",
     "transaction_unique_id":"myUniqId1"
}

Sample code example of CHECK response in JSON format:

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

Purpose: Interface should be used to check transaction status.

Request parameters:

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

Response parameters:

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

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

Tokenize transaction

Sample code example of TOKENIZE request:

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

“Content-type: application/json” –data

{
    "api_version":1,
    "merchant_account":"test_account ",
    "merchant_password":"test_passw",
    "transaction_type":"TOKENIZE",
    "card_number":"4111111111111111",
    "card_exp_month":"05",
    "card_exp_year":"2016",
    "cvv":"111",
    "card_holder":"John Doe"
}

Sample code example of TOKENIZE response in JSON format:

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

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

Request parameters:

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

Response parameters:

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

After the Tokenize transaction has been processed a merchant has ability to use card Token instead of credit card number details.

Erroneous response

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

Response parameters:

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

Erroneous response on check

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

Response parameters:

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

Response codes

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

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

Behavior on response codes

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

Payout API

Overview

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

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

Payout Methods

Example of request for searching available payout methods:

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

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

Request parameters:

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

Example of response in JSON format:

    {
    "sessionid": "someid",
    "status": "success",
    "code": 0,
    "message": "Request processed successfully",
    "methods": [
        {
            "type": "card",
            "mid_name": "my_mid_name",
            "mid_reference": "0001234567J",
            "currencies": ["USD"]
        },
        {
            "type": "qiwi",
            "mid_name": "my_mid_name",
            "mid_reference": "0001234567J",
            "currencies": ["EUR", "USD"]
        }
    ]
}

Response parameters:

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

Methods

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

Payout on CC

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

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

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

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

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

Payout via Token

Example of the payout request on credit card via Token:

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

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

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

Parameters of the payout request on credit card via Token:

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

Example of the response in JSON format:

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

Response parameters:

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

Payout cancellation

Example of payout cancellation request:

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

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

Request parameters of payout cancellation:

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

Example of cancellation response in JSON format:

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

Response parameters of payout cancellation:

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

Payout callback

Example of callback response in JSON format:

{
    "payout_id": "id",
    "reference": "PTFF000000000001",
    "transaction_status": "SUCCESS",
    "status": "success",
    "code": 0,
    "message": "Transaction processed successfully!"
}

Response parameters of the callback:

Field Mandatory Value Description
payout_id yes string An unique Id of the payout transaction.
reference yes string An unique reference of the transaction.
transaction_status yes string Status of the transaction.
status yes string ENUM ['success’, 'decline’, 'error’] Response status
code yes int Response code
message yes string Response message.

Query on demand API

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

Access to Maxpay Qod API

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

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

Qod Workflow

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

Qod Request formats

Qod Response formats

Sample code example of QOD request:

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

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

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

Request parameters are general for all request types

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

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

Transactions

Example of response in JSON:

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

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

Response parameters:

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

Chargebacks

Example of response in JSON:

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

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

Response parameters:

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

Modifications

Example of response in JSON:

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

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

Response parameters:

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

Request validation specified (not API) response codes

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

Empty response

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

Response parameters:

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

Erroneous response

Example of response in JSON:

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

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

Response parameters:

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

Response statuses

Code Description
success Succesful QOD response
error Unsuccesful QOD response

Qod API specified response codes

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

Other response codes

Module Code Value Message (can be extended depending on case)
GENERAL 0 SUCCESS transaction processed successfully
1 GENERAL SYSTEM ERROR general system error
2 DATABASE ERROR internal DB error
3 INTERNAL SERVICE ERROR general internal service error
10 INTERNAL SERVICE COMM ERROR general internal service communication error
11 INTERNAL SERVICE TIMEOUT internal timeout
12 SERVICE SSL ERROR internal SSL error
1000 GENERAL MERCHANT GATE ERROR merchant gate error
1001 GENERAL MERCHANT GATE ERROR request format error
1002 MANDATORY FIELDS ARE MISSING [field] not present in request
1003 INTERNAL COMM ERROR internal communication error
1004 INVALID PARAMETER invalid [field] in request message
1005 UNSUPPORTED API VERSION unsupported API version
2000 GENERAL MMS ERROR all other errors
2001 INVALID MERCHANT ACC PASSWORD incorrect value in merchant account or pass field
2002 COUNTRY RESTRICTIONS country is not available
2003 MERCHANT ACC IS NOT ACTIVE merchant account exists but not active
2004 UNAUTHORIZED TRANSACTION transaction is not allowed to account
2005 MID NOT ACTIVE there is no MID configured for account
2006 CURRENCY NOT ACTIVE there is no currency configured for account
2007 AMOUNT RESTRICTIONS amount is below or above amount restrictions
2008 IP ADDRESS RESTRICTIONS access from this IP-address is not available
2009 MERCHANT NOT ACTIVE merchant is not activated
2010 GATE NOT ACTIVE gate is not active
2011 ENTITY_ALREADY_EXISTS entity already exists
2012 ENTITY_NOT_FOUND entity is not found
2013 BAD_MID_CREDENTIALS bad mid credentials
3000 GENERAL PROCESSING ERROR all other errors
3001 TRANSACTION UNIQUE ID ALREADY USED transaction ID/ Order ID is already used
3002 INVALID TOKEN token not found or invalid
3003 INVALID REFFERENCE reference not found or invalid
3004 VOID NOT POSSIBLE it is not possible to void the the provided reference
3005 REFUND NOT POSSIBLE it is not possible to refund the provided reference
3006 TRANSACTION IS CB transaction is chargebacked
3007 ILLEGAL INTERVAL illegal interval between AUTH and SETTLE/VOID, between AUTH 3D and SETTLE/SALE
3008 ALREADY VOIDED transaction was already voided
3009 ALREADY REFUNDED transaction was already refunded
3010 ALREADY SETTLED transaction was already settled
3011 CARD TYPE NOT SUPPORTED MID doesn’t support the card type
3012 ACCOUNT IS NOT 3D ENABLED account doesn’t support 3D secure
3013 REQUIRED 3DS account support only 3D secure transaction
3014 TRANSACTION NOT FOUND FOR CHECK there was no transaction found on your Check request
3015 INVALID CURRENCY bank MID doesn’t support the currency
3016 WRONG SETTLE AMOUNT amount in settle transaction is incorrect
3017 WRONG MID CREDENTIALS bank MID access credentials are incorrect
3018 MID IP ERROR bank refused the connection
3019 VALIDATION FAILED request cannot be validated
3020 INVALID CHARGEBACK chargebacks is invalid
3021 TRANSACTION BLOCKED transaction is blocked by routing
3022 INCORRECT AMOUNT the amount is incorrect
3023 ABORTED TRANSACTION transaction is aborted by the customer
3024 EXPIRED TRANSACTION transaction is expired
3100 GENERAL BANK DECLINE transaction declined by bank network
3101 INSUFFICIENT FUNDS insufficient funds
3102 LOST/STOLEN CARD card lost or stolen
3103 3DSECURE AUTH FAILED 3d secure authentication failed
3104 INVALID CVV invalid CVV
3105 CARD EXPIRED card expired due to expiry date or expiry date is not correct
3106 INVALID AMOUNT bank cannot process selected amount
3107 INVALID CARD NUMBER card number was declined by bank
3108 REFUND LIMIT EXCEEDED it is not possible to issue refund due to bank limit
3109 TIMEOUT timeout between PSP and bank
3110 BANK REQUIRED FIELDS ARE MISSING OR INCORRECT not all required data was provided to the specific bank
3111 BANK ACCESS ERROR access error to a bank asquirer
3112 BANK CARD TYPE NOT SUPPORTED card type is not supported by MID
3113 BANK TRANSACTION TYPE NOT SUPPORTED transaction type is not supported by MID
3114 BANK CURRENCY NOT SUPPORTED currency is not supported by MID
3115 REFUND NOT POSSIBLE DO VOID order should be be voided due it was not settled
3116 COUNTRY NOT SUPPORTED country is not supported by MID
3117 MALFORMED BANK RESPONSE malformed bank response
3118 BANK_CONNECTION_ERROR bank connection error
3119 REFERAL OR RESTRICTED CARD Referal or restricted card
3120 RISK BANK DECLINE Risk Bank Decline
3121 INVALID ACQUIRER TOKEN acquirer token is invalid
3122 INVALID ACQUIRER REFERENCE acquirer reference is invalid
3123 ACQUIRER 3D SECURE NOT ENABLED acquirer 3D secure is not enabled
3124 UNKNOWN ACQUIRER PROCESSING STATUS unknown acquirer processing status
3125 ACQUIRER INTERNAL ERROR acquirer internal error
3126 WITHDRAWAL FREQUENCY LIMIT EXCEEDED withdrawal frequency limit exceeded
3127 BANK NEGATIVE LIST bank negative list
3128 FRAUD BANK DECLINE fraud decline by bank
3129 AUTHORIZATION DECLINED authorization decline
ANTIFRAUD 3200 GENERAL FRAUD DECLINE Declined by anti-fraud system
3201 GENERAL MANUAL REVIEW Sent for manual review by anti-fraud system
3220 TRUST LIST FRAUD DECLINE [Field] in black list
3221 TRUST LIST MANUAL REVIEW [Field] in watch list
FRS 4000 GENERAL RECONCILLIATION ERROR general reconcilliation error
4001 RECONCILLIATION INCOMPLETE reconcilliation incomplete
4002 RECONCILLIATION AMOUNT MISMATCH reconcilliation amount mismatch
4003 RECONCILLIATION COUNT MISMATCH reconcilliation count mismatch
4004 GENERAL FRS ERROR FRS general error
QOD 5000 QOD GENERAL ERROR QOD general error
5001 QOD UNSUPPORTED API VERSION unsupported API version of QOD
5002 INVALID TIME ORDER time order is invalid
AUTH 6000 INTERNAL AUTH FAILURE general internal auth failure
6001 WRONG CREDENTIALS Wrong credentials
6002 ACCESS DENIED Access denied
6003 ALREADY EXISTS The user already exists
6004 USER NOT FOUND The user is not found
6005 ROLE NOT FOUND The role is not found
6006 PERMISSION NOT FOUND The permission is not found
6007 EXPIRED TOKEN The token is expired
6008 TOKEN NOT FOUND The token is not found
6009 USER TEMPORARY BLOCKED The user is temporary blocked
6010 EXPIRED PASSWORD The password is expired
6011 INVALID PASSWORD The password is invalid
6012 PREVIOUSLY USED PASSWORD The password is previously used
7000 INTERNAL PAYMENT GATE ERROR Internal payment gate error
7101 INTERNAL PAYMENT GATE SENDER ERROR Internal payment gate sender error
7102 COMMUNICATION ERROR External communication error
7103 COMMUNICATION TIMEOUT External communication timeout