NAV Navbar

For any question, we are one click away

Contact us

Sandbox

Use Sandbox to try API

REST API reference

You can download Postman collection of API requests to test some basic eCommerce functions.

Download Postman collection

Order registration

To register an order, use register.do request.

Request parameters

Mandatory Name Type Description
See description

userName String Merchant 's API account login. If you pass your login and password to authenticate in the payment gateway, do not pass token parameter.
See description

password String Merchant's API account password. If you pass your login and password to authenticate in the payment gateway, do not pass token parameter.
See description

token String Value that is used for merchant authentication when requests are sent to the payment gateway. If you pass this parameter do not pass userName and password.
See description

orderNumber Alphanumeric Order number (ID) in the merchant's system, must be unique for each merchant.
Yes

amount Integer Payment amount in minor currency units (e.g. in cents etc.).
No

currency Integer SO 4217 encoded currency key. If not specified, the default value is used.
Yes

returnUrl String The address to which the user will be redirected if the payment is successful. The address must be specified in full including the protocol used (for example, https://test.ru instead of test.ru). Otherwise, the user will be redirected to the address of the following type http://<payment_gateway_address>/<merchant_address>.
No

failUrl String The address to which the user is to be redirected in case of a failed payment. The address must be specified in full including the protocol used (for example, https://test.ru instead of test.ru). Otherwise, the user will be redirected to the address of the following type http://<payment_gateway_address>/<merchant_address>.
No

dynamicCallbackUrl String This parameter allows you to use the functionality of sending callback notifications dynamically. Here you can pass the address to which all "payment" callback notifications, activated for the merchant, will be sent. "Payment" notifications are callback notifications related to the following events: successful hold, payment declined by timeout, cardpresent payment is declined, successful debit, refund, cancellation. At the same time, callback notifications activated for the merchant that are not related to payments (enabling/disabling a binding, creating a binding) will be sent to a static address for callbacks. Mandatory use depends on the merchant configuration on Payment Gateway side.
No

description String Order description in any format.
To enable sending this field to the processing system, contact the technical support service.
No

language Alphabetic ISO 639-1 encoded language key. If the language is not specified, the default language specified in the store settings is used.
No

pageView String By the value of this parameter, it is defined what pages of the payment interface are to be loaded for the customer. The following values are allowed.
  • DESKTOP – for loading pages for PC (in the archive that contains pages of the payment interface the following pages will be searched: payment_<locale>.html and errors_<locale>.html).
  • MOBILE – for loading pages for mobile devices (in the archive that contains pages of the payment interface the following pages will be searched: mobile_payment_<locale>.html and mobile_errors_<locale>.html).
  • If a merchant created payment pages and added their own prefixes, pass the created prefixes in pageView parameter to load the corresponding page. For example, when passing iphone value, pages with iphone_payment_<locale>.html and iphone_error_<locale>.htm will be searched

Where:
  • locale is the ISO 639-1 language key. For example, ru for Russian or en for English.

If this parameter is missing or does not match the format, it is considered that by default pageView=DESKTOP.
No

clientId Alphanumeric Customer number (ID) in the merchant's system — up to 255 characters . Used to implement the functionality of bindings. Can be returned in the response if the merchant is allowed to create bindings.
Specifying this parameter when processing payments via bindings is mandatory. Otherwise, a payment will be unsuccessful.
No

merchantLogin String To register an order on behalf of a child merchant, specify the merchant login in this parameter.
No

jsonParams String Block for passing additional merchant parameters. Fields containing additional info for further storage are pased as follows.
{name1:value1,…,nameN:valueN}
These fields can be transferred to the processing bank for further display in the bank registers.
Contact your bank to enable this functionality.
If customer notifications are configured for the merchant, then, customer's email must be passed in this block in the email parameter.
By default, the followng parameters are passed to the processing bank:
  • orderNumber – order number in the merchant's system;
  • description – order description (up to 99 characters, the following characters are forbidden^ %, +, end of line \r, and line break \n).

If you pass merchantOrderId parameter, then, its value will be passed to the processing bank as order number (instead of orderNumber parameter).
No

sessionTimeoutSecs Integer Order lifetime in seconds. If the parameter is not specified, the value specified in the merchant settings or the default value (1200 seconds = 20 minutes) will be used. If the request contains expirationDate, the value of sessionTimeoutSecs is not taken into account.
No

expirationDate String Data and time of the order expiry. Format used: yyyy-MM-ddTHH:mm:ss.
If this parameter is not passed in the request, sessionTimeoutSecs is used to define the expiry of the order.
No

bindingId String Identifier of a binding created earlier. It can be used only if the merchant has the permission to work with bindings.
No

features String Below are the allowed values.
  • AUTO_PAYMENT - Payment is processed without cardholder authentication (without CVC or 3-D Secure). To process these payments merchant must have sufficient permissions in the payment gateway.
  • VERIFY - If you specify this value in the order registration request, cardholder will be verified (they will have to go through 3-D Secure procedure) however they will not be charged any amount, so in this case amount parameter can be 0. Verification allows to make sure that a payment card is used by its legitimate owner, and further you can charge them without authentication (CVC, 3D-Secure). Even if some amount is passed in the request, the customer will not be charged if VERIFY feature is used. After a successful registration order status is changed to REVERSED (canceled).
  • FORCE_TDS - Force 3-D Secure payment. If a payment card does not support 3-D Secure, the transaction will fail.
  • FORCE_SSL - Force SSL payment (without 3-D Secure).
  • FORCE_FULL_TDS - After 3-D Secure authentication, PaRes status must be Y, which guarantees successful user authentication. Otherwise, the transaction will fail.
No

phone Integer Customer's phone number. It is always necessary to specify the country code, but you can specify or omit the + sign. Thus, the following options are valid:
  • +79998887766;
  • 79998887766.Allowed digits number: from 7 to 15.
No

email String Customer's email address.
See description

billingPayerData Object A block with the client's registration data (address, postal code) necessary for passing the address verification within the AVS/AVV services. Mandatory if the feature is enabled for the merchant on Payment Gateway side.

Below are the parameters of the billingPayerData block (data about the client registration address).

Mandatory Name Type Description
No

billingCity String The city registered on a specific card of the Issuing Bank.
No

billingCountry String The country registered on a specific card of the Issuing Bank ( ISO 3166-1, numeric).
No

billingAddressLine1 String The address registered on a specific card of the Issuing Bank. Line 1. Mandatory to be passed in order AVS verification works.
No

billingAddressLine2 String The address registered on a specific card of the Issuing Bank. Line 2.
No

billingAddressLine3 String The address registered on a specific card of the Issuing Bank. Line 3.
No

billingPostalCode String Postal code registered on a specific card of the Issuing Bank. Mandatory to be passed in order AVS verification works.
No

billingState String The state registered on a specific card of the Issuing Bank (ISO 3166-2).

Response parameters

Mandatory Name Type Description
No

formUrl String URL of the payment form, to which a customer will be redirected The URL is not returned if the registration of the order fails due to an error specified in errorCode.
No

errorCode Integer Error code. Can be missing if the result has not caused an error.
No

orderId String Order number in the payment gateway. Unique within the payment gateway.
No

errorMessage String Error description. Language of the description is set in language parameter of the request.

Error codes

Error code Error message
0 Request processing took place without system errors.
1 Order with given order number is processed already.
1 Order number is invalid
3 Unknown currency.
4 Order number is empty.
4 Empty merchant user name.
4 Empty amount.
4 Empty return URL.
4 Password cannot be empty.
5 Access denied.
5 The user must change his password.
5 [jsonParams] is invalid.
7 System error.
13 Merchant doesn't have the permission to verify payments.
14 Features are invalid.

Examples

Request example

curl --request POST \
  --url https://sandbox.paydoc.io/payment/rest/register.do \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data amount=2000 \
  --data userName=test_user \
  --data password=test_user_password \
  --data returnUrl=finish.html \
  --data failUrl=errors_ru.html \
  --data email=test@test.ru \
  --data clientId=259753456 \
  --data language=en

Response example

{
  "orderId": "01491d0b-c848-7dd6-a20d-e96900a7d8c0",
  "formUrl": "https://sandbox.paydoc.io/payment/merchants/rbs/payment_en.html?mdOrder=01491d0b-c848-7dd6-a20d-e96900a7d8c0"
}

Order pre-authorization

To request registration of an order with preauthorization registerPreAuth.do method is used.

Request parameters

Mandatory Name Type Description
See description

userName String Merchant 's API account login. If you pass your login and password to authenticate in the payment gateway, do not pass token parameter.
See description

password String Merchant's API account password. If you pass your login and password to authenticate in the payment gateway, do not pass token parameter.
See description

token String Value that is used for merchant authentication when requests are sent to the payment gateway. If you pass this parameter do not pass userName and password.
Yes

orderNumber Alphanumeric Order number (ID) in the merchant's system, must be unique for each merchant.
Yes

amount Integer Payment amount in minor currency units (e.g. in cents etc.).
No

currency Integer SO 4217 encoded currency key. If not specified, the default value is used.
Yes

returnUrl String The address to which the user will be redirected if the payment is successful. The address must be specified in full including the protocol used (for example, https://test.ru instead of test.ru). Otherwise, the user will be redirected to the address of the following type http://<payment_gateway_address>/<merchant_address>.
No

failUrl String The address to which the user is to be redirected in case of a failed payment. The address must be specified in full including the protocol used (for example, https://test.ru instead of test.ru). Otherwise, the user will be redirected to the address of the following type http://<payment_gateway_address>/<merchant_address>.
No

dynamicCallbackUrl String This parameter allows you to use the functionality of sending callback notifications dynamically. Here you can pass the address to which all "payment" callback notifications, activated for the merchant, will be sent. "Payment" notifications are callback notifications related to the following events: successful hold, payment declined by timeout, cardpresent payment is declined, successful debit, refund, cancellation. At the same time, callback notifications activated for the merchant that are not related to payments (enabling/disabling a binding, creating a binding) will be sent to a static address for callbacks. Mandatory use depends on the merchant configuration on Payment Gateway side.
No

description String Order description in any format.
To enable sending this field to the processing system, contact the technical support service.
No

language Alphabetic ISO 639-1 encoded language key. If the language is not specified, the default language specified in the store settings is used.
No

pageView String By the value of this parameter, it is defined what pages of the payment interface are to be loaded for the customer. The following values are allowed.
  • DESKTOP – for loading pages for PC (in the archive that contains pages of the payment interface the following pages will be searched: payment_<locale>.html and errors_<locale>.html).
  • MOBILE – for loading pages for mobile devices (in the archive that contains pages of the payment interface the following pages will be searched: mobile_payment_<locale>.html and mobile_errors_<locale>.html).
  • If a merchant created payment pages and added their own prefixes, pass the created prefixes in pageView parameter to load the corresponding page. For example, when passing iphone value, pages with iphone_payment_<locale>.html and iphone_error_<locale>.htm will be searched

Where:
  • locale is the ISO 639-1 language key. For example, ru for Russian or en for English.

If this parameter is missing or does not match the format, it is considered that by default pageView=DESKTOP.
No

clientId Alphanumeric Customer number (ID) in the merchant's system — up to 255 characters . Used to implement the functionality of bindings. Can be returned in the response if the merchant is allowed to create bindings.
Specifying this parameter when processing payments via bindings is mandatory. Otherwise, a payment will be unsuccessful.
No

merchantLogin String To register an order on behalf of a child merchant, specify the merchant login in this parameter.
No

jsonParams String Block for passing additional merchant parameters. Fields containing additional info for further storage are pased as follows.
{name1:value1,…,nameN:valueN}
These fields can be transferred to the processing bank for further display in the bank registers.
Contact your bank to enable this functionality.
If customer notifications are configured for the merchant, then, customer's email must be passed in this block in the email parameter.
By default, the followng parameters are passed to the processing bank:
  • orderNumber – order number in the merchant's system;
  • description – order description (up to 99 characters, the following characters are forbidden^ %, +, end of line \r, and line break \n).

If you pass merchantOrderId parameter, then, its value will be passed to the processing bank as order number (instead of orderNumber parameter).
No

sessionTimeoutSecs Integer Order lifetime in seconds. If the parameter is not specified, the value specified in the merchant settings or the default value (1200 seconds = 20 minutes) will be used. If the request contains expirationDate, the value of sessionTimeoutSecs is not taken into account.
No

expirationDate String Data and time of the order expiry. Format used: yyyy-MM-ddTHH:mm:ss.
If this parameter is not passed in the request, sessionTimeoutSecs is used to define the expiry of the order.
No

bindingId String Identifier of a binding created earlier. It can be used only if the merchant has the permission to work with bindings.
No

features String Below are the allowed values.
  • AUTO_PAYMENT - Payment is processed without cardholder authentication (without CVC or 3-D Secure). To process these payments merchant must have sufficient permissions in the payment gateway.
  • VERIFY - If you specify this value in the order registration request, cardholder will be verified (they will have to go through 3-D Secure procedure) however they will not be charged any amount, so in this case amount parameter can be 0. Verification allows to make sure that a payment card is used by its legitimate owner, and further you can charge them without authentication (CVC, 3D-Secure). Even if some amount is passed in the request, the customer will not be charged if VERIFY feature is used. After a successful registration order status is changed to REVERSED (canceled).
  • FORCE_TDS - Force 3-D Secure payment. If a payment card does not support 3-D Secure, the transaction will fail.
  • FORCE_SSL - Force SSL payment (without 3-D Secure).
  • FORCE_FULL_TDS - After 3-D Secure authentication, PaRes status must be Y, which guarantees successful user authentication. Otherwise, the transaction will fail.
No

autocompletionDate String The date and time when the two-stage payment was completed automatically in the following format: 2017-12-29T13:02:51. To enable sending this field to the processing system, contact your technical support service.
No

email String Customer's email address.
No

phone Integer Customer's phone number. It is always necessary to specify the country code, but you can specify or omit the + sign. Thus, the following options are valid:
  • +79998887766;
  • 79998887766.Allowed digits number: from 7 to 15.
See description

billingPayerData Object A block with the client's registration data (address, postal code) necessary for passing the address verification within the AVS/AVV services. Mandatory if the feature is enabled for the merchant on Payment Gateway side.

Below are the parameters of the billingPayerData block (data about the client registration address).

Mandatory Name Type Description
No

billingCity String The city registered on a specific card of the Issuing Bank.
No

billingCountry String The country registered on a specific card of the Issuing Bank ( ISO 3166-1, numeric).
No

billingAddressLine1 String The address registered on a specific card of the Issuing Bank. Line 1. Mandatory to be passed in order AVS verification works.
No

billingAddressLine2 String The address registered on a specific card of the Issuing Bank. Line 2.
No

billingAddressLine3 String The address registered on a specific card of the Issuing Bank. Line 3.
No

billingPostalCode String Postal code registered on a specific card of the Issuing Bank. Mandatory to be passed in order AVS verification works.
No

billingState String The state registered on a specific card of the Issuing Bank (ISO 3166-2).

Response parameters

Mandatory Name Type Description
No

orderId String Order number in the payment gateway. Unique within the payment gateway.
No

formUrl String URL of the payment form, to which a customer will be redirected The URL is not returned if the registration of the order fails due to an error specified in errorCode.
No

errorCode Integer Error code. Can be missing if the result has not caused an error.
No

errorMessage String Error description. Language of the description is set in language parameter of the request.

Error codes

Error code Error message
0 Request processing took place without system errors.
1 Order with given order number is processed already.
1 Order number is invalid
3 Unknown currency.
4 Order number is empty.
4 Empty merchant user name.
4 Empty amount.
4 Empty return URL.
4 Password cannot be empty.
5 Wrong amount.
5 Invalid merchant language.
5 Merchant login is invalid.
5 Access denied.
5 The user must change his password.
5 [jsonParams] is invalid.
7 System error.
13 Merchant doesn't have the permission to verify payments.
14 Features are invalid.

Examples

Request example

curl --request POST \
  --url https://sandbox.paydoc.io/payment/rest/registerPreAuth.do \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data amount=2000 \
  --data userName=test_user \
  --data password=test_user_password \
  --data returnUrl=finish.html \
  --data orderNumber=1255555555555 \
  --data clientId=259753456 \
  --data language=en

Response example

{
  "orderId": "01492437-d2fb-77fa-8db7-9e2900a7d8c0",
  "formUrl": "https://sandbox.paydoc.io/payment/merchants/rbs/payment_en.html?mdOrder=01492437-d2fb-77fa-8db7-9e2900a7d8c0"
}

Deposit order

To complete a pre-authorized order use deposit.do request.

Request parameters

Mandatory Name Type Description
Yes

userName String Merchant's API account login.
Yes

password String Merchant's API account password.
Yes

orderId String Order number in the payment gateway. Unique within the payment gateway.
Yes

amount Integer Payment amount in minor currency units (e.g. in cents etc.).

Response parameters

Mandatory Name Type Description
No

errorCode Integer Error code. Can be missing if the result has not caused an error.
No

errorMessage String Error description. Language of the description is set in language parameter of the request.

Error codes

Error code Error message
5 Access denied.
5 The user must change his password.
5 Wrong amount.
5 Deposit amount must be at least 1 ruble or equal to zero.
6 Unknown order id.
7 Payment must be in the correct state.
7 System error.

Examples

Request example

curl --request POST \
  --url https://sandbox.paydoc.io/payment/rest/deposit.do \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data userName=test_user \
  --data password=test_user_password \
  --data amount=2000 \
  --data orderId=01492437-d2fb-77fa-8db7-9e2900a7d8c0 \
  --data language=en

Response example

{
  "errorCode": 0,
  "errorMessage":"Success"
}

Refund

Use refund.do to make refund requests.

You cannot refund orders that initialize recurrent payments, as no money are actually charged.

Upon this request, the funds for the specified order are to be returned to the payer. The request will end with an error if the funds have not been debited for this order. The system permits returning funds more than once, but for a total amount not exceeding the initial debit amount.

Request parameters

Mandatory Name Type Description
Yes

orderId String Order number in the payment gateway. Unique within the payment gateway.
Yes

amount Integer Payment amount in minor currency units (e.g. in cents etc.).
No

language Alphabetic ISO 639-1 encoded language key. If the language is not specified, the default language specified in the store settings is used.

Response parameters

Mandatory Name Type Description
No

errorCode Integer Error code. Can be missing if the result has not caused an error.
No

errorMessage String Error description. Language of the description is set in language parameter of the request.

Error codes

Error code Error message
0 Request processing took place without system errors.
5 Access denied.
5 The user must change his password.
5 [orderId] is empty.
5 Wrong amount.
6 Unknown order id.
7 Payment must be in the correct state.
7 Refund amount exceeds deposited amount.
7 System error.

Examples

Request example

curl --request POST \
  --url https://sandbox.paydoc.io/payment/rest/refund.do \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data userName=test_user \
  --data password=test_user_password \
  --data orderId=01491d0b-c848-7dd6-a20d-e96900a7d8c0 \
  --data amount=2000 \
  --data language=en

Response example

{
  "errorCode": 0,
  "errorMessage":"Success"
}

Order status

Request parameters

Mandatory Name Type Description
No

userName String Merchant 's API account login. If you pass your login and password to authenticate in the payment gateway, do not pass token parameter.
No

password String Merchant's API account password. If you pass your login and password to authenticate in the payment gateway, do not pass token parameter.
No

token String Value that is used for merchant authentication when requests are sent to the payment gateway. If you pass this parameter do not pass userName and password.
Yes

orderId String Order number in the payment gateway. Unique within the payment gateway.
Yes

orderNumber Alphanumeric Order number (ID) in the merchant's system, must be unique for each merchant.
No

language Alphabetic ISO 639-1 encoded language key. If the language is not specified, the default language specified in the store settings is used.

Response parameters

There are several sets of the response parameters. Which set of parameters is returned in the response, depends on the version of getOrderStatusExtended specified in the merchant's settings in the payment gateway.

Version Mandatory Name Type Description
All versions. See description

orderNumber Alphanumeric Order number (ID) in the merchant's system, must be unique for each merchant registered in the payment gateway — up to 30 characters. If the Order number is generated on the Payment Gateway side, this parameter is not mandatory.
All versions. No

orderStatus Integer The value of this parameter specifies the status of the order in the payment gateway. It is missing if the order has not been found. Below is the list of available values:
  • 0 - order was registered but not paid;
  • 1 - pre-authorized amount is on hold on the buyer's account (for two-phase payments);
  • 2 - order amount is fully authorized;
  • 3 - authorization canceled;
  • 4 - transaction was refunded;
  • 5 - access control server of the issuing bank initiated authorization procedure;
  • 6 - authorization declined.
All versions. Yes

actionCode Integer Response code from the processing bank.
All versions. Yes

actionCodeDescription String actionCode description returned from the processing bank.
All versions. No

errorCode Integer Error code. Can be missing if the result has not caused an error.
All versions. No

errorMessage String Error description. Language of the description is set in language parameter of the request.
All versions. Yes

amount Integer Payment amount in minor currency units (e.g. in cents etc.).
All versions. No

currency Integer SO 4217 encoded currency key. If not specified, the default value is used.
All versions. Yes

date String Order registration date.
All versions. No

orderDescription String Order description passed to the payment gateway during the registration.
All versions. Yes

ip String Buyer's IP address. IPv6 is supported in all requests. (up to 39 characters).
09 and later. Yes

paymentWay String Payment method (a payment with entering card data, a payment using a binding, etc.).
19 and later. No

avsCode Alphabetic A code of the AVS verification response (checking the address and postal code of the cardholder). Possible values:
  • A – postal code and address are the same.
  • B – address matches, postal code doesn't match.
  • C - postal code matches, address doesn't match.
  • D - postal code and address don't match.
  • E - data validation is requested, but the result is unsuccessful.
  • F - invalid format of the AVS/AVV verification request.

attributes block contains information on the order number in the payment gateway. name parameter contains the word mdOrder, and value parameter contains the actual order number in the payment gateway.

Version Name Type Mandatory Description
All versions. No

name Numeric Name of an additional parameter.
All versions. No

value Numeric Value of an additional parameter - up to 1024 characters.

merchantOrderParams block is passed in the response, if the order contains merchant additional parameters. Each additional parameter is passed in a separate merchantOrderParams element.

Version Name Type Mandatory Description
All versions. No

name Numeric Name of an additional parameter.
All versions. No

value Numeric Value of an additional parameter - up to 1024 characters.

cardAuthInfo element contains a structure consisting of secureAuthInfo element list and the following parameters.

Version Name Type Mandatory Description
All versions. No

maskedPan String Masked number of the card used for the payment. This parameter is to be specified only after the order has been paid.
All versions. No

expiration Integer Card expiration in the following format: YYYYMM. This parameter is to be specified only after the order has been paid.
All versions. No

cardholderName Alphabetic Cardholder's name in Latin characters. This parameter is passed only after an order is paid.
All versions. No

approvalCode String IPS authorization code. This field has a fixed length (six symbols) and can contain digits and Latin letters.
06 and later. No

refund Boolean Whether the funds was forcibly returned to the buyer by the bank. The possible values are:
  • true - funds were reversed;
  • false - funds were not reversed.
08 and later. Yes

paymentSystem String Payment system name. The following variants are possible:
  • VISA;
  • MASTERCARD;
  • AMEX;
  • JCB;
  • CUP;
  • MIR.
08 and later. Yes

product String Additional details on corporate cards. These details are filled in by the technical support service. If such details are missing, an empty value is returned.

secureAuthInfo element consists of eci element and threeDSInfo element that is a list of cavv and xid parameters).

Version Name Type Mandatory Description
All versions. No

eci Integer Electronic commerce indicator. The indicator is specified only after an order has been paid and in case the corresponding permission is present. Below is the explanation of ECI codes.
  • ECI=1 or ECI=6 - merchant supports 3-D Secure, payment card does not support 3-D Secure, payment is processed based on CVV2/CVC code.
  • ECI=2 or ECI=5 - both merchant and payment card support 3-D Secure;
  • ECI=7 - merchant does not support 3-D Secure, payment is processed based on CVV2/CVC code.
All versions. No

cavv String Cardholder authentication value. The indicator is specified only after an order is paid and if the corresponding permission is enabled.
All versions. No

xid String Electronic commerce indicator of the transaction. The indicator is specified only after an order has been paid and in case the corresponding permission is present.

bindingInfo element contains the following parameters.

Version Name Type Mandatory Description
All versions. No

clientId Alphanumeric Customer number (ID) in the merchant's system — up to 255 characters . Used to implement the functionality of bindings. Can be returned in the response if the merchant is allowed to create bindings.
Specifying this parameter when processing payments via bindings is mandatory. Otherwise, a payment will be unsuccessful.
All versions. No

bindingId String Identifier of a binding created earlier. It can be used only if the merchant has the permission to work with bindings.
02 and later. No

authDateTime String Authorization date and time, shown as the amount of milliseconds passed from 00:00 January 1, 1970 (GMT).
02 and later. No

authRefNum String Registration number of the payment authorization that has been assigned to it on the payment registration.
02 and later. No

terminalId String Terminal identifier.

paymentAmountInfo element contains the following parameters.

Version Name Type Mandatory Description
03 and later. No

approvedAmount Integer Amount in minimum currency units (e.g. cents) that was put on hold on buyer's account. Used in two-phase payments only.
03 and later. No

depositedAmount Integer Charged amount in minimum currency units (e.g. in cents).
03 and later. No

refundedAmount Integer Refunded amount in minimum currency units.
03 and later. No

paymentState String Order status, this parameter can have the following values:
  • CREATED - order created (but not paid);
  • APPROVED - order approved (funds are on hold on buyer's account);
  • DEPOSITED - order deposited (buyer is charged);
  • DECLINED - order declined;
  • REVERSED - order canceled;
  • REFUNDED - refund.
11 and later. No

feeAmount Integer Fee amount.

bankInfo element contains the following parameters.

Version Name Type Mandatory Description
03 and later. No

bankName String Issuing bank name.
03 and later. No

bankCountryCode String Country code of the issuing bank.
03 and later. No

bankCountryName String Country of the issuing bank.

Error codes

Error code Error message
0 Request processing took place without system errors.
5 Access denied.
5 The user must change his password.
5 [orderId] is empty.
6 Unregistered orderId.
7 System error.

Examples

Request example

curl --request POST \
  --url https://sandbox.paydoc.io/payment/rest/getOrderStatusExtended.do \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data userName=test_user \
  --data password=test_user_password \
  --data orderId=01491d0b-c848-7dd6-a20d-e96900a7d8c0 \
  --data language=en

Response example

{
  "errorCode": "0",
  "errorMessage": "Success",
  "orderNumber": "7005",
  "orderStatus": 2,
  "actionCode": 0,
  "actionCodeDescription": "",
  "amount": 2000,
  "currency": "978",
  "date": 1617972915659,
  "orderDescription": "",
  "merchantOrderParams": [],
  "transactionAttributes": [],
  "attributes": [
    {
      "name": "mdOrder",
      "value": "01491d0b-c848-7dd6-a20d-e96900a7d8c0"
    }
  ],
  "cardAuthInfo": {
    "maskedPan": "555555**5599",
    "expiration": "202412",
    "cardholderName": "TEST CARDHOLDER",
    "approvalCode": "123456",
    "pan": "555555**5599"
  },
  "bindingInfo": {
    "clientId": "259753456",
    "bindingId": "01491394-63a6-7d45-a88f-7bce00a7d8c0"
  },
  "authDateTime": 1617973059029,
  "terminalId": "123456",
  "authRefNum": "714105591198",
  "paymentAmountInfo": {
    "paymentState": "DEPOSITED",
    "approvedAmount": 2000,
    "depositedAmount": 2000,
    "refundedAmount": 0
  },
  "bankInfo": {
    "bankCountryCode": "UNKNOWN",
    "bankCountryName": "&ltUnknown&gt"
  }
}

Payment by binding

Request parameters

Mandatory Name Type Description
Yes

userName String Merchant's API account login.
Yes

password String Merchant's API account password.
Yes

mdOrder String Order number in the payment gateway. Unique within the payment gateway.
Yes

bindingId String Identifier of a binding created earlier. It can be used only if the merchant has the permission to work with bindings.
No

language Alphabetic ISO 639-1 encoded language key. If the language is not specified, the default language specified in the store settings is used.
Yes

ip String Buyer's IP address. IPv6 is supported in all requests. (up to 39 characters).
No

cvc Integer This parameter is mandatory if permission Can process payments without confirmation of CVC is not enabled.
No

email String Customer's email address.
No

threeDSSDK String Possible values: true or false. Flag showing that payment comes from 3DS SDK.

Response parameters

Mandatory Name Type Description
No

redirect String This parameter is returned if the payment is successful and that payment did not include check for 3-D Secure involvement. URL to which a customer is redirected after their payment.
No

info String If response is successful. Result of a payment attempt. Below are the possible values.
  • Your payment has been processed, redirecting...
  • Operation declined. Check the entered data and that there are enough funds on the card and repeat the operation. Redirecting...
  • Sorry, payment cannot be completed. Redirecting...
  • Operation declined. Contact the merchant. Redirecting...
  • Operation declined. Contact the bank that issued the card. Redirecting...
  • Impossible operation. Cardholder authentication completed unsuccessfully. Redirecting...
  • No connection with bank. Try again later. Redirecting...
  • Input time expired. Redirecting...
  • No response from bank received. Try again later. Redirecting...
Yes

errorCode Integer Error code. Can be missing if the result has not caused an error.
No

errorMessage String Error description. Language of the description is set in language parameter of the request.
No

error String Error message (if response returned an error) in the language passed in the request.
No

acsUrl String On a successful response in case of a 3D-Secure payment. URL address for redirecting to ACS.
No

paReq String On a successful response in case of a 3D-Secure payment. Payment Authentication Request.
No

termUrl String In a successful response in case of a 3D-Secure payment. URL address for redirecting to ACS.

Error codes

Error code Error message
0 Request processing took place without system errors.
1 [cvc] is empty.
2 Binding not found.
2 Order not found.
5 Access denied.
5 The user must change his password.
7 System error.

Examples

Request example

curl --request POST \
  --url https://sandbox.paydoc.io/payment/rest/paymentOrderBinding.do \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data userName=test_user \
  --data password=test_user_password \
  --data mdOrder=01491d0b-c848-7dd6-a20d-e96900a7d8c0 \
  --data bindingId=01491394-63a6-7d45-a88f-7bce00a7d8c0 \
  --data clientId=259753456 \
  --data ip=1d0d:db8:6:1::77 \
  --data cvc=123 \
  --data language=en

Example of a success response for an SSL-payment (no 3-D Secure)

{
  "redirect": "https://sandbox.paydoc.io/payment/merchants/temp/finish.html?orderId=01491d0b-c848-7dd6-a20d-e96900a7d8c0&lang=en",
  "info": "Your order is proceeded, redirecting...",
  "errorCode": 0
}

An example of a success response for a 3D-Secure payment

{
  "info": "Your order is proceeded, redirecting...",
  "errorCode": 0,
  "acsUrl": "https://web.rbsuat.com/acs/auth/start.do",
  "paReq": "eJxVUu9vgjAQ/VcM37FQKqI5a9zUjEWI2TDZt6VCBxj5IRSj/vVrEab70OTe3fW967vC/JIdB2de1WmRzzRzaGgDnodFlObxTNsFa93R5hSCpOJ8+cnDpuIUPF7XLOaDNJpp2B79OJYz0e2ITXTCTaI7Y2bpeDwyrYkVhXuHaRS2iw9+otAJUakzxIB6KBmrMGG5oMDC04vrU4LHtmEA6iBkvHKXdEQsbBFAdwQ5yzitWR7ti8t31lEAatMQFk0uqiu1iQWoB9BUR5oIUU4RErwWw7DIAKkkoMcM20ZFtSS5pBH1b/HVv3mGF6ywF8SGd9jd/IMnTzwDpDogYoJTbGDTICYZmM7UsqeGlG3zwDKlLuvtg+4ASqWxeK48Z0AaXck99OP3CPilLHKu7gD6iwE9Jn59Ux6GQvpzLlfBpEwcX3ibrVuwdbrelOv3OvpaucrZtkkxptIZTMw7pQKAFA3qloa6fcvo3z/4BaHYvAI=",
  "termUrl": "https://sandbox.paydoc.io/payment/rest/finish3ds.do?lang=en"
}

Example of a response with an error

{
  "error": "Access denied",
  "errorCode": 5,
  "errorMessage": "Access denied"
}

Payment card data is collected on merchant's side (validation)

Payment card validation is done as shown in the table below.

Parameter Description Validation

PAN

Full payment card number Luhn validation (if payment card number is real), number of digits in a card number is from 13 to 20

CVC

CVC code 3 digits

YYYY, MM

Year, Month Present or future date. If card expiry is current year and month payment is possible only until the end of the current calendar month.

TEXT

Cardholder Not verified.

Payment order, card data is collected on merchant's side (internal MPI)

To make a payment paymentOrder.do request is used.

Request parameters

Mandatory Name Type Description
Yes

userName String Merchant's API account login.
Yes

password String Merchant's API account password. If you pass your login and password to authenticate in the payment gateway, do not pass token parameter.
Yes

MDORDER String Order number in the payment gateway.
Yes

$PAN Numeric Payment card number.
Yes

$CVC Numeric CVC/CVV2 code on the back of a payment card.
Yes

YYYY Numeric Payment card expiry year.
Yes

MM Numeric Payment card expiry month.
Yes

TEXT Alphabetic Cardholder name.
Yes

language Alphabetic ISO 639-1 encoded language key. If the language is not specified, the default language specified in the store settings is used.
No

ip String Buyer's IP address. IPv6 is supported in all requests. (up to 39 characters).
No

email String Customer's email address.
No

bindingNotNeeded Boolean Allowed values:
  • true – binding creation after the payment is made disabled (binding is a customer identifier passed in order registration request — after paymentOrder request it will be deleted from order details);
  • false – if payment is successful a binding can be created (if the necessary conditions are met). This is the default value.
No

jsonParams String Block for passing additional merchant parameters. Fields containing additional info for further storage are pased as follows.
{name1:value1,…,nameN:valueN}
These fields can be transferred to the processing bank for further display in the bank registers.
Contact your bank to enable this functionality.
If customer notifications are configured for the merchant, then, customer's email must be passed in this block in the email parameter.
By default, the followng parameters are passed to the processing bank:
  • orderNumber – order number in the merchant's system;
  • description – order description (up to 99 characters, the following characters are forbidden^ %, +, end of line \r, and line break \n).

If you pass merchantOrderId parameter, then, its value will be passed to the processing bank as order number (instead of orderNumber parameter).
No

threeDSSDK String Possible values: true or false. Flag showing that payment comes from 3DS SDK.
See description

billingPayerData Object A block with the client's registration data (address, postal code) necessary for passing the address verification within the AVS/AVV services. Mandatory if the feature is enabled for the merchant on Payment Gateway side.

Below are the parameters of the billingPayerData block (data about the client registration address).

Mandatory Name Type Description
No

billingCity String The city registered on a specific card of the Issuing Bank.
No

billingCountry String The country registered on a specific card of the Issuing Bank ( ISO 3166-1, numeric).
No

billingAddressLine1 String The address registered on a specific card of the Issuing Bank. Line 1. Mandatory to be passed in order AVS verification works.
No

billingAddressLine2 String The address registered on a specific card of the Issuing Bank. Line 2.
No

billingAddressLine3 String The address registered on a specific card of the Issuing Bank. Line 3.
No

billingPostalCode String Postal code registered on a specific card of the Issuing Bank. Mandatory to be passed in order AVS verification works.
No

billingState String The state registered on a specific card of the Issuing Bank (ISO 3166-2).

Response parameters

Mandatory Name Type Description
Yes

errorCode Integer Error code. Can be missing if the result has not caused an error.
No

errorMessage String Error description. Language of the description is set in language parameter of the request.
No

info String If response is successful. Result of a payment attempt. Below are the possible values.
  • Your payment has been processed, redirecting...
  • Operation declined. Check the entered data and that there are enough funds on the card and repeat the operation. Redirecting...
  • Sorry, payment cannot be completed. Redirecting...
  • Operation declined. Contact the merchant. Redirecting...
  • Operation declined. Contact the bank that issued the card. Redirecting...
  • Impossible operation. Cardholder authentication completed unsuccessfully. Redirecting...
  • No connection with bank. Try again later. Redirecting...
  • Input time expired. Redirecting...
  • No response from bank received. Try again later. Redirecting...
No

redirect String This parameter is returned if the payment is successful and that payment did not include check for 3-D Secure involvement. URL to which a customer is redirected after their payment.
No

termUrl String In a successful response in case of a 3D-Secure payment. URL address for redirecting to ACS.
No

acsUrl String On a successful response in case of a 3D-Secure payment. URL address for redirecting to ACS.
No

paReq String On a successful response in case of a 3D-Secure payment. Payment Authentication Request.

Error codes (errorCode parameter):

Value Description
0 Request processing took place without system errors.
5 Payments attempts exceeded.
5 System or internal error.

Examples

Request example

curl --request POST \
  --url https://sandbox.paydoc.io/payment/rest/paymentorder.do \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data userName=test_user \
  --data password=test_user_password \
  --data MDORDER=014932b6-9dc7-7782-aeec-a07500a7d8c0 \
  --data '$PAN=5555555555555599' \
  --data '$CVC=123' \
  --data YYYY=2024 \
  --data MM=12 \
  --data 'TEXT=TEST CARDHOLDER' \
  --data language=en

Response examples

Response example when 3-D Secure authentication is not required.

{
  "redirect": "https://sandbox.paydoc.io/payment/merchants/temp/finish.html?orderId=014932b6-9dc7-7782-aeec-a07500a7d8c0&lang=en",
  "info": "Your order is proceeded, redirecting...",
  "errorCode": 0
}

Response example when 3-D Secure authentication is required.

{
  "info": "Your order is proceeded, redirecting...",
  "errorCode": 0,
  "acsUrl": "https://web.rbsuat.com/acs/auth/start.do",
  "paReq": "eJxVUsFWwjAQ/BVe7yVNmrbIW+JDQOFAVawHvfhKu5QKTaENvsrXm0ARve3MJjOb2cBtU2w7X1jVeSkHFu06VgdlUqa5zAbWa3Rv96xbAdG6Qhy/YHKoUMAc6zrOsJOnA6sXBMFq5fn2kiO1OcOl3XN7nr2M0VkFbnrjUd8S8DRc4F5AayS0T5cBuUCtWCXrWCoBcbK/m4WCs8B3HCAthAKr2Vh43GUuB3JGIOMCRR3LdFk2H0UrAeREQ1IepKq+hc9dIBcAh2or1krt+oQorFU3KQsghgRyneHpYKpaizR5KsLjjIfjZ3d+nLB5lDnh54aG0eR7ftwMgJgTkMYKBXMYdTj1Oo7f91jfpUBOPMSFcdf904POAHbGY/i385cBHXSl93AZ/4IAm10p0dwB8lsDuU48mpoME6XzkYutGr5Pm8fR5G5fUF4c3yI2XT1kb5lvkj0dMoq5ToZxepY0AIiRIe3SSLtvXf37Bz+jLruc",
  "termUrl": "https://sandbox.paydoc.io/payment/rest/finish3ds.do?lang=en"
}

If 3-D Secure is required, then, after receiving a paymentOrder response, the customer must be redirected to ACS. There are two ways to do that: regular and simplified (see the table below).

Redirection method Description
Regular If a payment is made with 3-D Secure, merchants must redirect their customers to ACS using the address specified in acsUrl, the request body must be MD=mdorder&PaReq=pareq&TermUrl=termUrl, where:
  • mdorder - unique order ID in the payment gateway;
  • pareq - parameter received from the paymentOrder response;
  • termUrl - parameter received from the paymentOrder response.

  • It must be a POST request.
    Depending on the configuration agreed with your bank, the customer after ACS authentication will be redirected either to the store or to the payment gateway. Variants of payment completion are described below.
Simplified For customers to access the ACS authentication page, the merchant redirects them to the payment gateway page at the following URL:
<payment gateway address>/acsRedirect.do?orderId=<order number>
where:
  • <payment gateway address> - server and context used to connect to the payment gateway;
  • <order number> - customer's unique order number.

Then, without other actions required from customer, the payment gateway redirects them to the ACS page, where customer authenticates.
If payments attempts are exceeded, the last payment attempts receives the following response.
{"redirect":"false.html?login=test&orderId=85eb9a84-2a47-7cca-b0ae-662c000016d1&lang=ru","info":"Operation declined. Check the entered data, amount available on your payment card, and try again.<br>Redirecting...","errorCode":0}
Redirect URL in this case is the value passed in failUrl parameter (or returnUrl if failUrl was not passed).
All further attempts will receive the following response.
{"redirect":"false.html?login=test&orderId=85eb9a84-2a47-7cca-b0ae-662c000016d1&lang=ru","info":"Redirecting...","errorCode":0}
Redirect URL in this case is the value passed in failUrl parameter (or returnUrl if failUrl was not passed).
The payment gateway will not return error in this case.

Payment order, card data is collected on merchant's side (external MPI)

Request parameters

Mandatory Name Type Description
Yes

userName String Merchant's API account login.
Yes

password String Merchant's API account password.
Yes

MDORDER String Order number in the payment gateway.
Yes

$PAN Numeric Payment card number.
Yes

$CVC Numeric CVC/CVV2 code on the back of a payment card.
Yes

YYYY Numeric Payment card expiry year.
Yes

MM Numeric Payment card expiry month.
Yes

TEXT Alphabetic Cardholder name.
Yes

language Alphabetic ISO 639-1 encoded language key. If the language is not specified, the default language specified in the store settings is used.
No

ip String Buyer's IP address. IPv6 is supported in all requests. (up to 39 characters).
No

email String Customer's email address.
No

bindingNotNeeded Boolean Allowed values:
  • true – binding creation after the payment is made disabled (binding is a customer identifier passed in order registration request — after paymentOrder request it will be deleted from order details);
  • false – if payment is successful a binding can be created (if the necessary conditions are met). This is the default value.
No

jsonParams Alphanumeric Fileds for storing additional data, must be passed as follows {"param":"value","param2":"value2"}.
These fields can be passed to the processing bank for further display in the bank registries.
By default orderNumber (order number) and description (order description) are passed. description must not exceed 99 characters, do not use the following characters: %, +, end of line \r and line break \n).
To enable this functionality contact your bank.
If you use external MPI the payment gateway expects that every paymentOrder request will include eci parameter. If eci value differs from the ones used for SSL authorizations it is also necessary to pass xid and cavv parameters.
See description

billingPayerData Object A block with the client's registration data (address, postal code) necessary for passing the address verification within the AVS/AVV services. Mandatory if the feature is enabled for the merchant on Payment Gateway side.

Below are the parameters of the billingPayerData block (data about the client registration address).

Mandatory Name Type Description
No

billingCity String The city registered on a specific card of the Issuing Bank.
No

billingCountry String The country registered on a specific card of the Issuing Bank ( ISO 3166-1, numeric).
No

billingAddressLine1 String The address registered on a specific card of the Issuing Bank. Line 1. Mandatory to be passed in order AVS verification works.
No

billingAddressLine2 String The address registered on a specific card of the Issuing Bank. Line 2.
No

billingAddressLine3 String The address registered on a specific card of the Issuing Bank. Line 3.
No

billingPostalCode String Postal code registered on a specific card of the Issuing Bank. Mandatory to be passed in order AVS verification works.
No

billingState String The state registered on a specific card of the Issuing Bank (ISO 3166-2).

Response parameters

Mandatory Name Type Description
Yes

errorCode Integer Error code. Can be missing if the result has not caused an error.
No

errorMessage String Error description. Language of the description is set in language parameter of the request.
No

info String If response is successful. Result of a payment attempt. Below are the possible values.
  • Your payment has been processed, redirecting...
  • Operation declined. Check the entered data and that there are enough funds on the card and repeat the operation. Redirecting...
  • Sorry, payment cannot be completed. Redirecting...
  • Operation declined. Contact the merchant. Redirecting...
  • Operation declined. Contact the bank that issued the card. Redirecting...
  • Impossible operation. Cardholder authentication completed unsuccessfully. Redirecting...
  • No connection with bank. Try again later. Redirecting...
  • Input time expired. Redirecting...
  • No response from bank received. Try again later. Redirecting...

If errorCode = 0 and info = "Your order is proceeded, redirecting", then payment processed successfully. In other cases an error occurred, see errorMessage.

Error codes (errorCode parameter):

Value Description
0 The requests has been processed without system errors..
5 Payment attempts exceeded.
5 System or internal error.

Examples

Request example

curl --request POST \
  --url https://sandbox.paydoc.io/payment/rest/paymentorder.do \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data userName=test_user \
  --data password=test_user_password \
  --data MDORDER=0140dda0-71ed-7706-a61f-36bd00a7d8c0 \
  --data '$PAN=5555555555555599' \
  --data '$CVC=123' \
  --data YYYY=2024 \
  --data MM=12 \
  --data 'TEXT=TEST CARDHOLDER' \
  --data language=en \
  --data 'xid=MDAwMDAwMDEzMzkyMjg5ODExNTc=' \
  --data 'cavv=AAABCpEChRM5IomAKFAAAAAAAAA=' \
  --data eci=05

Response example

{
  "redirect": "https://sandbox.paydoc.io/payment/merchants/temp/finish.html?orderId=01493844-d4d3-703f-9f7e-a73900a7d8c0&lang=en",
  "info": "Your order is proceeded, redirecting...",
  "errorCode": 0
}