Request for payment using Android Pay (androidPay)

The request used for payment via Android Pay is androidPay.

Use the following URL to connect to the Test Service (WSDL):
https://3dsec.sberbank.ru/payment/webservices/merchant-ws?wsdl.

Use the standard requests to the payment gateway for the operations of reversal, refund and payment completion.

Request parameters

The request parameters are given in table below.

Name Type Mandatory Description

merchant

AN..255

Yes

Merchant login in the payment gateway.

orderNumber

ANS..32

Yes

The number (identifier) of the order in the store system is unique for each store within the system – up to 30 characters. If the order number is generated on the Payment Gateway side, this parameter is not mandatory.

paymentToken

String

Yes

A token received from Android Pay and encoded in Base64.

ip

ANS..39

No

IP-address of the buyer. IPv6 is supported in all requests (up to 39 characters).

amount

N..12

No

Payment amount in minimum currency units.

description

ANS..512

No

Description of the order in any format. Only the first 24 characters of this field are transferred to Sberbank's processing for inclusion in the merchant's financial statements.

To enable sending this field to the processing system, contact the technical support service.

language

A2

No

Language in the ISO 639-1 encoding. If the language is not specified, the default language defined in the store settings is used.

additionalParameters

Not applicable

No

Additional parameters of the order that are stored in the merchant personal account for the subsequent viewing. For each additional parameter, use the entry block which includes the following nested parameters.

Name Type Description

key

String

The name of the optional parameter.

value

AN..1024

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

Below is an example of how to use this parameter. 

<entry>
    <key>parameter_1</key>
    <value>value_1</value>
</entry>
<entry>
    <key>parameter_2</key>
    <value>value_2</value>
</entry>

If the merchant has fiscalization set up, when indicating email (the buyer's email address) and/or phone (the buyer's cell phone number) as additional parameters, these parameters are first used to send the fiscal receipt.

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

preAuth

A..5

No

Parameter that defines the necessity of a pre-authorization (putting the amount on hold on the customer's account until its debiting). The following values are available:

  • true – the parameter is enabled, a two-phase payment is made;
  • false – the parameter is disabled, a one-phase payment is made (funds are debited immediately).

If the parameter is not specified in the request, a one-phase payment occurs.

clientId

ANS..255

No

Identifier of the Customer in the Store system. This parameter is used for the binding functionality. May be present if the store is allowed to create bindings.

Specifying this parameter when processing payments with the use of bindings is mandatory. Otherwise, a payment will be unsuccessful.

currencyCode

N3

No

Numeric ISO 4217 code of the payment currency. If this parameter is not specified, it is considered to be equal to the default currency code.

Response parameters

The response parameters are given in table below.

Name Type Mandatory Description

success

A..5

Yes

Designates a successful request. The following values are available:

  • true – request is processed successfully;
  • false – request failed.

data

Not applicable

Yes

It is returned only if the payment was successful and contains one nested parameter (see below).

orderId

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.

The following parameter is returned if bindings are used.

bindingId

The identifier of the previously created binding. Can only be used if the merchant has permission to work with bindings. If this parameter is passed in the given request, it means that:
1. The given order can be paid only using a binding;
2. The payer will be redirected to the payment page on which only entering CVC is required.

The parameters below are required only if additional authentication is used on the ACS of the issuing bank.

acsUrl

On a successful response in case of payment using 3-D Secure. The URL to go to the access control server.

paReq

On a successful response in case of payment using 3-D Secure. Payment Authentication Request – payment authentication request.

termUrl

In case of a successful response, in the case of a payment in which a check was made to ensure that the card belongs to 3-D Secure. The URL to return from the access control server.

error

Not applicable

Yes

This parameter is returned only if the payment failed. Listed below are the nested parameters.

code

Error code.

description

A detailed technical explanation of the error – the contents of this parameter is not to be displayed to the customer.

message

Comprehensive error description – it is intended for displaying to the user.

Error codes

Error code Error text
0

The request has been processed without system errors.

5

Access denied.

5

The user must change the password.

7

System error.

10

Invalid parameter value [paymentToken].

10

Invalid parameter value [orderNumber].

10

Invalid parameter value [merchant].

10

Invalid parameter value [ip].

10

Encryption of the data passed in unsuccessful.

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:androidPay>
         <arg0>
            <merchant>OurBestMerchantLogin</merchant>
            <orderNumber>UAF-203974-DE</orderNumber>
            <language>RU</language>
            <preAuth>true</preAuth>
            <paymentToken>eyJtZXJjaGFudCI6ICJrdXBpdmlwIiwib3JkZXJOdW1iZXIiOiAyMDUxOTIzMzkxLCJwYXltZW50VG9rZW4iOiAie1wiZXBoZW1lcmFsUHVibGljS2V5XCI6XCJrZXlcIixcImVuY3J5cHRlZE1lc3NhZ2VcIjpcIm1lc3NhZ2VcIixcInRhZ1wiOlwidGFnXCJ9In0=</paymentToken>
            <ip>127.0.0.1</ip>
            <amount>230000</amount>
         <currencyCode>643</currencyCode>
         </arg0>
      </mer:androidPay>
   </soapenv:Body>
</soapenv:Envelope>

Response example

Successful payment

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns1:androidPayResponse xmlns:ns1="http://engine.paymentgate.ru/webservices/merchant">
         <return>
            <success>true</success>
            <data>
               <orderId>12312312123</orderId>
            </data>
            <orderStatus errorCode="0"/>
         </return>
      </ns1:androidPayResponse>
   </soap:Body>
</soap:Envelope>

Failed payment

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns1:androidPayResponse xmlns:ns1="http://engine.paymentgate.ru/webservices/merchant">
         <return>
            <success>false</success>
            <error>
               <code>10</code>
               <description>Invalid parameter [orderNumber]</description>
            </error>
            <orderStatus errorCode="0"/>
         </return>
      </ns1:androidPayResponse>
   </soap:Body>
</soap:Envelope>