Request for order payment (paymentorder.do)

The request used for payment for an order is paymentorder.do.

Only POST is supported.

The Payment Gateway supports usage of both internal and external MPI.

Validation of card data occurs in accordance with the table:

Name	Meaning	Validation
PAN	N..19	Card validation (check whether the card number is valid), the number of digits in the card number from 13 to 20
CVC	CVC code	3 digits
YYYY, MM	Year, Month	Present or future date If the card is valid until the current year of the current month, payment is possible before the end of the calendar month
TEXT	Cardholder	Not tested

In this document, the following data type conventions are used when describing request and response parameters:

A<n> – a sequence of Latin letters of length <n>;
A..<n> – a sequence of Latin letters with a length not exceeding <n>;
N<n> – a sequence of digits of length <n>;
N..<n> – a sequence of digits with a length not exceeding <n>;
AN<n> – a sequence of Latin letters and numbers of fixed length <n>;
AN.. <n> – a sequence of Latin letters and numbers with a length not exceeding <n>;
ANS<n> – a sequence of Latin letters, numbers and characters of fixed length <n>
ANS.. <n> – a sequence of Latin letters, numbers and characters with a length not exceeding <n>;
UTC – date and time, in this case: the date must be passed without specifying the time zone, Moscow time, for the SOAP protocol, the standard encoding xs: dateTime is used.

Internal MPI

Request parameters:

Name	Type	Mandatory	Description
`userName`	AN..30	Yes	Login of the service account of the merchant.
`password`	AN..30	Yes	Merchant's service account password.
MDORDER	ANS..36	Yes	Order number in the payment gateway. Unique within the payment gateway.
$PAN	N12…19	Yes	Payment card number.
$CVC	N3	Yes	CVC/CVV2 code on the back of the card.
YYYY	N4	Yes	The year of expiration of card validity period.
MM	N2	Yes	The month of expiration of card validity period.
TEXT	A..512	Yes	Cardholder's name in Latin characters, if available.
`language`	A2	Yes	Language in the ISO 639-1 encoding. If the language is not specified, the default language defined in the store settings is used.
`ip`	ANS..39	No	IP-address of the buyer. IPv6 is supported in all requests (up to 39 characters).
`email`	ANS..40	No	Customer's email address.
`bindingNotNeeded`	boolean	No	The possible values are: true – prohibition to create a binding after the payment (the Customer identifier passed during order registration will be removed from the order details after the payment is made); false – as a result of successful payment, a binding can be created (if the corresponding conditions are met). This value is the default value.
`jsonParams`	String	No	Additional parameters of the request. Format: {«Name1»: «Value1», «Name2»: «Value2»}. It is forbidden to pass reserved names in the parameter (if they are passed, the order may be rejected): sbrf_spasibo:amount_bonus sbrf_sbermiles:amount_bonus loyaltyId
`billingPayerData`	See description	No	Customer's registration data (street address, postal code). Required for AVS/AVV checks. Mandatory if «AVS/AVV use allowed» permission is enabled for merchant

billingPayerData

billingPayerData block parameters

Name	Type	Mandatory	Description
`billingCity`	AN..50	No	City registered for the card at the Issuer Bank.
`billingCountry`	AN..50	No
`billingAddressLine1`	AN..50	No	Address registered for the card at the Issuer Bank. Line 1. Mandatory if «AVS/AVV use allowed» permission is enabled for merchant.
`billingAddressLine2`	AN..50	No	Address registered for the card at the Issuer Bank. Line 2.
`billingAddressLine3`	AN..50	No	Address registered for the card at the Issuer Bank. Line 3.
`billingPostalCode`	AN..50	No	Postal code registered for the card at the Issuer Bank. Mandatory if «AVS/AVV use allowed» permission is enabled for merchant.
`billingState`	AN..50	No	State registered for the card at the Issuer Bank (ISO 3166-2).

* By default, the orderNumber and description fields are passed to the bank's processing system (no more than 99 characters, %, +, carriage return \r and line feed \n cannot be used)

Response parameters:

Name	Type	Mandatory	Description
`errorCode`	ANS..3	Yes	Error code.
`errorMessage`	AN..512	No	Error description in the language passed in the `language` parameter in the request.
`info`	ANS..*	No	On a successful response. Result of a payment attempt. The available values are presented below. Your payment has been processed, redirecting.. Payment declined. Check the entered data and that there are enough funds on the card and repeat the operation. Redirecting… Sorry, the payment cannot be processed. Redirecting… Payment declined. Please contact the Merchant. Redirecting… Payment declined. Contact the bank that issued the card. Redirecting… Operation is impossible. Cardholder authentication completed unsuccessfully. Redirecting… No connection to the bank. Try again later. Redirecting… The data entering period has expired. Redirecting… No response from the bank. Try again later. Redirecting…
`redirect`	ANS..*	No	On a successful response. In the case of a payment without the need for authentication to the ACS – URL to which redirect is performed after the payment. In case of a 3D-Secure payment, the URL to return to ACS.
`termUrl`	AN..512	No	URL to redirect the payer to after authentication. Not used for payments that do not require additional authentication on the issuing Bank's ACS.
`acsUrl`	AN..512	No	Redirect address to the address of the ACS server. Not used for payments that do not require additional authentication on the issuing Bank's ACS.
`paReq`	AN..512	No	Request for the payer authentication. Not used for payments that do not require additional authentication on the issuing Bank's ACS.

Error codes

Error code	Error text
0	Request processing took place without system errors
5	All payment attempts are used
5	System or internal error

Request example:

MDORDER=0d4b02cb-5147-4232-9012-4d38c743ahr6&$PAN=5555555555555599&$CVC=123&YYYY=2015&MM=12&TEXT=Card Holder&language=ru

An example of a response in case of a payment that does not require additional authentication on the ACS of the Issuing Bank:

{"redirect":"www.ya.ru?MDORDER=8cfb5c89-c2db-49e4-80c5-a0569c897cbf&ANSWER=%3C%3Fxml+version%3D%221.0%22+encoding%3D%22UTF-8%22%3F%3E%0A%3CPSApiResult+primaryRC%3D%220%22+secondaryRC%3D%220%22%2F%3E&STATE=payment_deposited&ACTION_CODE=0&AUTH_CODE=2","info":"Your order is proceeded, redirecting...","errorCode":0}

An example of a response in case of a 3DS payment that requires additional authentication on the ACS of the Issuing Bank:

{"info":"Your payment has been processed, redirecting.",
"acsUrl":"https://test.paymentgate.ru/acs/auth/start.do",
"paReq":"eJxVUdFygjAQ/BWG9xKioNQ54tCirQ+oo/QDKNwAVYIGENuvbyJQ60Nmdu8um80ez
K/FUbugqPKS\nuzo1TF1DHpdJzlNX/wiXT44+ZxBmAtHfY9wIZBBgVUUpanni6kWVGlRnsPV2e
GbQKzEpZIyADFRe\nEXEW8ZpBFJ9fVmtmjaYT0wTSUyhQrHw2BdIB4FGBbI8X5Is8zep1zhHIr
Qhx2fBafLOJNQYyEGjE\nkWV1fZoR0ratkZZlekRDNEBUB8jdwbZRqJJK1zxhge+13Vn8bMLD9
yZM7eDLs4Lw4AJRE5BENbKR\nSS3TNm2NOjPTmVnS+60OUaEsMGrKrvpQR+GkXvEee/9rILMUM
urhHwMDvJ5KjnJC5veHgdxdv76r\nFONaxuSveRIvnyfeWxjsNk4QHXJaFZ/V+NIuVba3IaWYy
4ioTTtJRYAoGdKvjfQrlehh1b8el7SS\n",
"termUrl":"https://test.paymentgate.ru:443/testpayment/rest/finish3ds.do",
"errorCode":0}

If the payment requires the use of 3-D Secure technology, then once the response to order payment request is received, the Customer must ne redirected to ACS. There are two ways to redirect: standard and simplified (see table below).

Redirect types	Description
Standard	To redirect to ACS the merchant must send to the customer to the address specified in the acsUrl parameter with the request body MD=mdorder&PaReq=pareq&TermUrl=redirect, where: mdorder – unique order number in the payment gateway system pareq – parameter from the response to the payment request, redirect – parameter from the response to the payment request (return address from ACS) or the Store URL, if the scheme where ACS returns to the Store is used. The request must be in POST format. Depending on the connection scheme used, the Customer after being authenticated on ACS will be redirected to the Payment Gateway or to the Store. The payment completion processes for each of these cases are described below.
Simplified	In order for the Customer to get to the ACS page, the Merchant redirects him to the Payment Gateway page with the following URL pattern: <api.payment gateway address>/acsRedirect.do?orderId=<order number> where: <`payment gateway address`> – server and context of the payment gateway; Please remember to include api. before the domain name. <`Order number`> – unique customer order number. Next, the Payment Gateway redirects the Customer (without additional actions on the part of the Customer) to the ACS of the bank, where the Customer is authenticated.

If no attempts left, the gateway returns the following response to the last payment attempt.

{"redirect":"false.html?login=test&orderId=85eb9a84-2a47-7cca-b0ae-662c000016d1&lang=ru","info":"Operation rejected. Check the entered data, ensure that there are enough funds on the card.. <br>Redirecting...", "errorCode":0}

The redirect URL is the value passed in the failUrl parameter (or returnUrl, if failUrl is missing).

The payment gateway will return the following response for all subsequent payment attempts.

{"redirect":"false.html?login=test&orderId=85eb9a84-2a47-7cca-b0ae-662c000016d1&lang=ru","info":"Redirecting...","errorCode":0}

The redirect URL is the value passed in the failUrl parameter (or returnUrl, if failUrl is missing).

However, the gateway will not return an error.

Return from ACS to Payment Gateway. Standard scheme.

The issuer's ACS authenticates the cardholder and redirects the client to the payment gateway while passing PARes. The payment gateway authorizes the order if the client is successfully authenticated on ACS, or rejects the pre-authorization if the client is not successfully authenticated on the ACS.

Returns from ACS to the store. Scheme involving additional Finish 3DS method

The Issuer's ACS authenticates the cardholder and redirects the Customer back to the Store. The PARes received from ACS is passed to the Store, after which the Store passes it to the gateway using the finish3dsPayment.do method.

Description of finish3dsPayment.do method is given below:

Request parameters:

Name	Type	Mandatory	Description
`userName`	AN..30	Yes	Login of the service account of the merchant.
`password`	AN..30	Yes	Merchant's service account password.
`mdOrder`	ANS..36	Yes	Order number in the payment gateway. Unique within the payment gateway.
`paRes`	ANS	Yes	Response to the payer's authentication request.

Response parameters:

Name	Type	Mandatory	Description
`redirect`	ANS..*	No	On a successful response. In the case of a payment without the need for authentication to the ACS – URL to which redirect is performed after the payment. In case of a 3D-Secure payment, the URL to return to ACS.
`errorCode`	ANS..3	No	Error code.
`error`	AN..512	No	Error message (when responding with an error).

If errorCode = 0 – payment was successful. In other cases with an error, see the error error message

Error codes (errorCode field):

Error code	Error text
0	Request processing took place without system errors
5	Access denied
5	The user must change the password
7	Order is not found
7	System error