Request for order payment (paymentOrder)

The request used for payment for an order is paymentOrder.

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
year, month 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
cardholderName 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

orderId

ANS36

Yes

Identifier of the order in the payment system. It is unique within the system. The identifier is missing if the order registration failed due to an error detailed in errorCode.

pan

N12…19

Yes

Payment card number.

cvc

N3

Yes

CVC/CVV2 code on the back of the card.

year N4 Yes The last year of the expiration period of the card.
month N2 Yes Month of the billing period in the MM format.

cardholderName

A..200

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.

params

See column with the description.

No

Additional tag with the attributes for passing additional parameters. The fields for additional information and its subsequent storage. These fields can be submitted for processing by the bank for further display in the registers. By default, the order number orderNumber and its description orderDescription are passed to the bank for processing (no more than 99 characters, «%» (percentage), «+» (plus),  «\r» (carriage return) and «\n» (line feed) are prohibited for using).

Enabling the functionality is possible upon agreement with the Bank during the integration period. To pass N parameters, a request must contain N params tags, where the name attribute contains the parameter name and value attribute contains its value:

Name Type Description
Name

name

Type

AN..20

Type2

ANS..255

Type3

A7

Type4

ANS..100

Description
REST

Name of the additional parameter.

REST Online Lending

The attribute name, always takes the value of mdOrder.

WS

Name of the additional parameter.

Spasibo

Name or the description of an item in any format.

Spasibo2

Name of the parameter describing the details of a line item

ANS..255

Name of the additional parameter.

value

AN..1024

The value of the additional parameter is up to 1024 characters.

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.

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 Access denied
5 The user must change the password
5 The maximum number of payments attempted run out or the session timeout expired
5 Data validation error
7 System error

Request example: 

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:mer="http://engine.paymentgate.ru/webservices/merchant">
 <soapenv:Header> 
      <soapenv:Body>
       <mer:paymentOrder>
          <order orderId="09808814-eb60-4cea-86bb-ed849dbe7ae9" year="2015" month="12" pan="4111111111111111" cvc="123" cardholderName="A Moriarty" language="ru" ip="?">
             <!-Zero or more repetitions:->
             <params name="name" value="value"/>
          </order>
       </mer:paymentOrder>
    </soapenv:Body>
 </soapenv:Envelope>

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

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns1:paymentOrderResponse xmlns:ns1="http://engine.paymentgate.ru/webservices/merchant">
         <return info="Your payment has been processed, redirecting..." redirect="www.ya.ru?MDORDER=6d295b5b-84c3-44cd-adea-c0eaca122465&amp;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&amp;STATE=payment_deposited&amp;ACTION_CODE=0&amp;AUTH_CODE=2" errorCode="0"/>
      </ns1:paymentOrderResponse>
   </soap:Body>
</soap:Envelope>

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

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
       <ns1:paymentOrderResponse xmlns:ns1="http://engine.paymentgate.ru/webservices/merchant">
          <return errorCode="0" info="ВYour payment has been processed, redirecting..." redirect="https://test.paymentgate.ru:443/testpayment/rest/finish3ds.do" acsUrl="https://test.paymentgate.ru/acs/auth/start.do" paReq="eJxVUk1zgjAQ/SsM95KEr1pnjUOLnXqgYxUvvVHYAVQ+DFDUX99EUeshM/t2N2/3vQSmh2Kn/aJo8qqc6MyguoZlXCV5mU70dfj+NNKnHMJMIPorjDuBHAJsmihFLU8metGkBtM5LLwl7jkMTFwSGSaQK5RXRJxFZcshivev809uWzazHCADhALF3OfMtGzHfR4BuWAoowJ5iE27yqoayBlCXHVlK47ctS0gVwCd2PGsbesxIX3fG2lVpTs04qoAokpA7jssOhU1kuqQJzzwvf5yZqdPf0uDcHsM/C8WnNIJENUBSdQiNykzGaWOxujYpmNqAznnISrUDtx1XUqloguCWg3xHkr/UyC9FNLqq4wrAjzUVYmyQ/p3iyHBJr4ZodWDALmBygO5K3r7UB7HrXRvnXxvhdufxGKUdH34kiUb15mZ3k+3WSrnz01qXi79Yw67DFQAiKIhw6OS4cFl9PAR/gAOWr9V"/>
       </ns1:paymentOrderResponse>
    </soap:Body>
 </soap:Envelope>

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.

In case of an incorrect payment attempt, the gateway returns the following response. 

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns1:paymentOrderResponse xmlns:ns1="http://server/webservices/merchant">
         <return info="Operation declined. Please check the data and available balance of the card and retry." redirect="https://yandex.ru?orderId=39f1f59f-1836-7195-8452-1f6900003ad4&amp;lang=ru" errorCode="0"/>
      </ns1:paymentOrderResponse>
   </soap:Body>
</soap:Envelope>

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

If payment attempts are exhausted, the gateway returns the following response. 

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns1:paymentOrderResponse xmlns:ns1="http://engine.server.ru/webservices/merchant">
         <return errorCode="5" errorMessage="Max payments attempted or session timeout occurred"/>
      </ns1:paymentOrderResponse>
   </soap:Body>
</soap:Envelope>

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, then the Store passes it to the gateway using the finishThreeDS method.

Description of finishThreeDS method is given below:

Request parameters:

Name Type Mandatory Description

md

AN..30

Yes

Order number received on its registration.

paRes

ANS

Yes

Response to the payer's authentication request.

Response parameters:

Name Type Mandatory Description

returnUrl

ANS..512

Yes

The URL to which the user is to be redirected in case of a successful payment (and also in case of a failed payment where the failUrl parameter is not passed). 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>.

errorCode

ANS..3

No

Error code.

errorMessage

AN..512

No

Error description in the language passed in the language parameter in the request.

If errorCode=0 and info=«Your order is proceeded, redirecting» – payment was successful. In other cases with an error see the errorMessage 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

Request example: 

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:mer="http://engine.paymentgate.ru/webservices/merchant">
    <soapenv:Header/>
    <soapenv:Body>
       <mer:finishThreeDs>
          <request language="ru" md="8b5b7ee5-eb5a-4cf4-81ec-7153f7ca2864" paRes="eJzFV2mzokoS/Ssd/T4at1kEkRe0EcW+WCCLgH5jBwVRWfXXD2r37ft6eiZ6ZuLFEGFYnKjMypOZp4pinPyaJLydRN01WTEwaZogSz4V8dfPi/k8JKg5+kahYfBGYPjyLcRD+i2g8GWEzRdBvEA/r5gNsJLmZZAuyZBOF28EkU4GwWQaYAk6vS5CFMXxJUlGk0GfXJuiPq2wL+gXnEG+v05rX6M8OLUrJogurKKvCJxaoCiDfHtlquSq8CuKQV4DBvlhsekeo2ZiMBbxCvJgeP0EVOeFucFnI7xnN3iAXxnkMYOJgzZZ4ShGojRKf8KwPwn8T2zJIE+cOT/cgaruJt8kSVJLmkE+YsyUrWtyim6rBTFnkPc3JhnP9SmZZkzE3scM8iO8c3BaoR8ebHom3xPKOP6KaYvql2E9caZpg7ZrVjsG+TZioqDvVwAAlp3HxN6y2ESR/LwE35+J7nMKk0TFCiWnoKb/pxUos/patHn1CPWvAIM8QkGehV0xdpGdpsWuyaexKk/N1895257/RJBhGL4M8y/1NUPwiQiC0sg0IW6K7I/PL6skVk5p/R+ZccGpPhVRUBb3oJ26AiZtXsef3mP7lRvHenjCEEvg3iZXbxFGnN4eCDrHyMkn8munH5j9zio/B3ttgrcmD7DHAj85WjFWkiaPjkg+bS3l6+c/flMZfJElTfvfRPM9ko8evvtzg7JLVuNlPjOtnlVwfrbnbntQ7I+7AtOSQfn63e41k0Hew//G7VXIDwl7TfT1ejePNAdVXfkIMMqH7mYGy9QkoRea8wW61M+L1ElSyOUdhpU05W4jqZPbaGjuylHf5GicEpcYW/MiskkxU96WNYClI6CaFt1TqSuhcc55kyRpTwjnO1gISSgKYVaLqhTPhO5uRL2qXdYQva6F5f46nkA+HrDRxjxiUft+3Sv7NVaLy68fivSNpZbcXqz8SWx80AavEZdc2yKdumXaB6CicLXDcSC7ZGBQWJApKticRPue7IpZGUKASpx9kWwlnPOmwLLmFkABjNwdqGymuyzYOaB0HWiBgc92vGuamjDE/M5X870k3qE5DNwLXwuDbtquOQoO2LxsocPJ7DnmsFuI0yhkCZ+fMgN5OOgHgML7doRiPWHKE4P3d2wweWENwVEC2FZgc8i5LhwFHhgvv7XDonoeVeJx58OR54H2whsHYKzq8oIFwfJpC0aoRFKJrn21D+fmkO2XA2/uVK3eK3kf6eDJGUzUUAAVSQW1xAJNouIiuPJmhlHbQ9WrQSOL9sHLN3FII/TZ3/ce0LqIHi6XAz8/9dvFMOvUdqeIF53ofW52OFLJkXBF6tAfeXFuoWh6ksvFYLhdejdLEVAz0z97DpSacHG7DbkPBzeMjGWHEZHkIuOMdJPh6GRX1wov+9LwlSopS733sLRRSbmw3VReJrcSZJAFQDpkgfLkJptTLSzUYNmdIOrH+TynTYyV0qKmulHTE7zcxZjcqVAGj/zEymCdoZSAfze33tpH8zBV02wGznzWWhIG1d3eBRMC4plnLoeyiYu3nWfl0V2AcErkEx8hvxXKLbSEgR+etrww5EPgm21U0X2s/NyPwzMuYTBFCCZu6T/VS3zVSwBKst+3vnkpWQ0lAjwrKulYI8Ea33nQynKUuDna7DBQxlFFtl4MsIxabtUjiVwdlcZJii5q8tpUa9l3Z50XLbzrQhENAqRjYfYzyUM20FyeO4Kul0lP35x+F9TN0t8Q93hrEFbjswN93VmdvSGMHm8NTdvUlaGug9Amp+4rubo7UhSBjI4wifdnZf5Sqqf7Q6rFD6lOXS4hSiIPLf3/lKrO7+469lepfsOGzeF/kurmweubVKWnVD09n6SY/swXTHynbtMBz7GFObkxeXs5HDtxKxLHICgCez2zyIUbHO9YN508O/GCCLWv3tf2gII28JZYIndcfkuWlJ/x0sbvgMDVoWZh55o6VFVP6Vh1qcsxXrctqElNuXp0YuiLGTKb20SrHDvtepkt3LVzG22yrSh5wuaunBlBt7vswRBzoy1elE48NN0hb2a+P/YD29VkMyg8MAFbE1Lx5MY+Ocd8Znosa9uJgYBzHyPKblPnIJMxJRZs/YxoPDs88iXbUAgc9pSxzl6niXSrm9aJuBhUYx/89uzJsUUVgSicBeVv2jptjjN5ctw280rpz9590uYjLgsKrAMmbjLyq/6c6sUCrvVZtG9LdGZut70slfUyu3DD4ZAP/Poc4K7VlEHXaFK7JLxyU/ioI+PsZayQe7W5sQf91PmeJFcmoWVidQlQOxExkG6Q3Rx4iaCChVonB3J5ktD8uuAiIxyv3GwA0NrwSrmWjRmJmbfDWRdpmZsd8UU4boPzvsFdD8HP0WZBVa0p3/xiZ/6eTFnyIVOX+y7T7fZ61zjaUqieygI1dehY48wt5w/75le7198jmZdksWm/HeEBEJNEb/ApWQF/Ys47Ngi8YHzbaR8+RPdYOqYDf/N03F76/MDVtAphvNHB0FTyItyYRRUM4amouLm9GNtzFkb8/hanqHK7pTdIC2l3GncU7WEIV2eeye1Do2yI4JCxjXZc70o5Lo1aUo+EROxbMVibdyMcJHLcgNCi7rsk2MeVpQWUVuKqOrZ6ZZDO7OaPSMu3i5zTT+s8a0aaGCipQFhRMQr/++n4yO2Pk0VgkcHkIAD/8mSBd7RPp6ovAtea407QOq4jqKejJ1b5FVPNppD3FiFnKXaXziiYB3mejm2na5q0pQrphEVwvNcnhRaoI8nZ2tq1D0VpuMt83h3PzgzX8hbvacINCxbZnLPM8DrRh2CnD2k6coG4KQ+zPdbJTlljBrsVGyXa5bgx6woxZzfa2WvndjXG8sL81cmC/PgeRN6/EX98PT6vnc9L8uOe9PHy/A9JE/bD"/>
       </mer:finishThreeDs>
    </soapenv:Body>
 </soapenv:Envelope>

Response example: 

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
       <ns1:finishThreeDsResponse xmlns:ns1="http://engine.paymentgate.ru/webservices/merchant">
          <return errorCode="0" returnUrl="http://ya.ru?orderId=8b5b7ee5-eb5a-4cf4-81ec-7153f7ca2864"/>
       </ns1:finishThreeDsResponse>
    </soap:Body>
 </soap:Envelope>