General Technical Details

All the requests regarding GrataPay API should be sent to:

https://gratapay.com/api

All the requests should contain the Auth header with an authorization key that will be sent to Merchant, e.g.:

POST /deposit/create HTTP/1.1
Host: gratapay.com
Accept: application/json
Content-Type: application/json
Auth: fcd8766d4fa5b4a5c7198b87a5d0921d
                    

GrataPay API deals with JSON requests.

All the requests, excluding GET, should be signed by a secret key that will be also sent to Merchant. For signing you need to deliver the md5 hash from a request body with a secret a key concatenating. Then the delivered hash is used in the Sign header and sent together with the request.

The example of the hash calculation in PHP:

$secret_key = '1dfcd12ba13fff487a84cf50d8099297';
$request = '{"test":"test"}';
$sign = md5($request . $secret_key);
//49e8dde596382693c52ccc3d722e5229
                    

POST request will be written as:

POST /deposit/create HTTP/1.1
Host: gratapay.com
Accept: application/json
Content-Type: application/json
Auth: fcd8766d4fa5b4a5c7198b87a5d0921d
Sign: 49e8dde596382693c52ccc3d722e5229
…
{"test":"test"}
                    

Whereas GrataPay sends the requests to the Merchant system using the same rules and keys.

Payment Process

Please see below the scheme of the payment through Payment System by means of GrataPay API:

Client
Merchant
GrataPay
Payment system
Order creating and data entering
Creating and sending a deposit/create request
Request sending to the Payment system
Sending redirect parameters
Response to the request with GrataPay transaction data and redirect parameters
User redirecting to payment page, data entering for payment
User redirecting to Merchant site
User notification
Awaiting GrataPay notification
Sending a payment status notification
Sending a payment status Notification with transaction data
User notification, account crediting
Client
Merchant
GrataPay
Payment system

A maximally general case is analyzed in this scheme. In different systems the schemes can differentiate. The information is thoroughly described in the section below.

In certain cases Merchant can charge fee from its Clients, in which case GrataPay system can reckon on it on its side and provide total amounts in the responses to the deposit/create, deduce/create requests, as well as return them by the notifications. For the purpose Merchant needs to provide the policies of fee accounting.

Merchant can also pay fee for its Client.

All the cases will be reviewed after the Section of Requests and Responses.

Request for payment transaction creating /deposit/create

The request is sent by POST to the address:

https://gratapay.com/api/deposit/create

The request format is as follows:

FieldTypeMandatoryDescriptionExample
amountfloat(10,2)YesTransaction amount.10.00
currencystring(3)YesTransaction currency.RUB
payment_systemstringYesPayment system name.CardGate
transaction_idstringNoTransaction number in the Merchant system.123
notestringNoTransaction description for the Merchant.Account deposit 321
system_fieldsobjectNoContainer for additional fields of payment system.
urlobjectNoContainer for URL addresses transmitting.
url > callback_urlurlNoURL for transmitting notification of a payment to the Merchant system.http://site.com/callback
url > fail_urlurlNoURL for user redirecting to the Merchant page in case of failure.http://site.com/fail
url > pending_urlurlNoURL for user redirecting to the Merchant page in case of transaction nonfinal status.http://site.com/pending
url > success_urlurlNoURL for user redirecting to the Merchant page in case of success.http://site.com/success

The example of the request:

{
    "transaction_id": "123",
    "amount": "10.00",
    "currency": "RUB",
    "payment_system": "CardGate",
    "url": {
        "callback_url": "https://site.com/callback",
        "fail_url": "https://site.com/fail",
        "pending_url": "https://site.com/pending",
        "success_url": "https://site.com/success"
    }
}
                    

Response of GrataPay:

FieldTypeMandatoryDescriptionExample
statusstringYesTransaction status 'created' in the case of success, 'error' if an error arose.created
idintegerYes (success)Transaction number in GrataPay system.300
transaction_idstringNo (success)Transaction number in the Merchant system, if it was transmitted in the request.123
typestringYes (success)Transaction type: 'deposit' – top-up.deposit
amount_to_payfloat(10,2)Yes (success)The amount, required to be paid to the Client.10.00
amount_merchantfloat(10,2)Yes (success)The amount that will be credited to the Merchant account (less payment system fee).9.30 (with a fee, e.g.7%)
amount_clientfloat(10,2)Yes (success)*deprecated*10.00
currencystring(3)Yes (success)Transaction currency.RUB
payment_systemstringYes (success)Payment system name.CardGate
redirectobjectYes (success)Container with parameters of redirect.
redirect > urlurlYes (success)URL for the request sending.https://gratapay.com/
redirect > methodstringYes (success)The request method.GET
redirect > paramsobjectYes (success)Container with the request parameters. All the parameters in the container need to be sent together with the request.
codeintegerYes (fail)Error code, list of codes and their description are in the table below.500
messagestringYes (fail)Text description of an error.Internal server error
descriptionstringNo (fail)Additional error description, if it is not on GrataPay side.Do not honor

The example of successful GrataPay response:

{
    "status": "created",
    "id": "300",
    "transaction_id": "123",
    "type": "deposit",
    "amount_to_pay": "10.00",
    "amount_merchant": "9.30",
    "amount_client": "10.00",
    "currency": "RUB",
    "payment_system": "CardGate",
    "redirect": {
        "url": "https://gratapay.com/payment/checkout",
        "method": "GET",
        "params": {
            "data": "12345678"
        }
    }
}
                    

The example of unsuccessful GrataPay response:

{
    "status": "error",
    "code": "201",
    "message": "Mandatory field `amount` is not present"
}
                    

Payout Process

Please see below the scheme of the payout through Payment System by means of GrataPay API:

Client
Merchant
GrataPay
Payment system
Order creating and data entering
Creating and sending a deduce/create request
Request sending to the Payment system
Sending result response
Response to the request with GrataPay transaction data and status
User notification
Awaiting status change
Status request sending to the Payment system
Receiving response
Awaiting GrataPay notification
Sending a payment status Notification with transaction data
User notification
Client
Merchant
GrataPay
Payment system

A maximally general case is analyzed in this scheme. In different systems the schemes can differentiate. The information is thoroughly described in the section below.

The payout process is asynchronous. The Merchant creates a transaction with /deduce/create method. If transaction is created successfully then the Merchant should await for notification or send status requests.

Request for payout transaction creating /deduce/create

The request is sent by POST to the address:

https://gratapay.com/api/deduce/create

The request format is as follows:

FieldTypeMandatoryDescriptionExample
amountfloat(10,2)YesTransaction amount.10.00
currencystring(3)YesTransaction currency.RUB
payment_systemstringYesPayment system name.Card
transaction_idstringYesTransaction number in the Merchant system.123
notestringNoTransaction description for the Merchant.Account deposit 321
system_fieldsobjectYesContainer for additional fields of payment system.
urlobjectNoContainer for URL addresses transmitting.
url > callback_urlurlNoURL for transmitting notification of a payout to the Merchant system.http://site.com/callback
url > reversal_urlurlNoURL for transmitting notification of a successful payout that had been reversed.http://site.com/callback

The transaction_id parameter must be unique. In case of repeated ID GrataPay system will answer with 306 error code. This does not mean that transaction in not successful! We suggest to check transaction status after receiving this kind of response.

In some cases payment system can cancel payout transaction after it became successful. For this case reversal_url is used. GrataPay send common notification request to reversal_url with transaction status 'error' and 'Declined: reversal' message.

The example of the request:

{
    "transaction_id": "123",
    "amount": "10.00",
    "currency": "RUB",
    "payment_system": "Card",
    "system_fields": {
        "card_number": "4111111111111111",
        "client_phone": "+79008007000",
        "payment_description": "Account deposit 321"
    },
    "url": {
        "callback_url": "https://site.com/callback",
        "reversal_url": "https://site.com/reversal"
    }
}
                    

Response of GrataPay:

FieldTypeMandatoryDescriptionExample
statusstringYesTransaction status 'created' in the case of success, 'error' if an error arose.created
idintegerYes (success)Transaction number in GrataPay system.300
transaction_idstringNo (success)Transaction number in the Merchant system, if it was transmitted in the request.123
typestringYes (success)Transaction type: 'deduce' – payout.deposit
amount_to_payfloat(10,2)Yes (success)The amount, required to be paid to the Client.10.00
amount_merchantfloat(10,2)Yes (success)The amount withdrawn from the Merchant account.10.70 (with a fee, e.g.7%)
amount_clientfloat(10,2)Yes (success)*deprecated*10.00
currencystring(3)Yes (success)Transaction currencyRUB
payment_systemstringYes (success)Payment system name.CardGate
createdintegerYes (success)Timestamp of the creation date and time.1510000000

The example of successful GrataPay response:

{
    "status": "created",
    "id": "300",
    "transaction_id": "123",
    "type": "deposit",
    "amount_to_pay": "10.00",
    "amount_merchant": "10.70",
    "amount_client": "10.00",
    "currency": "RUB",
    "payment_system": "Card",
    "created": 1510000000
}
                    

The example of unsuccessful GrataPay response:

{
    "status": "error",
    "code": "305",
    "message": "Insufficient balance"
}
                    

Refunds

Refunds can only be made if next conditions are met:

  • Payment method supports refunds (you can specify it with your manager).
  • Transaction type is deposit and its status is success.
  • Merchant balance is greater of equal refund amount.
  • Sum of all refunds on specific transaction is less or equal the transaction amount.

The request is sent by POST to the address:

https://gratapay.com/api/refund/create

The request format is as follows:

FieldTypeMandatoryDescriptionExample
amountfloat(10,2)YesRefund amount.10.00
currencystring(3)YesTransaction currency.RUB
original_transaction_idintegerYesGrataPay ID of the original transaction.300
transaction_idstringNoTransaction number in the Merchant system.123
notestringNoTransaction description for the Merchant.Account deposit 321
urlobjectNoContainer for URL addresses transmitting.
url > callback_urlurlNoURL for transmitting notification of a refund to the Merchant system.http://site.com/callback

The example of the request:

{
    "amount": "10.00",
    "currency": "RUB",
    "original_transaction_id": "300",
    "transaction_id": "123",
    "url": {
        "callback_url": "https://site.com/callback"
    }
}
                    

Response of GrataPay:

FieldTypeMandatoryDescriptionExample
statusstringYesTransaction status 'ok' in the case of success, 'created' in case of non-final status, 'error' if an error arose.created
idintegerYes (success)Transaction number in GrataPay system.301
transaction_idstringNo (success)Transaction number in the Merchant system, if it was transmitted in the request.123
typestringYes (success)Transaction type.refund
amount_to_payfloat(10,2)Yes (success)The amount, to be refunded to the Client.10.00
amount_merchantfloat(10,2)Yes (success)The amount withdrawn from the Merchant account.10.70 (with a fee, e.g.7%)
amount_clientfloat(10,2)Yes (success)*deprecated*10.00
currencystring(3)Yes (success)Transaction currencyRUB
payment_systemstringYes (success)Payment system name.CardGate
createdintegerYes (success)Timestamp of the creation date and time.1510000000
codeintegerYes (fail)Error code, list of codes and their description are in the table below.500
messagestringYes (fail)Text description of an error.Internal server error
descriptionstringNo (fail)Text description of an error.Additional error description, if it is not on GrataPay side.

The example of successful GrataPay responses:

{
    "status": "ok",
    "id": "301",
    "transaction_id": "123",
    "type": "refund",
    "amount_to_pay": "10.00",
    "amount_merchant": "10.70",
    "amount_client": "10.00",
    "currency": "RUB",
    "payment_system": "CardGate",
    "created": 1510000000
}
                    

The example of successful GrataPay response:

{
    "status": "created",
    "id": "301",
    "transaction_id": "123",
    "type": "refund",
    "amount_to_pay": "10.00",
    "amount_merchant": "10.70",
    "amount_client": "10.00",
    "currency": "RUB",
    "payment_system": "CardGate",
    "created": 1510000000
}
                    

The example of unsuccessful GrataPay response:

{
    "status": "error",
    "code": "305",
    "message": "Insufficient balance"
}
                    

Transaction Status Notification

Notification is sent if the Merchant specifies the corresponding URL in the deposit/create or deduce/create request in case of transaction status changing. The request has headers Auth and Sign, signature and authorization should be checked, the merchant keys are used. The request is written as follows:

Notification example:

{
    "id": "300",
    "status": "ok",
    "type": "deposit",
    "transaction_id": "123",
    "amount_payed": "10.00",
    "amount_merchant": "9.30",
    "amount_client": "10.00",
    "currency": "RUB",
    "payment_system": "CardGate",
    "system_fields": {
        "card_number": "411111******1111"
    }
}
                    

The system will make efforts to send the notification no more than 20 times. The interval between efforts will grow each time.

The system concludes the successful notification delivering, if the response with code 200 and body:

{
    "answer": "ok"
}
                    

Transaction Status Request

The Merchant System can request transaction status without waiting for notification delivering. For this purpose it is required to send GET request with Auth heading to the address:

https://gratapay.com/api/status/{ID}, in which {ID} is replaced by a transaction number in GrataPay system, for example: https://gratapay.com/api/status/300.

There is also a way to request transaction status by Transaction number in Merchant system. For this case it is required to send GET request with Auth heading to the address:

https://gratapay.com/api/status/merchant?id={MERCHANT_ID}&date={APPROX_DATE}, in which {MERCHANT_ID} is replaced by a transaction number in Merchant system and {APPROX_DATE} by approximate date of the transaction creation (in format: 2020-12-30). {APPROX_DATE} is non mandatory parameter, but it used for speeding up the search. Transaction will be searched for ±3 days from {APPROX_DATE}

The response format:

FieldTypeMandatoryDescriptionExample
idintegerYesTransaction number in system.300
statusstringYesTransaction status: 'ok' – successful, 'pending' – has non final status, 'cancel' – canceled, 'error' – an error has occurred.ok
typestringYesTransaction type: 'deposit', 'deduce'.deposit
transaction_idstringNoTransaction number in Merchant system.123
amount_payedfloat(10,2)YesIn case of deposit — the amount paid by a Client. In case of withdrawal – the amount paid to a Client.10.00
amount_merchantfloat(10,2)YesIn case of deposit – the amount credited to the Merchant account. In case of withdrawal – the amount withdrawn from the Merchant account.9.30
amount_clientfloat(10,2)Yes*deprecated*10.00
currencystring(3)YesTransaction currency.RUB
payment_systemstringYesName of Payment system to which the Transaction belongs.CardGate
createdintegerYesTransaction creation time.1500000000
updatedintegerYesTime of the last status change.1510000000
messagestringNoError description in case of failure.operation_time_out
system_fieldsobjectNoContainer with additional fields (availability and content depend on a payment system).

The example of response to the request: https://gratapay.com/api/status/300:

{
    "id": "300",
    "status": "ok",
    "type": "deposit",
    "transaction_id": "123",
    "amount_to_pay": "10.00",
    "amount_merchant": "9.30",
    "amount_client": "10.00",
    "currency": "RUB",
    "payment_system": "CardGate",
    "created": 1500000000,
    "updated": 1510000000,
    "system_fields": {
        "card_number": "411111******1111"
    }
}
                    

Balance request

The Merchant System can request remaining balance. For this purpose it is required to send GET request with Auth heading to the address: https://gratapay.com/api/balance

Response of GrataPay:

FieldTypeMandatoryDescriptionExample
statusstringYesTransaction status: 'ok' – successful, 'error' – an error has occurred.ok
balancesstringYes (success)Container for balance by different type of payment system
balances > payment systemfloat(10,2)Yes (success)Available payment system for Merchant system. Instead of `payment system` it will be placed all available balance on payment system type.TestCard
payment system > currencyfloat(10,2)No (success)Remaining balance by currency. At field `currency` it will be placed all available currencies for Merchant.4973.00
codeintegerYes (fail)Error code, list of codes and their description are in the table below.103
messageintegerYes (fail)Error description.Header `Auth` is not set or empty

The example of successful response to the request https://gratapay.com/api/balance:

{
    "status": "ok",
    "balances": {
        "TestCard": {
            "RUB": "4973.00"
        }
    }
}
                    

The example of unsuccessful GrataPay response to the request:

{
    "status": "error",
    "code": "103",
    "message": "Header `Auth` is not set or empty"
}
                    

Errors arising in operating with the system

The list of all possible errors is presented in the following table:

CodeDescription
1XXAuthorization error, request format error
101Merchant is not found
102Wrong request signature
103The required request header is not found
104Wrong request format / JSON is not correctly structured
105IP is not whitelisted
2XXRequest content errors
201Mandatory field is not found
202Payment system is not found or not available
203Payment system does not support the transaction type (deposit or withdrawal)
3XXData validation errors
301Wrong field format
302Transaction is not found
303Amount is less than 0 after fee calculating
304User is not found
305Insufficient balance
306Transaction with number transaction_id is already exist
307Antifraud validation check failed
308Recurring data is not found
309Transaction has wrong status
4XXPayment system errors
401Error on the side of Payment system, more detailed information will be specified in the field “message”.
5XXGrataPay server errors
501Error on the side of GrataPay server, more detailed information will be specified in the field “message”.

Testing

Supported currencies: RUB, EUR, USD.

Any other currencies will be converted into RUB.

For successful payment you need to use card with number:

4111 1111 1111 1111

Any other card numbers will initiate an error.

Use "payment_system": "CardGateTest" for testing card acquiring.

Use "payment_system": "CardGateTestS2S" for testing server-to-server integration.

Use "payment_system": "TestCard" for testing card payout.