Инструменты страницы



Request for payment using Apple Pay (payment.do)

The request used for registering an order is «payment.do» (see below).

https://3dsec.sberbank.ru/payment/applepay/payment.do

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

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.

Request parameters

The request parameters are given in table below.

It is necessary to add to the request a header with the definition of the type of contents – «Content-Type: application/json» to ensure that the request is processed correctly.

Name Type Mandatory Description

merchant

AN..255

Yes

Merchant login in the payment gateway.

orderNumber

ANS..32

Yes

Number (identifier) of the order in the store system. It is unique for every store within the Payment Gateway. If the order number is generated on the Payment Gateway side, this parameter is not mandatory.

description

ANS..512

No

Description of the order in free form.

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.

clientID

ANS..255

No

Identifier of the Customer in the Store system. Used to implement the functionality of bindings.

additionalParameters

Not applicable

No

Additional parameters of the order that are stored in the merchant personal account for the subsequent viewing. Additional parameters must be specified in the following format.

«parameter_name»: «parameter_value»

Each new pair of a parameter name and its value must be separated by a comma.

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.

Two-phase payments functionality is available if specifically requested by Merchant from the bank.

This parameter can be passed either as a boolean value (without quotation marks) or as a string (with quotation marks).

paymentToken

AN..8192

Yes

The paymentToken parameter must contain a Base64 encoded value of the paymentData property that was received in PKPaymentToken Object from the Apple Pay system (see Apple Pay documentation). Thus, to send a payment request to the payment gateway, the merchant must:

  1. Receive from the Apple Pay system the PKPaymentToken Object object containing the paymentData property;
  2. Extract the value of the paymentData property and encode it in Base64;
  3. Include the encoded value of the paymentData property as the value of the paymentToken parameter in the payment request that the merchant sends to the payment gateway.

dynamicCallbackUrl

ANS..512

No

This parameter enables dynamic callback functionality. In it, you can pass the address to which all «payment» callback notifications activated for the merchant will be sent. Payment-related notifications are callback notifications about the following events: successful hold, payment rejected by timeout, cardpresent payment rejected, successful debiting, refund, reversal. Notably, payment-unrelated callbacks that are active for the Merchant (enabling/disabling a binding, binding creation) will be sent to static callback URL.

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 block (returned only if the request was successful)

orderId

ANS36

Yes

Identifier of the order in the payment system. It is unique within the system. Missing if order registration failed due to an error detailed in ErrorCode.

error block (returned only if the request resulted in an error)

code

N3

Yes

Error code.

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

message

AN..512

Yes

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

The OrderStatus element contains order status parameters and is returned only if the payment gateway recognized all request parameters as correct. See the list of nested parameters below.

errorCode

ANS..3

No

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

See description of error codes on this page.

orderNumber

ANS..32

No

Number (identifier) of the order in the store system. It is unique for every store within the Payment Gateway. If the order number is generated on the Payment Gateway side, this parameter is not mandatory.

orderStatus

N1

No

The order status in the payment system is defined by the value of this parameter. It is missing if the order has not been found. The following values are available:

  • 0 – order is registered but unpaid;
  • 1 – the preauthorized amount is held (for two-phase payments);
  • 2 – full authorization of the order amount was carried out;
  • 3 – authorization is canceled;
  • 4 – a refund operation was performed for the transaction;
  • 5 – authorization via ACS of the issuing bank was initiated;
  • 6 – authorization is declined.

actionCode

N..5

No

Processing code Full list of processing response codes and description of these codes is available on a separate page.

actionCodeDescription

AN..512

No

Description of the response code in the language that is passed in language parameter of the request.

amount

N..12

No

Payment amount in minimum currency units.

currency

N3

No

ISO 4217 code of the payment currency. If not specified, default value is used.

date

ANS

No

Date of order registration in Unix-time format (POSIX-time).

ip

ANS..39

No

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

merchantOrderParams element

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

AN..20

No

Name of the additional parameter.

value

AN..1024

No

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

attributes element

name

A7

No

Name of the additional parameter.

value

AN..1024

No

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

cardAuthInfo element

pan

N12…19

No

Masked number of the card that has been used for the payment. This parameter is to be specified only after the order has been paid.

In the case of payment via Apple Pay, DPAN is used as the card number: a number associated with the buyer's mobile device and acting as a payment card number in the Apple Pay system.

expiration

ANS

No

Expiry date of the card in the format YYYYMM.

cardholderName

A..200

No

Cardholder's name in Latin characters, if available.

approvalCode

AN6

No

International payment system authorization code. This field has a fixed length (six characters) and can contain digits and Latin letters.

authDateTime

ANS

No

Authorization date and time in Unix time (POSIX time).

terminalId

AN..10

No

Identifier of the terminal in processing through which the payment was made.

authRefNum

AN..24

No

Registration number of the payment authorization that has been assigned to it on the payment registration.

paymentAmountInfo element

approvedAmount

N..12

No

Amount confirmed to be debited.

depositedAmount

N..12

No

The amount in the minimum currency units (for example, in kopecks), confirmed to be debited from the card.

refundedAmount

N..12

No

The refund amount in minimum currency units.

paymentState

A..10

No

Payment status.

totalAmount

N..12

No

Order amount + fee (if applicable to the order).

The bankInfo element contains the following parameters.

bankCountryName

AN..160

No

Name of the country of the issuing bank passed in the language parameter of the request or in the language of the user who has called the method if the language has not been specified in the request.

Error codes from the error parameter

Error code Error text
1

The funds on the card are not sufficient.

4

Invalid parameter value [paymentToken.signature], the check failed.

10

Invalid parameter value [merchant].

10

Invalid parameter value [orderNumber].

10

Invalid parameter value [paymentToken].

10

Invalid parameter value [paymentToken.version].

10

Invalid parameter value [paymentToken.header].

10

Invalid parameter value [paymentToken.signature].

10

Invalid parameter value [paymentToken.header.transactionId].

10

Invalid parameter value [paymentToken.header.wrappedKey].

10

Invalid parameter value [paymentToken.header.publicKeyHash].

10

Authorization is invalid.

Error codes from parameter errorCode

Error code Error text
1

Expected [orderId] or [orderNumber].

7

Transaction is being processed now. Please try again later.

POST request example

{
    "merchant": "merchant_name",
    "orderNumber": "applepay123456794",
    "description": "descritpion_text",
    "paymentToken": "eyJ2ZXJzaW9uIjoiRUNfdjEiLCJkYXRhIjoiNTFhUTNGOXl0Q1YwYTdpQS9mMUh0RGc1TnBvSVZtc2RFa1FvTlpoOW95ZVA3eGgvVDk4dXJkenJDN0dOQ3o4c1FodXpXOVZNWUhGU25DTytTWXo0eDYrTnZwZjdCUzhOcnlUWk1Keldtcml0VUZJVytwVjNvNWY4M0F3OU55c1BCMlAxZGZicS9hZDVzV1RwZTMwTnV2UDltRGhaUStET1M3RzB6MDZSNHRXY0R0VFErT0U5YlI1OHFQRUdnTTRiSmRmUklZb25oQlJrdWY2cGw4aU9PQ0VvS01QN2lRck84Z2IrVGNnSjVZSDdDL3J3enBDUVZjMGQxNWJuME9wbE1SOGwxMDcrMDR4ZVVWT3BUMGI3cHRmYnA3VmVaeHVXaHhSTTlHYlF5QmVkVlJHQ2toN3kyREtZY3BRdjJqM1h2L0NjNzRKaVBZM09DTFVEMEIvS0UwUFo1TnJvUEJFUmZ2a1B4WUFzV1ZmM1E3UUtTcTk4Z3p5UXlrWEpwTmFwcEt6cENDMkNKU09XdzVkenNPWjAiLCAic2lnbmF0dXJlIjoiTUlBR0NTcUdTSWIzRFFFSEFxQ0FNSUFDQVFFeER6QU5CZ2xnaGtnQlpRTUVBZ0VGQURDQUJna3Foa2lHOXcwQkJ3RUFBS0NBTUlJRDVqQ0NBNHVnQXdJQkFnSUlhR0QybWRuTXB3OHdDZ1lJS29aSXpqMEVBd0l3ZWpFdU1Dd0dBMVVFQXd3bFFYQndiR1VnUVhCd2JHbGpZWFJwYjI0Z1NXNTBaV2R5WVhScGIyNGdRMEVnTFNCSE16RW1NQ1FHQTFVRUN3d2RRWEJ3YkdVZ1EyVnlkR2xtYVdOaGRHbHZiaUJCZFhSb2IzSnBkSGt4RXpBUkJnTlZCQW9NQ2tGd2NHeGxJRWx1WXk0eEN6QUpCZ05WQkFZVEFsVlRNQjRYRFRFMk1EWXdNekU0TVRZME1Gb1hEVEl4TURZd01qRTRNVFkwTUZvd1lqRW9NQ1lHQTFVRUF3d2ZaV05qTFhOdGNDMWljbTlyWlhJdGMybG5ibDlWUXpRdFUwRk9SRUpQV0RFVU1CSUdBMVVFQ3d3TGFVOVRJRk41YzNSbGJYTXhFekFSQmdOVkJBb01Da0Z3Y0d4bElFbHVZeTR4Q3pBSkJnTlZCQVlUQWxWVE1Ga3dFd1lIS29aSXpqMENBUVlJS29aSXpqMERBUWNEUWdBRWdqRDlxOE9jOTE0Z0xGRFptMFVTNWpmaXFRSGRiTFBnc2MxTFVtZVkrTTlPdmVnYUphakNIa3d6M2M2T0twYkM5cStoa3dORnhPaDZSQ2JPbFJzU2xhT0NBaEV3Z2dJTk1FVUdDQ3NHQVFVRkJ3RUJCRGt3TnpBMUJnZ3JCZ0VGQlFjd0FZWXBhSFIwY0RvdkwyOWpjM0F1WVhCd2JHVXVZMjl0TDI5amMzQXdOQzFoY0hCc1pXRnBZMkV6TURJd0hRWURWUjBPQkJZRUZBSWtNQXVhN3UxR01aZWtwbG9wbmtKeGdoeEZNQXdHQTFVZEV3RUIvd1FDTUFBd0h3WURWUjBqQkJnd0ZvQVVJL0pKeEUrVDVPOG41c1QyS0d3L29ydjlMa3N3Z2dFZEJnTlZIU0FFZ2dFVU1JSUJFRENDQVF3R0NTcUdTSWIzWTJRRkFUQ0IvakNCd3dZSUt3WUJCUVVIQWdJd2diWU1nYk5TWld4cFlXNWpaU0J2YmlCMGFHbHpJR05sY25ScFptbGpZWFJsSUdKNUlHRnVlU0J3WVhKMGVTQmhjM04xYldWeklHRmpZMlZ3ZEdGdVkyVWdiMllnZEdobElIUm9aVzRnWVhCd2JHbGpZV0pzWlNCemRHRnVaR0Z5WkNCMFpYSnRjeUJoYm1RZ1kyOXVaR2wwYVc5dWN5QnZaaUIxYzJVc0lHTmxjblJwWm1sallYUmxJSEJ2YkdsamVTQmhibVFnWTJWeWRHbG1hV05oZEdsdmJpQndjbUZqZEdsalpTQnpkR0YwWlcxbGJuUnpMakEyQmdnckJnRUZCUWNDQVJZcWFIUjBjRG92TDNkM2R5NWhjSEJzWlM1amIyMHZZMlZ5ZEdsbWFXTmhkR1ZoZFhSb2IzSnBkSGt2TURRR0ExVWRId1F0TUNzd0thQW5vQ1dHSTJoMGRIQTZMeTlqY213dVlYQndiR1V1WTI5dEwyRndjR3hsWVdsallUTXVZM0pzTUE0R0ExVWREd0VCL3dRRUF3SUhnREFQQmdrcWhraUc5Mk5rQmgwRUFnVUFNQW9HQ0NxR1NNNDlCQU1DQTBrQU1FWUNJUURhSEdPdWkrWDJUNDRSNkdWcE43bTJuRWNyNlQ2c01qT2haNU51U28xZWd3SWhBTDFhKy9ocDg4REtKMHN2M2VUM0Z4V2NzNzF4bWJMS0QvUUozbVdhZ3JKTk1JSUM3akNDQW5XZ0F3SUJBZ0lJU1cwdnZ6cVkycGN3Q2dZSUtvWkl6ajBFQXdJd1p6RWJNQmtHQTFVRUF3d1NRWEJ3YkdVZ1VtOXZkQ0JEUVNBdElFY3pNU1l3SkFZRFZRUUxEQjFCY0hCc1pTQkRaWEowYVdacFkyRjBhVzl1SUVGMWRHaHZjbWwwZVRFVE1CRUdBMVVFQ2d3S1FYQndiR1VnU1c1akxqRUxNQWtHQTFVRUJoTUNWVk13SGhjTk1UUXdOVEEyTWpNME5qTXdXaGNOTWprd05UQTJNak0wTmpNd1dqQjZNUzR3TEFZRFZRUUREQ1ZCY0hCc1pTQkJjSEJzYVdOaGRHbHZiaUJKYm5SbFozSmhkR2x2YmlCRFFTQXRJRWN6TVNZd0pBWURWUVFMREIxQmNIQnNaU0JEWlhKMGFXWnBZMkYwYVc5dUlFRjFkR2h2Y21sMGVURVRNQkVHQTFVRUNnd0tRWEJ3YkdVZ1NXNWpMakVMTUFrR0ExVUVCaE1DVlZNd1dUQVRCZ2NxaGtqT1BRSUJCZ2dxaGtqT1BRTUJCd05DQUFUd0Z4R0VHZGRraGRVYVhpV0JCM2JvZ0tMdjNudXVUZUNOL0V1VDRUTlcxV1piTmE0aTBKZDJEU0pPZTdvSS9YWVh6b2pMZHJ0bWNMN0k2Q21FLzFSRm80SDNNSUgwTUVZR0NDc0dBUVVGQndFQkJEb3dPREEyQmdnckJnRUZCUWN3QVlZcWFIUjBjRG92TDI5amMzQXVZWEJ3YkdVdVkyOXRMMjlqYzNBd05DMWhjSEJzWlhKdmIzUmpZV2N6TUIwR0ExVWREZ1FXQkJRajhrbkVUNVBrN3lmbXhQWW9iRCtpdS8wdVN6QVBCZ05WSFJNQkFmOEVCVEFEQVFIL01COEdBMVVkSXdRWU1CYUFGTHV3M3FGWU00aWFwSXFaM3I2OTY2L2F5eVNyTURjR0ExVWRId1F3TUM0d0xLQXFvQ2lHSm1oMGRIQTZMeTlqY213dVlYQndiR1V1WTI5dEwyRndjR3hsY205dmRHTmhaek11WTNKc01BNEdBMVVkRHdFQi93UUVBd0lCQmpBUUJnb3Foa2lHOTJOa0JnSU9CQUlGQURBS0JnZ3Foa2pPUFFRREFnTm5BREJrQWpBNnozS0RVUmFac1liN05jTld5bUsvOUJmdDJROTFUYUtPdnZHY2dWNUN0NG40bVBlYldaK1kxVUVOajUzcHd2NENNREl0MVVRaHNLTUZkMnhkOHpnN2tHZjlGM3dzSVcyV1Q4WnlhWUlTYjFUNGVuMGJtY3ViQ1lraFlRYVpEd21TSFFBQU1ZSUJYekNDQVZzQ0FRRXdnWVl3ZWpFdU1Dd0dBMVVFQXd3bFFYQndiR1VnUVhCd2JHbGpZWFJwYjI0Z1NXNTBaV2R5WVhScGIyNGdRMEVnTFNCSE16RW1NQ1FHQTFVRUN3d2RRWEJ3YkdVZ1EyVnlkR2xtYVdOaGRHbHZiaUJCZFhSb2IzSnBkSGt4RXpBUkJnTlZCQW9NQ2tGd2NHeGxJRWx1WXk0eEN6QUpCZ05WQkFZVEFsVlRBZ2hvWVBhWjJjeW5EekFOQmdsZ2hrZ0JaUU1FQWdFRkFLQnBNQmdHQ1NxR1NJYjNEUUVKQXpFTEJna3Foa2lHOXcwQkJ3RXdIQVlKS29aSWh2Y05BUWtGTVE4WERURTJNVEV3TVRBNU5UY3dObG93THdZSktvWklodmNOQVFrRU1TSUVJQWpSdk9nWkxDa0w5ZmNCZjdOSm5RY3hsd2ltL09ieHkrcEltZ1M0TGRUYU1Bb0dDQ3FHU000OUJBTUNCRWN3UlFJZ1BKaHlkTXE5UDdTaHJFT2RxVk5KUk84QnN1MC93SXNCS0Y1cnlFR0JPSDRDSVFEeWo4Wml3VVV5alRJUFRUZDBKTTlaMExIdGZTQVhOWVN2T0t4eGN3MTlod0FBQUFBQUFBPT0iLCJoZWFkZXIiOnsiZXBoZW1lcmFsUHVibGljS2V5IjoiTUZrd0V3WUhLb1pJemowQ0FRWUlLb1pJemowREFRY0RRZ0FFNUdmb2t2U2Z3WnV3aXYwSGxKVE1MS0dlMS96dWtjejczSFlvVjh5cjNGNWdmZmthVmNQTmptNjFhdFNOZm9UZUxiSnQ1aHBLWkJuSWlwZlVXSXZxMmc9PSIsInB1YmxpY0tleUhhc2giOiJLMG9KcmJiYURVUDh6YitSUEZhTmxVUTdTU2I3T1FEWERVeU9vM0JXdDJzPSIsInRyYW5zYWN0aW9uSWQiOiIyYTNkZjhjNDg0Y2JmMDg1OTgyN2Y0ZDBkZjhkYjY4YjYyNjBlNTIxYWUwZmI4YjI1NDRmNzNiM2RlMDVlYjE5In19",
    "language": "ru",
    "additionalParameters": {},
    "preAuth": "true"
}

Пример ответа

Successful payment

{
    "success": true,
    "data": {
        "orderId": "b926351f-a634-49cf-9484-ccb0a3b8cfad"
    },
    "orderStatus": {
        "errorCode": "0",
        "orderNumber": "229",
        "orderStatus": 1,
        "actionCode": 0,
        "actionCodeDescription": "",
        "amount": 960000,
        "currency": "643",
        "date": 1478682458102,
        "ip": "81.18.144.51",
        "merchantOrderParams": [
            {
                "name": "param2",
                "value": "param2"
            },
            {
                "name": "param1",
                "value": "param1"
            }
        ],
        "attributes": [
            {
                "name": "mdOrder",
                "value": "b926351f-a634-49cf-9484-ccb0a3b8cfad"
            }
        ],
        "cardAuthInfo": {
            "expiration": "201907",
            "cardholderName": "CARD HOLDER",
            "approvalCode": "123456",
            "pan": "520424**0010"
        },
        "authDateTime": 1478682459082,
        "terminalId": "12345678",
        "authRefNum": "111111111111",
        "paymentAmountInfo": {
            "paymentState": "APPROVED",
            "approvedAmount": 960000,
            "depositedAmount": 0,
            "refundedAmount": 0
        },
        "bankInfo": {
            "bankCountryName": "<UNKNOWN>"
        }
    }
}

Failed payment

{
  "error": {
    "code": 10,
    "description": "Processing Error",
    "message": "Authorization is invalid"
  },
  "success": false
}