For developers

  1. Main page
  2. For developers

General Technical Details

All the requests regarding Royal Pay API should be sent to:

https://cards.royalpay.eu/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: cards.royalpay.eu
Accept: application/json
Content-Type: application/json
Auth: fcd8766d4fa5b4a5c7198b87a5d0921d

Royal Pay 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: cards.royalpay.eu
Accept: application/json
Content-Type: application/json
Auth: fcd8766d4fa5b4a5c7198b87a5d0921d
Sign: 49e8dde596382693c52ccc3d722e5229
…
{"test":"test"}

Whereas Royal Pay 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 Royal Pay API:

Client
Merchant
Royal Pay
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 Royal Pay transaction data and redirect parameters
User redirecting to payment page, data entering for payment
User redirecting to Merchant site
User notification
Awaiting Royal Pay notification
Sending a payment status notification
Sending a payment status Notification with transaction data
User notification, account crediting
Client
Merchant
Royal Pay
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 Royal Pay 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://cards.royalpay.eu/api/deposit/create

The request format is as follows:

Field
Type
Mandatory
Description
Example
Field
amount
Type
float(10,2)
Mandatory
Yes
Description
Transaction amount.
Example
10.00
Field
currency
Type
string(3)
Mandatory
Yes
Description
Transaction currency.
Example
RUB
Field
payment_system
Type
string
Mandatory
Yes
Description
Payment system name.
Example
CardGate
Field
transaction_id
Type
string
Mandatory
No
Description
Transaction number in the Merchant system.
Example
123
Field
note
Type
string
Mandatory
No
Description
Transaction description for the Merchant.
Example
Account deposit 321
Field
system_fields
Type
object
Mandatory
No
Description
Container for additional fields of payment system.
Example
Field
url
Type
object
Mandatory
No
Description
Container for URL addresses transmitting.
Example
Field
url > callback_url
Type
url
Mandatory
No
Description
URL for transmitting notification of a payment to the Merchant system.
Example
http://site.com/callback
Field
url > fail_url
Type
url
Mandatory
No
Description
URL for user redirecting to the Merchant page in case of failure.
Example
http://site.com/fail
Field
url > pending_url
Type
url
Mandatory
No
Description
URL for user redirecting to the Merchant page in case of transaction nonfinal status.
Example
http://site.com/pending
Field
url > success_url
Type
url
Mandatory
No
Description
URL for user redirecting to the Merchant page in case of success.
Example
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 Royal Pay:

Field
Type
Mandatory
Description
Example
Field
status
Type
string
Mandatory
Yes
Description
Transaction status 'created' in the case of success, 'error' if an error arose.
Example
created
Field
id
Type
integer
Mandatory
Yes (success)
Description
Transaction number in Royal Pay system.
Example
300
Field
transaction_id
Type
string
Mandatory
No (success)
Description
Transaction number in the Merchant system, if it was transmitted in the request.
Example
123
Field
type
Type
string
Mandatory
Yes (success)
Description
Transaction type: 'deposit' – top-up.
Example
deposit
Field
amount_to_pay
Type
float(10,2)
Mandatory
Yes (success)
Description
The amount, required to be paid to the Client.
Example
10.00
Field
amount_merchant
Type
float(10,2)
Mandatory
Yes (success)
Description
The amount that will be credited to the Merchant account (less payment system fee).
Example
9.30 (with a fee, e.g.7%)
Field
amount_client
Type
float(10,2)
Mandatory
Yes (success)
Description
The amount that need to be credited to the client account.
Example
9.20 (with a Merchant fee 1%)
Field
currency
Type
string(3)
Mandatory
Yes (success)
Description
Transaction currency.
Example
RUB
Field
payment_system
Type
string
Mandatory
Yes (success)
Description
Payment system name.
Example
CardGate
Field
redirect
Type
object
Mandatory
Yes (success)
Description
Container with parameters of redirect.
Example
Field
redirect > url
Type
url
Mandatory
Yes (success)
Description
URL for the request sending.
Example
https://cards.royalpay.eu/
Field
redirect > method
Type
string
Mandatory
Yes (success)
Description
The request method.
Example
GET
Field
redirect > params
Type
object
Mandatory
Yes (success)
Description
Container with the request parameters. All the parameters in the container need to be sent together with the request.
Example
Field
code
Type
integer
Mandatory
Yes (fail)
Description
Error code, list of codes and their description are in the table below.
Example
500
Field
message
Type
string
Mandatory
Yes (fail)
Description
Text description of an error.
Example
Internal server error
Field
description
Type
string
Mandatory
No (fail)
Description
Additional error description, if it is not on Royal Pay side.
Example
Do not honor

The example of successful Royal Pay response:

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

The above mentioned example demonstrates the case when Merchant does not charge fee from a Client (or counts it on its side), as well as does not pay fee for a Client, Royal Pay fee – 7%. In the event that Merchant pays fee for a Client, the amounts will be shared as follows:

{
    "amount_to_pay": "10.00",
    "amount_merchant": "9.30",
    "amount_client": "10.00"
}

If Merchant charges additional fee (e.g. 1%) from a Client and Royal Pay counts fee, the amounts will be:

{
    "amount_to_pay": "10.00",
    "amount_merchant": "9.30",
    "amount_client": "9.20"
}

The example of unsuccessful Royal Pay 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 Royal Pay API:

Client
Merchant
Royal Pay
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 Royal Pay transaction data and status
User notification
Awaiting status change
Status request sending to the Payment system
Receiving response
Awaiting Royal Pay notification
Sending a payment status Notification with transaction data
User notification
Client
Merchant
Royal Pay
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://cards.royalpay.eu/api/deduce/create

The request format is as follows:

Field
Type
Mandatory
Description
Example
Field
amount
Type
float(10,2)
Mandatory
Yes
Description
Transaction amount.
Example
10.00
Field
currency
Type
string(3)
Mandatory
Yes
Description
Transaction currency.
Example
RUB
Field
payment_system
Type
string
Mandatory
Yes
Description
Payment system name.
Example
Card
Field
transaction_id
Type
string
Mandatory
Yes
Description
Transaction number in the Merchant system.
Example
123
Field
note
Type
string
Mandatory
No
Description
Transaction description for the Merchant.
Example
Account deposit 321
Field
system_fields
Type
object
Mandatory
Yes
Description
Container for additional fields of payment system.
Example
Field
url
Type
object
Mandatory
No
Description
Container for URL addresses transmitting.
Example
Field
url > callback_url
Type
url
Mandatory
No
Description
URL for transmitting notification of a payout to the Merchant system.
Example
http://site.com/callback
Field
url > reversal_url
Type
url
Mandatory
No
Description
URL for transmitting notification of a successful payout that had been reversed.
Example
http://site.com/callback

The transaction_id parameter must be unique. In case of repeated ID Royal Pay 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. Royal Pay 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 Royal Pay:

Field
Type
Mandatory
Description
Example
Field
status
Type
string
Mandatory
Yes
Description
Transaction status 'created' in the case of success, 'error' if an error arose.
Example
created
Field
id
Type
integer
Mandatory
Yes (success)
Description
Transaction number in Royal Pay system.
Example
300
Field
transaction_id
Type
string
Mandatory
No (success)
Description
Transaction number in the Merchant system, if it was transmitted in the request.
Example
123
Field
type
Type
string
Mandatory
Yes (success)
Description
Transaction type: 'deduce' – payout.
Example
deposit
Field
amount_to_pay
Type
float(10,2)
Mandatory
Yes (success)
Description
The amount, required to be paid to the Client.
Example
10.00
Field
amount_merchant
Type
float(10,2)
Mandatory
Yes (success)
Description
The amount withdrawn from the Merchant account.
Example
10.70 (with a fee, e.g.7%)
Field
amount_client
Type
float(10,2)
Mandatory
Yes (success)
Description
The amount should withdrawn from the client account.
Example
10.80 (with a Merchant fee 1%)
Field
currency
Type
string(3)
Mandatory
Yes (success)
Description
Transaction currency
Example
RUB
Field
payment_system
Type
string
Mandatory
Yes (success)
Description
Payment system name.
Example
CardGate
Field
created
Type
integer
Mandatory
Yes (success)
Description
Timestamp of the creation date and time.
Example
1510000000

The example of successful Royal Pay response:

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

The example of unsuccessful Royal Pay 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://cards.royalpay.eu/api/refund/create

The request format is as follows:

Field
Type
Mandatory
Description
Example
Field
amount
Type
float(10,2)
Mandatory
Yes
Description
Refund amount.
Example
10.00
Field
currency
Type
string(3)
Mandatory
Yes
Description
Transaction currency.
Example
RUB
Field
original_transaction_id
Type
integer
Mandatory
Yes
Description
Royal Pay ID of the original transaction.
Example
300
Field
transaction_id
Type
string
Mandatory
No
Description
Transaction number in the Merchant system.
Example
123
Field
note
Type
string
Mandatory
No
Description
Transaction description for the Merchant.
Example
Account deposit 321
Field
url
Type
object
Mandatory
No
Description
Container for URL addresses transmitting.
Example
Field
url > callback_url
Type
url
Mandatory
No
Description
URL for transmitting notification of a refund to the Merchant system.
Example
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 Royal Pay:

Field
Type
Mandatory
Description
Example
Field
status
Type
string
Mandatory
Yes
Description
Transaction status 'ok' in the case of success, 'created' in case of non-final status, 'error' if an error arose.
Example
created
Field
id
Type
integer
Mandatory
Yes (success)
Description
Transaction number in Royal Pay system.
Example
301
Field
transaction_id
Type
string
Mandatory
No (success)
Description
Transaction number in the Merchant system, if it was transmitted in the request.
Example
123
Field
type
Type
string
Mandatory
Yes (success)
Description
Transaction type.
Example
refund
Field
amount_to_pay
Type
float(10,2)
Mandatory
Yes (success)
Description
The amount, to be refunded to the Client.
Example
10.00
Field
amount_merchant
Type
float(10,2)
Mandatory
Yes (success)
Description
The amount withdrawn from the Merchant account.
Example
10.70 (with a fee, e.g.7%)
Field
amount_client
Type
float(10,2)
Mandatory
Yes (success)
Description
The amount should withdrawn from the client account.
Example
10.80 (with a Merchant fee 1%)
Field
currency
Type
string(3)
Mandatory
Yes (success)
Description
Transaction currency
Example
RUB
Field
payment_system
Type
string
Mandatory
Yes (success)
Description
Payment system name.
Example
CardGate
Field
created
Type
integer
Mandatory
Yes (success)
Description
Timestamp of the creation date and time.
Example
1510000000
Field
code
Type
integer
Mandatory
Yes (fail)
Description
Error code, list of codes and their description are in the table below.
Example
500
Field
message
Type
string
Mandatory
Yes (fail)
Description
Text description of an error.
Example
Internal server error
Field
description
Type
string
Mandatory
No (fail)
Description
Additional error description, if it is not on Royal Pay side.
Example
Connection problem

The example of successful Royal Pay responses:

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

The example of unsuccessful Royal Pay 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": "9.20",
    "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://cards.royalpay.eu/api/status/{ID}, in which {ID} is replaced by a transaction number in Royal Pay system, for example: https://cards.royalpay.eu/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://cards.royalpay.eu/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:

Field
Type
Mandatory
Description
Example
Field
id
Type
integer
Mandatory
Yes
Description
Transaction number in system.
Example
300
Field
status
Type
string
Mandatory
Yes
Description
Transaction status: 'ok' – successful, 'pending' – has non final status, 'cancel' – canceled, 'error' – an error has occured.
Example
ok
Field
type
Type
string
Mandatory
Yes
Description
Transaction type: 'deposit', 'deduce'.
Example
deposit
Field
transaction_id
Type
string
Mandatory
No
Description
Transaction number in Merchant system.
Example
123
Field
amount_payed
Type
float(10,2)
Mandatory
Yes
Description
In case of deposit — the amount paid by a Client. In case of withdrawal – the amount paid to a Client.
Example
10.00
Field
amount_merchant
Type
float(10,2)
Mandatory
Yes
Description
In case of deposit – the amount credited to the Merchant account. In case of withdrawal – the amount withdrawn from the Merchant account.
Example
9.30
Field
amount_client
Type
float(10,2)
Mandatory
Yes
Description
In case of deposit— the amount that needs to be deposited to the Client Account. In case of withdrawal – the amount that needs to be withdrawn from a Client account.
Example
9.20
Field
currency
Type
string(3)
Mandatory
Yes
Description
Transaction currency.
Example
RUB
Field
payment_system
Type
string
Mandatory
Yes
Description
Name of Payment system to which the Transaction belongs.
Example
CardGate
Field
created
Type
integer
Mandatory
Yes
Description
Transaction creation time.
Example
1500000000
Field
updated
Type
integer
Mandatory
Yes
Description
Time of the last status change.
Example
1510000000
Field
description
Type
string
Mandatory
No
Description
Error description in case of failure.
Example
operation_time_out
Field
system_fields
Type
object
Mandatory
No
Description
Container with additional fields (availability and content depend on a payment system).
Example

The example of response to the request: https://cards.royalpay.eu/api/status/300:

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

Balance request

The Mechant System can request remaining balance. For this purpose it is required to send GET request with Auth heading to the address: https://cards.royalpay.eu/api/balance

Response of Royal Pay:

Field
Type
Mandatory
Description
Example
Field
status
Type
string
Mandatory
Yes
Description
Transaction status: 'ok' – successful, 'error' – an error has occured.
Example
ok
Field
balances
Type
string
Mandatory
Yes(success)
Description
Container for balance by different type of payment system
Example
Field
balances > payment system
Type
float(10,2)
Mandatory
Yes(success)
Description
Available payment system for Merchant system.
Instead of `payment system` it will be placed all available balance on payment system type.
Example
TestCard
Field
payment system > currency
Type
float(10,2)
Mandatory
No(success)
Description
Remaining balance by currency.
At field `currency` it will be placed all available currencies for Merchant.
Example
4973.00
Field
code
Type
integer
Mandatory
Yes(fail)
Description
Error code, list of codes and their description are in the table below.
Example
103
Field
message
Type
integer
Mandatory
Yes(fail)
Description
Error description.
Example
Header `Auth` is
not set or empty

The example of successful response to the request: https://cards.royalpay.eu/api/balance:

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

The example of unsuccessful Royal Pay 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:

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