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



Request for payment using Apple Pay with fiscal data (payment.do)

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

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.

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.

additionalParameters

Not applicable

No

Additional parameters of the order that are stored in the merchant personal account for the subsequent viewing. Each new pair of a parameter name and its value must be separated by a comma. Below is an example of how to use this parameter. 

{
    "firstParamName": "firstParamValue",
    "secondParamName": "secondParamValue"
}

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.

orderBundle

Not applicable

Yes

Block containg the cart of items of the order. The description of the attributes is given below.

additionalOfdParams

Data block for transferring additional parameters of the OFD

Yes

A block with parameters required by OFD. To pass N parameters, a request must contain N «params» blocks, where the «name» attribute contains the parameter name and the value contains its value.

The transfer of this block is possible only when using the following OFDs:

  • ATOL;
  • Business.Ru;
  • Evotor.

orderBundle

orderBundle contains the following elements.

A parameter included in a block and indicated as mandatory is only mandatory within that block. If the section is optional and missing, then the parameters included in it should not be passed.

Name Type Mandatory Description FFD version

orderCreationDate

ANS..21

No

Order creation date in the format YYYY-MM-DDTHH:MM:SS.

All versions.

customerDetails

Not applicable

No

Block containing attributes with data about the customer. The description of the attributes is given below.

(Go to description.)

All versions.

cartItems

Not applicable

Yes

Block with the attributes of the items in the cart. The description of the attributes is given below.

(Go to description.)

All versions.

customerDetails

customerDetails contains the following elements.

A parameter included in a block and indicated as mandatory is only mandatory within that block. If the section is optional and missing, then the parameters included in it should not be passed.

Name Type Mandatory Description FFD version

email

ANS..40

See note below.

Customer's email address, to which the receipt will be sent. Most OFDs support delivery of receipt only to one email address. Some OFDs allow receipt delivery to multiple emails. In this case, the emails should be separated by commas without spaces. Contact your OFD for availability of receipt delivery to multiple emails. It is mandatory to pass one of the two parameters: email or phone.

All versions.

phone

NS..12

See note below.

Customer's phone number. It can be of the following format: ^((+7|7|8)?([0-9]){10})$. Examples:

  • +79000000000
  • 89000000000
  • 9000000000
  • 79000000000

If the number is passed in a separate parameter and in additional parameters, the number specified in this phone parameter will be used.

When using ATOL fiscalization, the phone parameter should be sent in the following format:

The phone number must be passed together with the country code without spaces and additional characters except for the quotation marks (the number «371 2 1234567» must be passed as «+37121234567»). If the phone number belongs to Russia (prefix «+7»), then the value can be passed without a prefix (the number «+79251234567» can be sent as «9251234567»). The maximum string length is 64 characters. One of the fields must be filled in the request: email or phone.

All versions.

contact

ANS..40

No

Customer's preferred way of communication.

All versions.

deliveryInfo

Not applicable

No

Block containing the attributes of the delivery address. The description of the attributes is given below.

(Go to description.)

All versions.

fullName

ANS..100

No

Payer's first name, last name, and patronymic.

1.05 and later versions.

passport

ANS..100

No

The series and number of the payer's passport in the following format: 2222888888.

1.05 and later versions.

inn

N..12

No

Taxpayer identification number. From 10 to 12 digits can be passed.

1.05 and later versions.

It is mandatory to pass one of the two parameters: email or phone.

deliveryInfo

deliveryInfo contains the following elements.

A parameter included in a block and indicated as mandatory is only mandatory within that block. If the section is optional and missing, then the parameters included in it should not be passed.

Name Type Mandatory Description FFD version

deliveryType

ANS..20

No

Delivery method.

All versions.

country

A..2

Yes

The two-letter country code for the delivery country.

All versions.

city

ANS..40

Yes

Delivery city.

All versions.

postAddress

ANS..255

Yes

Delivery address.

All versions.

A parameter included in a block and indicated as mandatory is only mandatory within that block. If the section is optional and missing, then the parameters included in it should not be passed.

cartItems

cartItems contains the following elements.

A parameter included in a block and indicated as mandatory is only mandatory within that block. If the section is optional and missing, then the parameters included in it should not be passed.

Name Type Mandatory Description FFD version

items

Not applicable

Yes

Array of blocks describing line items in the cart. Information about every line item in the cart is passed in a separate block that is included in items.

Do not use «‘)«character combination inside this section, or it will cause an error on the gateway side.

(Go to description.)

All versions.

items

items« contains the following elements.

A parameter included in a block and indicated as mandatory is only mandatory within that block. If the section is optional and missing, then the parameters included in it should not be passed.

Name Type Mandatory Description FFD version

positionId

ANS..12

Yes

Unique identifier of a line item within the order cart.

All versions.

Name

name

Type

ANS..100

Description

REST

Name or the description of an item in any format.

Use
- to pass \ use \«- to pass »

REST Online Lending

For Online Lending functionality, it's necessary to specify a description of the line item in accordance with the Yandex.Market catalog, subject to the following requirements:

  • The following words and character sequences are not allowed: file, exec, insert, as, select, or, procedure, limit, order, and, or, by, asc, desc, delete, update, distinct, having, truncate, replace, handler, like, regex, tz_offset, to_timestamp_tz, bfilename, union, sql-command, abort, alter, analyze, begin, audit, checkpoint, close, cluster, comment, commit, copy, create, deallocate, declare, delete, drop, end, execute, explain, fetch, grant, insert, lock, move, noaudit, notify, prepare, reindex, rename, reset, revoke, rollback, savepoint, select, set, show, shutdown, start, truncate, unlisten, update, vacuum
  • The following special characters are not allowed: ' & – # % | ; =

WS

Name or the description of an item in any format.

Use
- to pass \ use \«- to pass »

WS Online Lending

For online crediting functionality it's necessary to specify a description of the good item in accordance with the Yandex.Market.

ANS..100

Yes

Name or the description of an item in any format.

Use
- to pass \ use \«- to pass »

All versions.

itemDetails

Not applicable

No

Additional block containing the parameters describing a line item. The description of the attributes is given below.

The field size limit is 1024 bytes.

(Go to description.)

All versions.

quantity

N..18

Yes

Element describing the total of items of one positionId and its unit of measurement The description of the attributes is given below.

(Go to description.)

All versions.

itemAmount

N..12

No

The sum of the cost of all line items of one positionId in minimum currency units. Passing itemAmount is mandatory only if the itemPrice parameter was not passed. Otherwise passing of itemAmount is not required. If both parameters – itemPrice and itemAmount – are passed. then itemAmount must be equal to itemPrice * quantity, otherwise, the request will result in an error.

When calculating itemAmount = itemPrice*quantity parameter, the result is rounded up to the second digit after the decimal point. For example, if the calculation result is 100.255, then final value will be 100.26.

All versions.

itemCurrency

N3

No

Currency code of a line item according to ISO 4217. If the parameter is not specified, it is considered to be equal to the order currency.

All versions.

itemCode

ANS..100

Yes

Number (identifier) of a line item in the store system.

All versions.

tax

Not applicable

Only for stores with enabled fiscalization settings

An additional tag with attributes describing the tax. Nested tags are described below.

(Go to description.)

All versions.

itemPrice

N..18

Only for stores with enabled fiscalization settings

The cost of one line item in minimum currency units. Mandatory for merchants using fiscalization.

  • itemPrice cannot be less than 0.
  • itemPrice may be either string or integer.

All versions.

itemAttributes

See description.

Only for stores with enabled fiscalization settings

Block containing the attributes of the item.

See description below.

1.05 and later versions.

==== itemAttributes ==== itemAttributes contains the attributes array in which the attributes of a line item must be specified (see example and table below). <sxh JavaScript> «itemAttributes»:{«attributes»:[{«name»:«paymentMethod»,»value«:«1»},{«name»:«paymentObject»,»value«:«1»}]} </sxh>

Name Type Mandatory Description FFD version

paymentMethod

N..2

Yes

Payment type. Possible values:

  • 1 – full pre-payment before the delivery date of the payment subject;
  • 2 – partial pre-payment before the delivery date of the payment subject;
  • 3 – advance payment;
  • 4 – full payment on the delivery date of the payment subject;
  • 5 – partial payment for the payment subject on the delivery date followed by payment on credit;
  • 6 – delivery of the payment subject on the delivery date without payment followed by payment on credit;
  • 7 – payment for the payment subject after its delivery using payment on credit.

Values are passed in the following priority (indicated in descending order of priority):

  1. Shopping cart from API request.
  2. Fiscalization settings in your personal account.
  3. Default values.

For paymentMethod, the default value is 1 (full prepayment before the transfer of the payment item).

1.05 and later versions.

paymentObject

N..2

Yes

Type of item being paid for. Possible values:

  • 1 – product;
  • 2 – excisable product;
  • 3 – work;
  • 4 – service;
  • 5 – gambling bet;
  • 6 – gambling winnings;
  • 7 – lottery ticket;
  • 8 – lottery winnings;
  • 9 – intellectual property;
  • 10 – payment;
  • 11 – agent's fee;
  • 12 – several subjects;
  • 13 – other payment subject.
  • 14 – property rights;
  • 15 – non-operating income;
  • 16 – insurance premiums: on the amount of expenses that reduce the amount of tax (advance payments) in accordance with paragraph 3.1 of Article 346.21 of the Tax Code of the Russian Federation;
  • 17 – sales tax;
  • 18 – resort tax.

Values are passed in the following priority (indicated in descending order of priority):

  1. Shopping cart from API request.
  2. Fiscalization settings in your personal account.
  3. Default values.

The default value for paymentObject is 1 (item).

1.05 and later versions.

nomenclature

ANS

yes (if markQuantity is passed)

Trade item code in text representation. Maximum length – 32 bytes.

1.05 and later versions.

markQuantity

(Go to description.)

No

Fractional quantity of the labeled item.

1.2 and later versions.

userData

ANS..64

No

Value of user details. May be transferred only after approval by Federal Tax Service.

1.05 and later versions.

agent_info.type

N..2

Mandatory if agent_info object is passed.

Agent type. The following values are available:

  • 1 – banking payment agent;
  • 2 – banking payment subagent;
  • 3 – payment agent;
  • 4 – payment subagent;
  • 5 – attorney;
  • 6 – commission agent;
  • 7 – other agent.

1.05 and later versions.

agent_info.paying.operation

ANS..24

No

Name of the transaction of the paying agent.

1.05 and later versions.

agent_info.paying.phones

array ANS..19

No

Phone numbers array of the payments agent in +N format.

1.05 and later versions.

agent_info.paymentsOperator.phones

Array ANS..19

No

Phone numbers array of the payments operator in +N format.

1.05 and later versions.

agent_info.MTOperator.phones

array ANS..19

No

An array of Money Transfer operator phone numbers in +N format.

1.05 and later versions.

agent_info.MTOperator.name

ANS..64

No

Money Transfer operator name.

1.05 and later versions.

agent_info.MTOperator.address

ANS..256

No

Money Transfer operator address.

1.05 and later versions.

agent_info.MTOperator.inn

N10..12

No

Money Transfer operator TIN.

1.05 and later versions.

supplier_info.phones

Array ANS..19

No

An array of supplier phone numbers in +N format.

1.05 and later versions.

supplier_info.name

ANS..256

No

Supplier name.

1.05 and later versions.

supplier_info.inn

N10..12

No

Supplier TIN.

1.05 and later versions.

==== quantity ==== quantity contains the following elements.

A parameter included in a block and indicated as mandatory is only mandatory within that block. If the section is optional and missing, then the parameters included in it should not be passed.

Name Type Mandatory Description FFD version

value

N..18

Yes

Quantity of line items in given positionId. Use a decimal point as a separator in fractions.

All versions.

measure

ANS..20

Yes

The unit of measurement for the quantity of line item instances.

All versions.

If the FFD is version 1.2 or later, then the following parameters are passed here:

Name Type Mandatory Description FFD version

value

N1

Yes

Quantity of line items in given positionId. For FFD version 1.2+, the value is always 1.

1.2 and later versions.

measure

N..3

Yes

Unit of measurement for the quantity of the payment subject. In case of FFD version 1.2+, if the 'nomenclature' and 'markQuantity' parameters are passed, the value is always 0. In other cases, it can have some value.

1.2 and later versions.

Possible values of measure

Value Description
0 Used for payment subjects that can be sold individually or in units (as well as in the event that the payment subject is a product subject to mandatory labeling with an identification tool (which can be known from mark_code being passed))
10 Gram
11 Kilogram
12 Ton
20 Centimeter
21 Decimeter
22 Meter
30 Square centimeter
31 Square decimeter
32 Square meter
40 Milliliter
41 Liter
42 Cubic meter
50 Kilowatt hour
51 Gigacalorie
70 Day (24h)
71 Hour
72 Minute
73 Second
80 Kilobyte
81 Megabyte
82 Gigabyte
83 Terabyte
255 Applicable when using other units of measurement

==== markQuantity ====

Parameters of markQuantity tag:

A parameter included in a tag and indicated as mandatory is only mandatory within that tag. If the tag itself is not mandatory and is not passed, its included parameters should not be passed.

Name Type Mandatory Description

numerator

N..12

yes

The numerator of the fractional part of the payment subject.

denominator

N..12

yes

The denominator of the fractional part of the payment subject.

==== itemDetails ==== 'itemDetails contains the following elements.

A parameter included in a block and indicated as mandatory is only mandatory within that block. If the section is optional and missing, then the parameters included in it should not be passed.

Name Type Mandatory Description FFD version

itemDetailsParams

ANS..255

Yes

Additional information on a line item. The parameter represents an array of blocks each of which contains information on a certain characteristic of the line item.

(Go to description.)

All versions.

itemDetailsParams

'itemDetailsParams contains the following elements.

A parameter included in a block and indicated as mandatory is only mandatory within that block. If the section is optional and missing, then the parameters included in it should not be passed.

Name Type Mandatory Description FFD version

value

ANS..255

Conditional. Mandatory if itemDetailsParams parameter is present.

Additional information on a line item.

All versions.

Name

name

Type

AN..255

Type2

ANS..255

Description

REST

Name of the parameter describing the details of a line item

WS

Name of the parameter describing the details of a line item

AN..255

Conditional. Mandatory if itemDetailsParams parameter is present.

Name of the parameter describing the details of a line item

All versions.

==== tax ==== tax contains the following elements.

A parameter included in a block and indicated as mandatory is only mandatory within that block. If the section is optional and missing, then the parameters included in it should not be passed.

Name Type Mandatory Description FFD version

taxType

N..2

No

VAT rate. The following values are available:

  • 0 – without VAT;
  • 1 – VAT at rate of 0%;
  • 2 – receipt VAT at rate of 10%;
  • 4 – receipt VAT at calculated rate of 10/110;
  • 6 – receipt VAT at rate of 20%;
  • 7 – receipt VAT at calculated rate of 20/120.

If the cart and fiscalization data are not included in the request, then the default values specified in the personal account are passed to the Fiscal Data Operator (see User Manual for personal account).

All versions.

taxSum

N..18

No

Amount of the tax calculated by the merchant. The amount is specified in minimum currency units

All versions.

==== additionalOfdParams ==== additionalOfdParams contains the following elements.

Name Type Mandatory Description FFD version

agent_info.type

N..2

Mandatory if agent_info object is passed.

Agent type. The following values are available:

  • 1 – banking payment agent;
  • 2 – banking payment subagent;
  • 3 – payment agent;
  • 4 – payment subagent;
  • 5 – attorney;
  • 6 – commission agent;
  • 7 – other agent.

1.05 and later versions.

agent_info.paying.operation

ANS..24

No

Name of the transaction of the paying agent.

1.05 and later versions.

agent_info.paying.phones

array ANS..19

No

Phone numbers array of the payments agent in +N format.

1.05 and later versions.

agent_info.paymentsOperator.phones

Array ANS..19

No

Phone numbers array of the payments operator in +N format.

1.05 and later versions.

agent_info.MTOperator.address

ANS..256

No

Money Transfer operator address.

1.05 and later versions.

agent_info.MTOperator.inn

N10..12

No

Money Transfer operator TIN.

1.05 and later versions.

agent_info.MTOperator.name

ANS..64

No

Money Transfer operator name.

1.05 and later versions.

agent_info.MTOperator.phones

array ANS..19

No

An array of Money Transfer operator phone numbers in +N format.

1.05 and later versions.

supplier_info.phones

Array ANS..19

No

An array of supplier phone numbers in +N format.

1.05 and later versions.

cashier

A..256

No

Cashier full name

1.05 and later versions.

additional_check_props

ANS..16

No

Additional property of the receipt.

1.05 and later versions.

additional_user_props.name

ANS..24

No

Name of the additional property of the user.

1.05 and later versions.

additional_user_props.value

ANS..24

No

Value of the additional property of the user.

1.05 and later versions.

cashier_inn

N..12

No

Cashier's INN

1.2 and later versions.

client.address

ANS..256

No

Customer address.

1.2 and later versions.

client.birth_date

NS10

No

Customer birth date as dd.mm.yyyy

1.2 and later versions.

client.citizenship

N3

No

Country numeric code of the county of Customer's citizenship. The country code is specified according to All-Russian World Countries Classifier (OKSM)

1.2 and later versions.

client.document_code

N2

No

Identification document type numeric code (for example, 21 stands for Russian Passport).

1.2 and later versions.

client.passport_number

NS11

No

Series and number of the payer's passport: 1111 222222

1.2 and later versions.

client.email

ANS..64

No

Customer's email address. Exactly one of the two fields must be passed: email or phone.

1.2 and later versions.

client.phone

NS..19

No

Customer's phone number. Must be passed with the country code without spaces and additional characters (except for + character). For example, the number «+371 2 1234567» should be passed as «+37121234567»). Exactly one of the two fields must be passed: email or phone.

1.2 and later versions.

client.inn

N12

No

INN of the buyer.

1.2 and later versions.

client.name

ANS..256

No

Customer name.

1.2 and later versions.

operatingCheckProps.name

ANS

No

Operation ID The value is «0» until the value of Russia's Federal Tax Service attribute is determined.

1.2 and later versions.

operatingCheckProps.name

ANS

No

Operation ID The value is «0» until the value of Russia's Federal Tax Service attribute is determined.

1.2 and later versions.

operatingCheckProps.timestamp

NS19

No

Date and time of the operation in dd.mm.yyyy HH:MM:SS format

1.2 and later versions.

operatingCheckProps.value

ANS..64

No

Operation data.

1.2 and later versions.

sectoralCheckProps.date

NS10

No

Date of the legislative act of the federal body of executive power that sets forth the requirements for assigning the value of «sectoral attribute». Format: dd.mm.yyyy.

1.2 and later versions.

sectoralCheckProps.federalId

ANS

No

Identifier of federal body of executive power. Must be one of the values from directory of federal bodies of executive power

1.2 and later versions.

sectoralCheckProps.number

N..32

No

Number of the legislative act of the federal body of executive power that sets forth the requirements for assigning the value of «sectoral attribute».

1.2 and later versions.

sectoralCheckProps.value

ANS..256

No

A set of values defined by the legislative act of the federal body of executive power.

1.2 and later versions.

===== 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

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.

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

Yes

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

actionCodeDescription

AN..512

Yes

Response code is a numeric code that designates the result of user's call to the system. Full list of processing response codes and description of these codes is available on a separate page.

amount

N..12

Yes

Payment amount in minimum currency units (kopecks, cents, etc.). Must match the total amount for all line items in the shopping cart.

Before summing up all line items, the product of quantity and price for each good item is rounded to an integer. If the value is followed by 5 or greater after the decimal point, it is rounded up. Below there are examples of rounding.

  1. If quantity = 0.111, and price = 5500, then the result is 611 (610.5 rounded up).
  2. If quantity = 1.455, and price = 6900, then the result is 10040 (10039.5 rounded up).
  3. If quantity = 1.211, and price = 6988, then the result is 8462 (8462.468 rounded down).

Therefore, the «amount» parameter value must be equal to the sum of the line items rounded.

currency

N3

No

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

date

ANS

Yes

The order registration date, expressed in milliseconds since midnight (00:00:00 GMT) January 1, 1970.

ip

ANS..39

Yes

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

The authorization date and time, expressed in milliseconds since midnight (00:00:00 GMT) January 1, 1970.

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

Order status; the parameter can take the following values:

  • CREATED – order is created;
  • APPROVED – order is approved;
  • DEPOSITED – order is completed;
  • DECLINED – the order is declined;
  • REVERSED – order is reversed;
  • REFUND – there has been a refund for this order;

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
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 ==== <sxh javascript> {«merchant»:«Vmerch»,»orderNumber«:«9eac9d14-4430-7e2a-a582-2d3b00096352»,»description«:«descritpion_text», «clientId»:«123»,»paymentToken«:«eyJ2ZXJzaW9uIjoiUlNBX3YxIiwic2lnbmF0dXJlIjoiTUlBR0NTcUdTSWIzRFFFSEFxQ0FNSUFDQVFFeER6QU5CZ2xnaGtnQlpRTUVBZ0VGQURDQUJna3Foa2lHOXcwQkJ3RUFBS0NBTUlJRDVqQ0NBNHVnQXdJQkFnSUlhR0QybWRuTXB3OHdDZ1lJS29aSXpqMEVBd0l3ZWpFdU1Dd0dBMVVFQXd3bFFYQndiR1VnUVhCd2JHbGpZWFJwYjI0Z1NXNTBaV2R5WVhScGIyNGdRMEVnTFNCSE16RW1NQ1FHQTFVRUN3d2RRWEJ3YkdVZ1EyVnlkR2xtYVdOaGRHbHZiaUJCZFhSb2IzSnBkSGt4RXpBUkJnTlZCQW9NQ2tGd2NHeGxJRWx1WXk0eEN6QUpCZ05WQkFZVEFsVlRNQjRYRFRFMk1EWXdNekU0TVRZME1Gb1hEVEl4TURZd01qRTRNVFkwTUZvd1lqRW9NQ1lHQTFVRUF3d2ZaV05qTFhOdGNDMWljbTlyWlhJdGMybG5ibDlWUXpRdFUwRk9SRUpQV0RFVU1CSUdBMVVFQ3d3TGFVOVRJRk41YzNSbGJYTXhFekFSQmdOVkJBb01Da0Z3Y0d4bElFbHVZeTR4Q3pBSkJnTlZCQVlUQWxWVE1Ga3dFd1lIS29aSXpqMENBUVlJS29aSXpqMERBUWNEUWdBRWdqRDlxOE9jOTE0Z0xGRFptMFVTNWpmaXFRSGRiTFBnc2MxTFVtZVkrTTlPdmVnYUphakNIa3d6M2M2T0twYkM5cStoa3dORnhPaDZSQ2JPbFJzU2xhT0NBaEV3Z2dJTk1FVUdDQ3NHQVFVRkJ3RUJCRGt3TnpBMUJnZ3JCZ0VGQlFjd0FZWXBhSFIwY0RvdkwyOWpjM0F1WVhCd2JHVXVZMjl0TDI5amMzQXdOQzFoY0hCc1pXRnBZMkV6TURJd0hRWURWUjBPQkJZRUZBSWtNQXVhN3UxR01aZWtwbG9wbmtKeGdoeEZNQXdHQTFVZEV3RUIvd1FDTUFBd0h3WURWUjBqQkJnd0ZvQVVJL0pKeEUrVDVPOG41c1QyS0d3L29ydjlMa3N3Z2dFZEJnTlZIU0FFZ2dFVU1JSUJFRENDQVF3R0NTcUdTSWIzWTJRRkFUQ0IvakNCd3dZSUt3WUJCUVVIQWdJd2diWU1nYk5TWld4cFlXNWpaU0J2YmlCMGFHbHpJR05sY25ScFptbGpZWFJsSUdKNUlHRnVlU0J3WVhKMGVTQmhjM04xYldWeklHRmpZMlZ3ZEdGdVkyVWdiMllnZEdobElIUm9aVzRnWVhCd2JHbGpZV0pzWlNCemRHRnVaR0Z5WkNCMFpYSnRjeUJoYm1RZ1kyOXVaR2wwYVc5dWN5QnZaaUIxYzJVc0lHTmxjblJwWm1sallYUmxJSEJ2YkdsamVTQmhibVFnWTJWeWRHbG1hV05oZEdsdmJpQndjbUZqZEdsalpTQnpkR0YwWlcxbGJuUnpMakEyQmdnckJnRUZCUWNDQVJZcWFIUjBjRG92TDNkM2R5NWhjSEJzWlM1amIyMHZZMlZ5ZEdsbWFXTmhkR1ZoZFhSb2IzSnBkSGt2TURRR0ExVWRId1F0TUNzd0thQW5vQ1dHSTJoMGRIQTZMeTlqY213dVlYQndiR1V1WTI5dEwyRndjR3hsWVdsallUTXVZM0pzTUE0R0ExVWREd0VCL3dRRUF3SUhnREFQQmdrcWhraUc5Mk5rQmgwRUFnVUFNQW9HQ0NxR1NNNDlCQU1DQTBrQU1FWUNJUURhSEdPdWkrWDJUNDRSNkdWcE43bTJuRWNyNlQ2c01qT2haNU51U28xZWd3SWhBTDFhKy9ocDg4REtKMHN2M2VUM0Z4V2NzNzF4bWJMS0QvUUozbVdhZ3JKTk1JSUM3akNDQW5XZ0F3SUJBZ0lJU1cwdnZ6cVkycGN3Q2dZSUtvWkl6ajBFQXdJd1p6RWJNQmtHQTFVRUF3d1NRWEJ3YkdVZ1VtOXZkQ0JEUVNBdElFY3pNU1l3SkFZRFZRUUxEQjFCY0hCc1pTQkRaWEowYVdacFkyRjBhVzl1SUVGMWRHaHZjbWwwZVRFVE1CRUdBMVVFQ2d3S1FYQndiR1VnU1c1akxqRUxNQWtHQTFVRUJoTUNWVk13SGhjTk1UUXdOVEEyTWpNME5qTXdXaGNOTWprd05UQTJNak0wTmpNd1dqQjZNUzR3TEFZRFZRUUREQ1ZCY0hCc1pTQkJjSEJzYVdOaGRHbHZiaUJKYm5SbFozSmhkR2x2YmlCRFFTQXRJRWN6TVNZd0pBWURWUVFMREIxQmNIQnNaU0JEWlhKMGFXWnBZMkYwYVc5dUlFRjFkR2h2Y21sMGVURVRNQkVHQTFVRUNnd0tRWEJ3YkdVZ1NXNWpMakVMTUFrR0ExVUVCaE1DVlZNd1dUQVRCZ2NxaGtqT1BRSUJCZ2dxaGtqT1BRTUJCd05DQUFUd0Z4R0VHZGRraGRVYVhpV0JCM2JvZ0tMdjNudXVUZUNOL0V1VDRUTlcxV1piTmE0aTBKZDJEU0pPZTdvSS9YWVh6b2pMZHJ0bWNMN0k2Q21FLzFSRm80SDNNSUgwTUVZR0NDc0dBUVVGQndFQkJEb3dPREEyQmdnckJnRUZCUWN3QVlZcWFIUjBjRG92TDI5amMzQXVZWEJ3YkdVdVkyOXRMMjlqYzNBd05DMWhjSEJzWlhKdmIzUmpZV2N6TUIwR0ExVWREZ1FXQkJRajhrbkVUNVBrN3lmbXhQWW9iRCtpdS8wdVN6QVBCZ05WSFJNQkFmOEVCVEFEQVFIL01COEdBMVVkSXdRWU1CYUFGTHV3M3FGWU00aWFwSXFaM3I2OTY2L2F5eVNyTURjR0ExVWRId1F3TUM0d0xLQXFvQ2lHSm1oMGRIQTZMeTlqY213dVlYQndiR1V1WTI5dEwyRndjR3hsY205dmRHTmhaek11WTNKc01BNEdBMVVkRHdFQi93UUVBd0lCQmpBUUJnb3Foa2lHOTJOa0JnSU9CQUlGQURBS0JnZ3Foa2pPUFFRREFnTm5BREJrQWpBNnozS0RVUmFac1liN05jTld5bUsvOUJmdDJROTFUYUtPdnZHY2dWNUN0NG40bVBlYldaK1kxVUVOajUzcHd2NENNREl0MVVRaHNLTUZkMnhkOHpnN2tHZjlGM3dzSVcyV1Q4WnlhWUlTYjFUNGVuMGJtY3ViQ1lraFlRYVpEd21TSFFBQU1ZSUJYakNDQVZvQ0FRRXdnWVl3ZWpFdU1Dd0dBMVVFQXd3bFFYQndiR1VnUVhCd2JHbGpZWFJwYjI0Z1NXNTBaV2R5WVhScGIyNGdRMEVnTFNCSE16RW1NQ1FHQTFVRUN3d2RRWEJ3YkdVZ1EyVnlkR2xtYVdOaGRHbHZiaUJCZFhSb2IzSnBkSGt4RXpBUkJnTlZCQW9NQ2tGd2NHeGxJRWx1WXk0eEN6QUpCZ05WQkFZVEFsVlRBZ2hvWVBhWjJjeW5EekFOQmdsZ2hrZ0JaUU1FQWdFRkFLQnBNQmdHQ1NxR1NJYjNEUUVKQXpFTEJna3Foa2lHOXcwQkJ3RXdIQVlKS29aSWh2Y05BUWtGTVE4WERURTJNVEV5T0RFd05UUXhNMW93THdZSktvWklodmNOQVFrRU1TSUVJSEMvVVBRcWNzOEEreDBYSFh4UDdON1dMY3hiKzV4Wk9POHVydGhLaDlSTE1Bb0dDQ3FHU000OUJBTUNCRVl3UkFJZ1BXZ0RuK2Ixd3ArSGFqNWR5MUJWT3FTODVqVVJMVHA2NkhYMWtwdTVtd0lDSUZ6MXkrZ1p0bEEzdXRJNkhFVUNkMTFIUUJYc3h5ckFpdlJuTEtSQ2kySS9BQUFBQUFBQSIsImhlYWRlciI6eyJ3cmFwcGVkS2V5IjoiWHNQRWpWWXIwWGZWTDY2RlgrV1lySVBCRU9FOHdUVGtrWExtdE14Y3grb0NDbGk4OHNyeHhYRVpYRGU3T0ZSUXVEcENFWStmenpyMkwzRm55NWZnQjdMY2JlZXZIVHpndGRXQUZBbTlSQlJ1NnBNMTNhSlExdVZVUmdJNWEybkVFNWxxVEtLbnhva0FlOUV0S1Bzc0NSUVRHakR0ZnZhSURGenovbFFqNW5xQmt4elJoUXVNZzRpTUE5NU1ycHFRMlZaOExTRmE1QjkyRi9DWjNMdTJtYkZXTkl2VkdmV2pPQTJzTGx6Rzc1aUJ0Y0lRNzE0V0twTEJrZkRuUjU2OU8yZWt5ODBjaVk0Z0ZGc3l4R1FtSUl1SW1oaHErbUlUZmtlMEtrWHY1MUZwcTlSVGl0ZTlJUFBheGxWN1Z5OEswOVlsTkFGN0hYVGhab21NYjF3Rnd3PT0iLCJlcGhlbWVyYWxQdWJsaWNLZXkiOm51bGwsInB1YmxpY0tleUhhc2giOiJqQUJpSGRVQjZDNWZkeWEvL0NnVHJ5MlBhajJ0L3VZUWxVTUFyeGYzNStNPSIsInRyYW5zYWN0aW9uSWQiOiJhNzdjYjg0OTc2OTlhZjkxYTIzZmFjODNjZDJmMGNlMmVmY2EzOTkzYTkxNzNkYzM4ZGIzNjVjM2VjZmIxOWJlIn0sImRhdGEiOiJRdGlXMFovV1k2dTZhQnV1RHVnYmVKbTZhODhoNnM4dFk5cHlidjRzcVd1ZHQ3NmtQNWIyVC9ZdHRkZDM2WXRDalZsTlJ2RWwvSWo3MmhUL0xrSkFsdnlMTmF4U1hjU2dQUnd5NEhvYytrRTFWY0RodG1uTUs5cmZIZ0dIT2phWUJDQW4yVTBNL0RhbGNEU0JXVDVLNnZzT0NCZUo1dE9rNFRTdHBYYUI5QzI2eXo5anorYSthVGNGdkVNVjlkNm1hSjF0ZEV3QkMxd2xLaDhEWTc2UFZHdHdxMnlPZmxuNmVmN1d6M3dITkdLeEN1RytHVGpmZnVXcGVvdThNM0hpelZWaGh5MFJLeCtKZ3p3L2VvcDR1aTJSTENtaFIzeG5XVHJWN1FyMGFWUFhkcTJuUVhrendUMkwzT0dpb2ZST3NZOWx3TEVla0ZFR3dHTnMyc2IzTHk3cFVTQWFMenJlWXJ1K1UyanVzbzZLN2hFVDhxd2tZYlljek9xUVhnQkRweVcyOGFCY21ZMXllUTR3TG5IU0pnTlA1Rm5tbjU0MVBId2RYS29McXdPeDQxVDRoM0VIZzNneVpYRFpCNzk0VVJkVXhwNzZ2b0QyOHlVcXhSN3QrUFJpc1E4PSJ9», «additionalParameters»:{ «recurringFrequency»: «1», «recurringExpiry»:«20241231»}, «orderBundle»:{ «customerDetails»:{«phone»:«9888888888»,»inn«:«516974792202»,»passport«:«4507 443564»},»cartItems«:{«items»:[{«positionId»:1,»name«:«По-аджарски \»Лодочка\» SMALL«,»quantity«:{«value»:«1»,»measure«:«0»},»itemCode«:«270_235.00»,»itemPrice«:23500,»tax«:{«taxType»:0,»taxSum«:0},»itemAttributes«:{«attributes»:[{«name»:«nomenclature»,»value«:«010463003407001221CMK45BrhN0WLf»},{«name»:«paymentMethod»,»value«:«1»},{«name»:«paymentObject»,»value«:«30»},{«name»:«agent_info.type»,»value«:«7»},{«name»:«agent_info.paying.operation»,»value«:«test operation»},{«name»:«agent_info.paying.phones»,»value«:«9161234123»},{«name»:«agent_info.paymentsOperator.phones»,»value«:«9161234456»},{«name»:«agent_info.MTOperator.phones»,»value«:«9161234789»},{«name»:«agent_info.MTOperator.name»,»value«:«MT operator»},{«name»:«agent_info.MTOperator.address»,»value«:«Moscow»},{«name»:«agent_info.MTOperator.inn»,»value«:«8634330204»},{«name»:«supplier_info.phones»,»value«:«9161234333»},{«name»:«supplier_info.name»,»value«:«Supplier»},{«name»:«supplier_info.inn»,»value«:«287381373424»},{«name»:«excise»,»value«:«10.0»},{«name»:«country_code»,»value«:«810»},{«name»:«declaration_number»,»value«:«12332234533»},{«name»:«userData»,»value«:«user data»},{«name»:«markQuantity.numerator»,»value«:«1»},{«name»:«markQuantity.denominator»,»value«:«2»},{«name»:«sectoralItemProps[0].federalId»,»value«:«001»},{«name»:«sectoralItemProps[0].date»,»value«:«10.10.2021»},{«name»:«sectoralItemProps[0].number»,»value«:«123/4567»},{«name»:«sectoralItemProps[0].value»,»value«:«value1»},{«name»:«sectoralItemProps[1].federalId»,»value«:«003»},{«name»:«sectoralItemProps[1].date»,»value«:«11.10.2021»},{«name»:«sectoralItemProps[1].number»,»value«:«321/4567»},{«name»:«sectoralItemProps[1].value»,»value«:«value2»}]}}]}}} </sxh> ==== Пример ответа ==== === Successful payment === <sxh javascript> {«success»:true,»data«:{«orderId»:«96813830-fff3-7fdd-bed7-6276000d813a»,»bindingId«:«78460ed5-65c0-7384-8651-6065000d813a»,»transactionId«:«ec805db4-3119-4d8b-b266-470b0340e6de»},»orderStatus«:{«errorCode»:«0»,»orderNumber«:«138001»,»orderStatus«:2,»actionCode«:0,»actionCodeDescription«:»«,»amount«:23500,»currency«:«643»,»date«:1643031375000,»orderDescription«:«descritpion_text»,»ip«:«10.99.50.35»,»merchantOrderParams«:[{«name»:«browser_language_param»,»value«:«en»},{«name»:«recurringExpiry»,»value«:«20241231»},{«name»:«recurringFrequency»,»value«:«1»},{«name»:«browser_os_param»,»value«:«UNKNOWN»},{«name»:«user_agent»,»value«:«PostmanRuntime/7.28.4»},{«name»:«browser_name_param»,»value«:«UNKNOWN»}],»transactionAttributes«:[],»attributes«:[{«name»:«mdOrder»,»value«:«96813830-fff3-7fdd-bed7-6276000d813a»}],»cardAuthInfo«:{«maskedPan»:«4111111111»,»expiration«:«202412»,»cardholderName«:«Surname Name»,»approvalCode«:«123456»,»paymentSystem«:«VISA»,»secureAuthInfo«:{«eci»:7,»threeDSInfo«:{«cavv»:«TVRJek5EVTJOemc1TVRJek5EVTI=»}},»pan«:«4111111111»},»bindingInfo«:{«clientId»:«123»,»bindingId«:«78460ed5-65c0-7384-8651-6065000d813a»},»authDateTime«:1643031375433,»authRefNum«:«034057509507»,»paymentAmountInfo«:{«paymentState»:«DEPOSITED»,»approvedAmount«:23500,»depositedAmount«:23500,»refundedAmount«:0,»feeAmount«:0,»totalAmount«:23500},»bankInfo«:{«bankName»:«TEST BANK»,»bankCountryCode«:«RU»,»bankCountryName«:«Россия»},»orderBundle«:{«customerDetails»:{«phone»:«9888888888»,»passport«:«*»,»inn«:«**»},»cartItems«:{«items»:[{«positionId»:«1»,»name«:«По-аджарски \»Лодочка\» SMALL«,»quantity«:{«value»:1.0,»measure«:«0»},»itemAmount«:23500,»itemCurrency«:643,»itemCode«:«270_235.00»,»tax«:{«taxType»:0,»taxSum«:0},»itemPrice«:23500,»itemAttributes«:{«attributes»:[{«name»:«nomenclature»,»value«:«010463003407001221CMK45BrhN0WLf»},{«name»:«paymentMethod»,»value«:«1»},{«name»:«paymentObject»,»value«:«30»},{«name»:«agent_info.type»,»value«:«7»},{«name»:«agent_info.paying.operation»,»value«:«test operation»},{«name»:«agent_info.paying.phones»,»value«:«9161234123»},{«name»:«agent_info.paymentsOperator.phones»,»value«:«9161234456»},{«name»:«agent_info.MTOperator.phones»,»value«:«9161234789»},{«name»:«agent_info.MTOperator.name»,»value«:«MT operator»},{«name»:«agent_info.MTOperator.address»,»value«:«Moscow»},{«name»:«agent_info.MTOperator.inn»,»value«:«8634330204»},{«name»:«supplier_info.phones»,»value«:«9161234333»},{«name»:«supplier_info.name»,»value«:«Supplier»},{«name»:«supplier_info.inn»,»value«:«287381373424»},{«name»:«excise»,»value«:«10.0»},{«name»:«country_code»,»value«:«810»},{«name»:«declaration_number»,»value«:«12332234533»},{«name»:«userData»,»value«:«user data»},{«name»:«markQuantity.numerator»,»value«:«1»},{«name»:«markQuantity.denominator»,»value«:«2»},{«name»:«sectoralItemProps[0].federalId»,»value«:«001»},{«name»:«sectoralItemProps[0].date»,»value«:«10.10.2021»},{«name»:«sectoralItemProps[0].number»,»value«:«123/4567»},{«name»:«sectoralItemProps[0].value»,»value«:«value1»},{«name»:«sectoralItemProps[1].federalId»,»value«:«003»},{«name»:«sectoralItemProps[1].date»,»value«:«11.10.2021»},{«name»:«sectoralItemProps[1].number»,»value«:«321/4567»},{«name»:«sectoralItemProps[1].value»,»value«:«value2»}]}}]}},»chargeback«:false,»operations«:[{«amount»:23500,»cardHolder«:«Surname Name»,»authCode«:«123456»}]}} </sxh> === Failed payment === <sxh javascript> { «error»: { «code»: 1, «description»: «Processing Error», «message»: «The funds on the card are not sufficient» }, «success»: false } </sxh>