Introduction

According to Federal Law 54, from 1 July 2017, all Russian Internet resources are required to issue receipts to clients for online payments.
When making settlements with individuals, special cash register equipment (CRE) must be used

Basic questions

  • Who is obliged to cash receipts, a bank or a store? The obligation to cash receipts is imposed on the TSE (trade and service enterprise).
  • I do not know if I need a cash register - You can check if you need to use a cash register here (by clicking the "Do I need a cash register" button)
  • What needs to be done to make everything work? - For correct operation, it is necessary to rent or purchase a cash register, conclude an agreement with the FDO (fiscal data operator), register the cash register with the Federal Tax Service, transmit information about each purchase.
  • Is it possible to cash receipts for online payments at the cash register, which is in my store? - Yes, if it is registered in the CRE register and can be used for online payments, while in the case of making a payment online, the receipt must be sent to the client within 5 minutes from the moment of payment.
  • • I have a cash register Shtrih-M, ATOL (except ATOL 42-FS). Can I connect it to your internet acquiring? - We do not have integration with these cash registers. You can use our online acquiring and cash receipts at any cash register, but for this you will have to integrate your systems yourself. The exception is the connection of Internet acquiring through our partner PayKeeper. The website https://paykeeper.ru/paykeeper/54-fz-internet-magazin/ specifies the types of cash registers with which they are connected. If your cash register is present in this list, then it will be better for you to implement integration through PayKeeper.
  • • How to generate fiscal receipts (fiscalization) when accepting payments in foreign currency? - Federal Law No. 54 is in force on the territory of the Russian Federation, according to which all cash register equipment works only with Russian rubles. Orders paid in foreign currency are not fiscalized. To issue a receipt for payments in foreign currency, conversion is required, but at the moment the payment gateway does not support conversion. To issue receipts for currency transactions, you will need to integrate your resource with the selected cloud cash register directly; this connection method will allow you to convert currency transactions.
  • • What is the attribute of the subject of payment? - All users of cash register equipment are required to indicate the name of the subject of payment (what the payment is being charged for). Depending on your activity, everyone has different payment subjects. Someone provides services, someone sells goods, and someone accepts payments. In order to determine what you took the money from the Buyer for, the Federal Tax Service provided for the attribute of the subject of the payment. Example: If you provided a service and issued a cash receipt in which the attribute of the subject of payment for the service was set to "GOODS" - such a receipt can be recognized as "issued in violation".
  • • What is the attribute of the payment method? - Another important detail of the subject of payment is a attribute of the method of payment. This detail determines the transfer of the subject of payment at the time of payment. In simple words, a modern cash receipt reflects not only the fact of receipt of payment, but also the fact of transfer of the subject of payment (goods, services, work, etc.). The payment method attribute detail is responsible for the fact of recording the transfer of the payment subject and the fact of payment. This detail is mandatory, with the exception of the value "FULL PAYMENT". Example: You have accepted an advance for the subject of payment (a specific product), which is unambiguously determined at the time of payment (when the buyer paid money for it). In this case, you cash the sales receipt, in which you indicate the attribute of the payment method "100% PREPAYMENT" in the subject of the payment. A sales receipt with such a payment attribute indicates that you accepted the payment, but did not hand over the goods. After you hand over the goods, you need to send a closing receipt. This can be done in the personal area of the Internet acquiring in the details of the transaction.
    The payment gateway has the following attributes of the payment method:
    • 100% prepayment - Full prepayment before handing over the payment item
    • o Partial prepayment - Partial prepayment before handing over the subject of payment
    • o Advance payment - An advance payment for a product whose characteristics have not been determined by that time (for example, if a gift card is purchased).
    • o Full payment - Full payment, including taking into account prepayment or advance (preliminary payment) at the time of handing over the subject of payment

Payment gateway features

The payment gateway allows you to accept payments for orders containing information about the Shopping Cart.
The shopping cart provides a detailed Order for the product items for which payment is made within the framework of a single Order.
The request for order registration also transmits the data necessary for the formation of a cash receipt.
If you choose an ecom-cash register from our partners, then all the necessary information will be transferred to the FDO and to the tax service, according to the requirements of FZ-54

Procedure for connecting an ecom checkout

For standard Internet acquiring, you can transfer information about the shopping cart to the cash register in 2 ways:

For the "Internet Acquiring Lite" and "Free amount payment" products:
The transfer of information to the cash register to cash the receipt is provided by the settings in the Personal area.

Instructions for setting up fiscalization:
Instruction manual


At the same time, it is necessary to choose a partner:
Below are the preferential partner rates for Alfa-Bank clients.

1. Orange Data - rent of a cash register for online trading.

How much does it cost:

  • • Connection of the E-com Check Register service is free of charge
  • • The cost of renting 1 Cash Register is 1,900 rubles/month (Taxcom FDO services are included)
  • • The cost of the FMD (fiscal memory device) is 6,900 rubles.(15 months) 11,000 (36 months)

Read more:
https://lk.orangedata.ru/register/?partner_code=3010032

To receive preferential terms, the application for connection must be filled out through the website https://lk.orangedata.ru/register/?partner_code=3010032


2. ATOL Online - rent of a cash register for online trading.

How much does it cost:

  • • The cost of servicing the ATOL Online cloud cash register:
    • o The monthly tariff is 1,500 rubles.
    • o The annual tariff is 18,000 rubles.
    • o The per-receipt tariff – from 10 rubles/receipt
  • • Connecting the service - free of charge
  • • Assistance in registering a cash register with the Federal Tax Service – free of charge
  • • Service from TAXCOM FDO and the First FDO - free of charge
  • • Dedicated manager at the connection stage - free of charge
  • • Cost of fiscal memory device:
    • o for 15 months - 9,200 rubles.
    • o for 36 months - 13,500 rubles.

More details can be found at the link

To get preferential terms, you need to fill out an application for connection.


3. OFD.ru Ferma service - rent of a cash register for online trading.

How much does it cost:

  • Connecting the service - free of charge
  • • Fiscal Data Transmission Services (FDO) from OFD.ru – free of charge

  • The cost of the Ferma service for 1 CRE within the tariffs:

    • o the monthly tariff: 2,100 rubles per month
    • o the annual tariff: 22,200 rubles per year
    • o the 13 months tariff: 24,050 rubles per 13 months
    • o the 15 months tariff: 27,000 rubles per 15 months
    • o the per-receipt tariff: 3,300 rubles for a package of 300 receipts

  • The cost of fiscal memory devices:

    • o For 15 months: 9,200 rubles.
    • o For 36 months: 13,800 rubles.

Read more:
http://alfabank.ofd.ru/


In case of signing an individual contract:

To enable the E-Com Cash Register service, it is necessary to conclude an additional agreement with the bank:
Additional agreement

Instructions for completing the additional agreement:
Instructions for completing the additional agreement

In case of filling out the CONFIRMATION OF ACCESSION (COA), no additional agreement is required.

FAQ

Help with the connection process:
Contact the support service support@ecom.alfabank.ru

Where to send the signed add. agreement:

  • • By courier service:
    Alfa-Bank OJSC,
    18 Andropov Avenue, building 3, Moscow
    to Alexey Koldaev

  • • By Russian Post:
    Alfa-Bank OJSC, 27 Kalanchevskaya str., Moscow, 107078
    to Alexey Koldaev

Need a test environment:
Contact the test environment support service: support@ecom.alfabank.ru

Presentation:
Download

Requirements for requests

Requirements for the generation of order registration requests with a Shopping Cart

In order registration requests (with or without pre-authorization) the Shopping cart is passed in the <orderBundle> parameter.

  • • All product items in the Shopping cart must be expressed in the same currency (if the currency of the item is specified), and must match the currency of the Order.
  • • The sum of all product items in the Shopping cart must be equal to the Order amount;
  • • For each item, the passed <quantity> value is checked. If the value is too large or too small, the request fails.

  • • All parameters of the Shopping cart are validated for compliance with the required format (length).
    If at least one of the above conditions is not met, the Order is considered incorrectly formed and the Payment gateway returns an error.

Requirements for the generation of requests for the order completion with a Shopping cart

When orders are completed, the Shopping cart is transferred in the <depositItems> element.

  • • In case of completion for the full pre-authorized amount, the transfer of the Shopping cart is optional.
  • • The amount of completion in the Shopping cart shall not exceed the pre-authorized amount of the order.
  • • When completing an order for an amount other than the amount of pre-authorization (except for the transfer of the value "0"), a Shopping cart must be transferred.
  • • All product items in the Shopping cart must be expressed in the same currency (if the currency of the items is specified), and must match the currency of the original Order.
  • • New items that are not included in the original order are prohibited from being transferred to the Shopping cart. There is a check of the availability of the specified product in the Shopping cart of the completion request in the initial order. The <positionId>, <name>, <itemCode> elements must match. If at least one of the values does not match, it is considered that this item is not in the Shopping cart of the registration order.
  • • The value of the <quantity> element in the completion request Shopping cart shall not exceed the value of a similar parameter in the registration order Shopping cart.
  • • The value of the <itemAmount> element of the <items> block shall not exceed the value of a similar parameter in the original order.
  • • For each item, the passed <quantity> value is checked. If the value is too large or too small, the request fails.

  • • All parameters of the Shopping cart are validated for compliance with the required format (length).
    If at least one of the above conditions is not met, the order completion request is considered incorrectly formed and the Payment gateway returns an error.

Requirements for the generation of requests for the order return with a Shopping cart

In the request for a refund, the Shopping cart is specified in the <refundItems> block.

  • • In case of a full refund of the Order, the transfer of the Shopping cart is optional.
  • • When returning an order for an amount other than the amount debited (except for the transfer of the value "0"), a Shopping cart must be transferred.
  • • In the case of several returns on orders with a Shopping cart, all of them should be carried out only according to the algorithm of return with a Shopping cart.
  • • The refund amount in the Shopping cart must not exceed the confirmed monetary amount of the original order.
  • • All product items of the Shopping cart must be expressed in the same currency (if the currency of the items is specified), which coincides with the currency of the original Order.
  • • Items that are not included in the original order are prohibited from being transferred to the Shopping cart. The availability of the specified product in the Shopping cart of the return request in the original order is checked. The <positionId>, <name>, <itemCode> elements must match. If at least one of the values does not match, it is considered that this item is missing from the original order.
  • • The value of the <quantity> element in the completion request Shopping cart shall not exceed the value of a similar parameter in the registration order Shopping cart.
  • • The value of the <itemAmount> element of the <items> block shall not exceed the value of a similar parameter in the original order.

  • • All parameters of the Shopping cart are validated for compliance with the required format (length).
    If at least one of the above conditions is not met, the order return request is considered incorrectly generated and the Payment gateway must return an error.

Interaction patterns when using different types of payment

One-phase payment


Two-phase payment


WebServices interface

Request for order registration (WS)

To register an order in the system, the registerOrder. The composition of the product Shopping cart is transferred in the <orderBundle> parameter.
The Requirements for the generation of order registration requests with a Shopping Cart section contains a list of conditions necessary for the correct generation of the request.
Note If the Shopping cart with fiscalization data is not transmitted in the payment request, the default values specified in the settings of the personal area are transmitted to the fiscal data operator (for more information, see the instructions for working with the personal area).
Request parameters:

Name Type Mandatory Description
merchantOrderNumber ANS..32 yes The order number (identifier) in the store's system is unique for each store within the system. If the order number is generated on the payment gateway side, this parameter does not have to be transmitted.
description ANS..512 no Description of the order in any form. To enable sending this field to processing, contact technical support.
amount N..20 yes Payment amount in kopecks (or cents)
currency N3 no The payment currency code is ISO 4217. If not specified, it is considered equal to the default currency code.
language A2 no The language is encoded in ISO 639-1. If not specified, the default language specified in the store settings will be used.
pageView ANS..20 no

The value of this parameter determines which pages of the payment interface should be loaded for the client. Possible values are:

  • DESKTOP – for pages designed to be displayed on PC screens (pages with payment_<locale>.html and errors_<locale>.html will be searched for in the archive of the payment interface pages);
  • MOBILE – for pages designed to be displayed on mobile devices (pages with names mobile_payment_<locale>.html and mobile_errors_<locale>.html will be searched for in the archive of the payment interface pages);

  • If the store has added arbitrary prefixes to their page file names, value of the desired prefix should be passed in the pageView parameter for the corresponding pages to be loaded. For example, if iphone is passed in the parameter, pages with names iphone_payment_<locale>.html and iphone_error_<locale>.html will be searched for in the archive of the payment interface pages.
    where:

    • locale – language of the page encoded in ISO 639-1. For example, ru for Russian or en for English.

If the parameter is missing or does not match the format, the default value is pageView=DESKTOP.

sessionTimeoutSecs N...9 no The order lifetime in seconds. If the parameter is not specified, the value specified in the merchant's settings or the default time (1200 seconds = 20 minutes) will be used. If the expirationDate parameter is present in the request, the value of the sessionTimeoutSecs parameter is ignored.
bindingId AN..255 no ID of the binding created earlier. It can only be used if the store has permission to work with bindings. If this parameter is passed in this request, it means: 1. This order can only be paid using a binding; 2. The payer will be redirected to the payment page, where only CVC input is required.
expirationDate ANS no Date and time of the order lifetime expiration. Format: yyyy-MM-dd'T'HH:mm:ss. If this parameter is not passed in the request, then sessionTimeoutSecs is used to determine the end-of-life time of the order.
returnUrl AN..512 yes The address to which the user must be redirected in case of successful payment. 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>.
failUrl AN..512 no The address to which the user must be redirected in case of failed payment. 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>.
params - no

Tag containing attributes to pass additional parameters of the merchant.

The fields for additional information and its subsequent storage. To pass N parameters, the request must contain N Params tags, where the name attribute contains the name, and the value attribute contains the value:

Name Type Mandatory Description
name AN..20 yes Name of the additional parameter
value AN..1024 yes Value of the additional parameter

These fields can be passed to the Bank processing system to be subsequently displayed in the registries. This functionality can be enabled upon additional agreement with the bank during the integration period.
If sending notifications to a buyer is set up for a seller, the email address of a buyer must be passed in this tag in the email parameter.
clientId AN..255 no

The client's number (ID) in the store's system. It is used to implement the functionality of bindings. It can be present if creating bindings is allowed for the store.

Specifying this parameter when processing payments with the use of bindings is mandatory. Otherwise, a payment will be failed.
merchantLogin AN..255 no To register an order on behalf of a child merchant, specify the merchant login in this parameter.
features ANS..255 no AUTO_PAYMENT - if the request for order registration initiates auto-payments.
orderBundle N/A - Shopping cart of order items. The description is given below.
taxSystem N..2 yes - for fiscalization (for stores without fiscalization settings the parameter is not necessary)

Taxation system, the following values are available:

  • "0" - general;
  • "1" - simplified, income;
  • "2" - simplified, income minus expense;
  • "3" - unified imputed income tax;
  • "4" - unified agricultural tax;
  • "5" - patent taxation system.

By default the following fields are passed to the bank processing system:

  • merchantOrderNumber – order number in the store system;

  • description – order description (no more than 99 characters; %, +, carriage return \r, and line feed \n cannot be used).
    If an additional parameter named merchantOrderId is passed in the order, then its value will be passed to the processing system as the order number (instead of the value of the orderNumber field).


Parameters of the orderBundle tag:
The compulsoriness of parameters is specified for use within the tag. If the tag is optional and not included in the request, then the parameters included in it should not be transferred.

Name Type Mandatory Description
orderCreationDate ANS..21 no Order creation date in the YYYY-MM-DDTHH:MM:SS format
customerDetails - no A block with attributes of buyer data. Its attributes are described below. The transmission limit for each of the enabled parameters is 64 characters.
cartItems - yes A tag with the attributes of the product items of the Shopping cart. Its attributes are . described below.
agent - no A block for transmitting agent data (see the description below).
supplierPhones массив ANS..19 no An array of supplier's phone numbers in the +N format.

Parameters of the agent block

Name Type Mandatory Description
agentType N..2 yes (if a block is transmitted)

Agent type, one of the following values is possible:

  • "1" - bank payment agent;
  • "2" - bank payment subagent;
  • "3" - payment agent;
  • "4" - payment subagent;
  • "5" - designated agent;
  • "6" - commission agent;
  • "7" - other agent.
payingOperation ANS..24 no Name of the payment agent's operation.
payingPhones массив ANS..19 no Array of phone numbers of the payment agent in the +N format.
paymentsOperatorPhones массив ANS..19 no Array of phone numbers of the payment acceptance operator in the +N format.
MTOperatorPhones массив ANS..19 no Array of phone numbers of the transfer operator in the +N format.
MTOperatorName ANS..64 no Name of the transfer operator.
MTOperatorAddress ANS..256 no Address of the transfer operator.
MTOperatorInn N10..12 no TIN of the transfer operator.


Parameters of the customerDetails block:
The compulsoriness of parameters is specified for use within the tag. If the tag is optional and not included in the request, then the parameters included in it should not be transferred.

Name Type Mandatory Description
email ANS..40 no Buyer's email address. You can specify multiple email addresses separated by commas and without spaces - in this case the receipt will be sent to all specified addresses. Be sure to pass one of the two parameters: email or phone.
phone ANS.12 no Buyer's phone number. If the phone includes a country code, the number must begin with a plus sign (+). If the phone is passed without a plus sign (+), the country code should not be specified. Thus, the following options are acceptable: +79998887766; 9998887766. Be sure to pass one of the two parameters: email or phone.
contact ANS..40 no The method of communication with the buyer.
deliveryInfo - no A tag with the attributes of the address for delivery. Its attributes are described below.
fullName ANS..100 no Last name, first name and patronymic of the payer.
passport ANS..100 no The series and number of the payer's passport in the following format: 2222888888.
inn ANS..12 no Taxpayer identification number. It is allowed to transmit 10 or 12 characters.


Parameters of the deliveryInfo:
The compulsoriness of parameters is specified for use within the tag. If the tag is optional and not included in the request, then the parameters included in it should not be transferred.

Name Type Mandatory Description
deliveryType ANS..20 no Type of delivery
country A..2 yes Country of delivery (according to ISO 3166-1)
city ANS..40 yes City of delivery
postAddress ANS..255 yes Address of delivery


Parameters of the cartItemstag:
The compulsoriness of parameters is specified for use within the tag. If the tag is optional and not included in the request, then the parameters included in it should not be transferred.

Name Type Mandatory Description
items N/A yes A tag with parameters containing information on one item in the Shopping cart. The item number is indicated as a tag attribute: positionId, ANS..12, mandatory (unique identifier of the item inside the Order Shopping Cart). A separate items tag must be transferred for each item in the request. The description of the tag parameters is presented below.


Parameters of the itemstag:
The compulsoriness of parameters is specified for use within the tag. If the tag is optional and not included in the request, then the parameters included in it should not be transferred.

Name Type Mandatory Description
name ANS..100 yes The name or description of the product item in free form
itemDetails N/A no An additional tag with the parameters of the description of the product item. Its attributes are described below.
quantity N..18 yes This parameter transfers the total number of items of one positionId. A decimal point is used to indicate fractional numbers. The measure is transferred as an attribute: measure, ANS..20, mandatory (a product item quantity measure).
itemAmount N..18 No (see description) The sum of the cost of all product items of one positionID in minimum currency units. itemAmount is required to be transferred only if the itemPrice parameter was not transferred. Otherwise, itemAmount transfer is not required. If both parameters are transferred in the request: itemPrice and itemAmount, then itemAmount must be equal to ItemPrice quantity, otherwise the request will fail with an error. When calculating the itemAmount = ItemPrice quantity parameter, the result is rounded to the second digit after the decimal separator. For example, if the result of calculations is 100.255, then the final result will be 100.26.
itemCurrency N..3 no The currency code of the product item ISO 4217. If not specified, it is considered equal to the order currency.
itemCode ANS..100 yes The number (identifier) of the product item in the store's system. The parameter must be unique within the request.
discount N/A no An additional tag with attributes describing the discount for the product item. Its attributes are described below.
agentInterest N/A no An additional tag with attributes describing the agent fee for the sale of goods. Its attributes are described below.
tax N/A yes - for fiscalization (for stores without fiscalization settings the parameter is not necessary) A tag with parameters for describing the tax, the description is presented below.
itemPrice N..18 yes - for fiscalization (for stores without fiscalization settings the parameter is not necessary) The cost of one product item of this positionId in money in minimum currency units. Mandatory for merchants with fiscalization
itemAttributes See description no A tag intended for transmitting a set of attributes of a product item. A description of the available attributes is provided below.

Parameters of the itemAttributes tag:
Attributes should be specified as follows

html 
        <attributes  name="attribute_name_1">attribute_value_1</attributes>
<attributes  name="attribute_name_2">attribute_value_2</attributes>
Name Type Mandatory Description
paymentMethod N..2 yes

Attribute of the payment method, the following values are available:

  • "1" - full preliminary payment before the transfer of the subject of payment;
  • "2" - partial preliminary payment until the transfer of the subject of payment;
  • "3" - advance;
  • "4" - full payment at the time of transfer of the subject of payment;
  • "5" - partial payment of the subject of payment at the time of its transfer with subsequent credit payment;
  • "6" - transfer of the subject of payment without its reimbursement at the time of its transfer with subsequent credit payment;
  • "7" - payment of the subject of payment after its transfer with credit payment..
paymentObject N..2 yes

The attribute of the subject of payment, the following values are available:

  • "1" - product;
  • "2" - excisable product;
  • "3" - work;
  • "4" - service;
  • "5" - gambling bet;
  • "6" - gambling winnings;
  • "7" - lottery ticket;
  • "8" - lottery winnings;
  • "9" - provision of IPR (intellectual property results);
  • "10" - payment;
  • "11" - agent fee;
  • "12" - compound subject of payment;
  • "13" - other subject of payment.
nomenclature ANS no The code of the product item in the hexadecimal representation. The maximum length is 32 bytes in HEX encoding.

Example of a representation:
1. 00 00 00 01 00 21 FA 41 00 23 05 41 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 12 00 AB 00
2. 000000010021FA4100230541000000000000000000000000000000001200AB00

Thus, the representation is possible with or without spaces.
The presence of spaces is optional.
supplier_info.phones Array ANS..19 no An array of supplier's phone numbers in the +N format.
supplier_info.name ANS..256 no Supplier's name.
supplier_info.inn N10..12 no Supplier's TIN.
agent_info.type N..2 Mandatory only if the agent_info object is transferred.

Agent type, one of the following values is possible:

  • "1" - bank payment agent;
  • "2" - bank payment subagent;
  • "3" - payment agent;
  • "4" - payment subagent;
  • "5" - designated agent;
  • "6" - commission agent;
  • "7" - other agent.
agent_info.paying.operation ANS..24 no Name of the payment agent's operation.
agent_info.paying.phones массив ANS..19 no Array of phone numbers of the payment agent in the +N format..
agent_info.paymentsOperator.phones массив ANS..19 no Array of phone numbers of the payment acceptance operator in the +N format..
agent_info.MTOperator.phones массив ANS..19 no Array of phone numbers of the transfer operator in the +N format.
agent_info.MTOperator.name ANS..64 no Name of the transfer operator.
agent_info.MTOperator.address ANS..256 no Address of the transfer operator.
agent_info.MTOperator.inn ANS..256 no TIN of the transfer operator.


Parameters of the itemDetails tag:
The compulsoriness of parameters is specified for use within the tag. If the tag is optional and not included in the request, then the parameters included in it should not be transferred.

Name Type Mandatory Description
itemDetailsParams ANS..255 no The parameter transfers the value of a certain characteristic of the product item. The name of the characteristic is indicated as an attribute: name, AN..255, mandatory (the name of the characteristic describing the product item). Each characteristic of a product item must be transferred in a separate itemDetailsParams parameter.


Parameters of the discount tag:
The compulsoriness of parameters is specified for use within the tag. If the tag is optional and not included in the request, then the parameters included in it should not be transferred.

Name Type Mandatory Description
discountType ANS..20 yes Type of discount for a product item
discountValue N..20 yes The value of the discount for the product item


Parameters of the agentInterest tag:
The compulsoriness of parameters is specified for use within the tag. If the tag is optional and not included in the request, then the parameters included in it should not be transferred.

Name Type Mandatory Description
interestType ANS..20 yes Type of agent fee for the product sale
interestValue N..20 yes Value of agent fee for the product sale


Parameters of the tax tag:
The compulsoriness of parameters is specified for use within the tag. If the tag is optional and not included in the request, then the parameters included in it should not be transferred.

Name Type Mandatory Description
taxType N..2 yes

VAT rate, the following values are available:

  • "0" – without VAT;
  • "1" – VAT at the rate of 0%;
  • "2" – receipt VAT at the rate of 10%;
  • "3" – receipt VAT at the rate of 18%;
  • "4" – receipt VAT at the estimated rate 10/110;
  • "5" – receipt VAT at the estimated rate 18/118;
  • "6" – receipt VAT at the rate of 20%;
  • "7" – receipt VAT at the estimated rate 20/120;

Mandatory for sellers with fiscalization
taxSum N..18 no The amount of tax calculated by the seller. Specified in minimum currency units.

Response parameters:

Name Type Mandatory Description
orderId ANS36 no The order number in the payment system. It is unique within the system. It is missing if the order registration failed due to an error detailed in errorCode.
formUrl AN..512 no URL of the payment form to which the client's browser is to be redirected. It is not returned if the order registration failed due to an error detailed in errorCode.
errorCode N3 yes Error code.
errorMessage AN..512 no Error description in the language passed in the language parameter in the request.

Error codes ( errorCode field):

Meaning Description
0 Request processing took place without system errors.
1 Invalid order number.
1 Order with given order number is processed already.
3 Unknown currency.
4 Empty amount.
4 The order number cannot be empty.
4 The return URL cannot be empty.
5 The value of one of the parameters is incorrect.
5 Access denied.
5 The user must change password.
7 System error.
8 There is no mandatory Shopping Cart parameter indicating the name of the missing item.
8 The currency in the Shopping Cart does not match the currency of the order.
8 The amount of items in the Shopping cart does not match the total amount of the order.
8 Non-existent ID of the bonus program.
8 The value of the quantity parameter is too large or too small.

Request example:

html 
        <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:mer="https://ecom.alfabank.ru/api/soap/merchant-ws/">
   <soapenv:Header/>
   <soapenv:Body>
      <mer:registerOrder>
         <order merchantOrderNumber="110a88qerf8kfqdarf" description=" " amount="24000" currency=" " pageView=" " sessionTimeoutSecs="5400" binding=" " expirationDate=" ">
            <!--Optional:-->
            <returnUrl>https://tws.egopay.ru/ab/finish.html</returnUrl>
            <!--Zero or more repetitions:-->
            <params name="param1" value="valueParam1"/>
            <params name="param2" value="valueParam2"/>
            <!--Optional:-->
            <clientId>666</clientId>
            <!--Optional:-->
            <merchantLogin> </merchantLogin>
            <taxSystem>0</taxSystem>
            <!--Optional:-->
             <orderBundle>
               <!-- Optional: -->
               <orderCreationDate>2013-07-12T13:51:00</orderCreationDate>
               <!-- Информация о покупателе -->
               <!-- Optional: -->
               <customerDetails>
                  <!-- Optional: -->
                  <email>johnsmith@mail.ru</email>
                  <!-- Optional: -->
                  <phone>79851231234</phone>
                  <!-- Optional: -->
                  <contact>Mega Tester</contact>
                  <!-- Optional: -->
                  <deliveryInfo>
                     <!-- Optional: -->
                     <deliveryType>courier</deliveryType>
                     <country>RU</country>
                     <city>Moscow</city>
                     <postAddress>Земляной Вал 50А стр.2</postAddress>
                  </deliveryInfo>
               </customerDetails>
 
               <!-- Состав Корзины -->
               <cartItems>
                  <!-- Zero or more repetitions: -->
     
                  <items positionId="1">
                     <name>Metzeler Enduro 3 Sahara</name>
                     <!-- Optional: -->
                     <itemDetails>
                        <!-- Zero or more repetitions: -->
                        <itemDetailsParams name="brand">Metzeler</itemDetailsParams>
                        <itemDetailsParams name="radius">17inch</itemDetailsParams>
                     </itemDetails>
                     <quantity measure="штук">1</quantity>
                     <itemAmount>8000</itemAmount>
                     <itemCurrency>643</itemCurrency>
                     <itemCode>T-M-14</itemCode>
                     <!-- Optional: -->
                     <discount>
                        <!-- Optional: -->
                        <discountType>percent</discountType>
                        <!-- Optional: -->
                        <discountValue>5</discountValue>
                     </discount>
                     <!-- Optional: -->
                     <agentInterest>
                        <!-- Optional: -->
                        <interestType>agentPercent</interestType>
                        <!-- Optional: -->
                        <interestValue>7</interestValue>
                     </agentInterest>
                     <tax>
                        <taxType>1</taxType>
                        <taxSum>111</taxSum>
                     </tax>
                     <itemPrice>8000</itemPrice>
                  </items>
 
                 <items positionId="2">
                     <name>Universal Mirror Enduro</name>
                     <!-- Optional: -->
                     <itemDetails>
                        <!-- Zero or more repetitions: -->
                        <itemDetailsParams name="brand">Noname</itemDetailsParams>
                        <itemDetailsParams name="diameter">12mm</itemDetailsParams>
                     </itemDetails>
                     <quantity measure="штук">1</quantity>
                     <itemAmount>8000</itemAmount>
                     <itemCurrency>643</itemCurrency>
                     <itemCode>NM-15</itemCode>
                     <!-- Optional: -->
                     <discount>
                        <!-- Optional: -->
                        <discountType>percent</discountType>
                        <!-- Optional: -->
                        <discountValue>5</discountValue>
                     </discount>
                     <!-- Optional: -->
                     <agentInterest>
                        <!-- Optional: -->
                        <interestType>agentPercent</interestType>
                        <!-- Optional: -->
                        <interestValue>7</interestValue>
                     </agentInterest>
                     <tax>
                        <taxType>1</taxType>
                        <taxSum>111</taxSum>
                     </tax>
                     <itemPrice>8000</itemPrice>
                  </items>
 
                  <items positionId="3">
                     <name>Warm Grips</name>
                     <!-- Optional: -->
                     <itemDetails>
                        <!-- Zero or more repetitions: -->
                        <itemDetailsParams name="brand">Noname</itemDetailsParams>
                     </itemDetails>
                     <quantity measure="штук">1</quantity>
                     <itemAmount>8000</itemAmount>
                     <itemCurrency>643</itemCurrency>
                     <itemCode>G-16</itemCode>
                     <!-- Optional: -->
                     <discount>
                        <!-- Optional: -->
                        <discountType>percent</discountType>
                        <!-- Optional: -->
                        <discountValue>5</discountValue>
                     </discount>
                     <!-- Optional: -->
                     <agentInterest>
                        <!-- Optional: -->
                        <interestType>agentPercent</interestType>
                        <!-- Optional: -->
                        <interestValue>7</interestValue>
                     </agentInterest>
                     <tax>
                        <taxType>1</taxType>
                        <taxSum>111</taxSum>
                     </tax>
                     <itemPrice>8000</itemPrice>
                  </items>
               </cartItems>
     
            </orderBundle>
                </soapenv:Body>
    
    </soapenv:Envelope>

Response example:

html 
        <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   soap:Body
      <ns1:registerOrderResponse xmlns:ns1="https://ecom.alfabank.ru/api/soap/merchant-ws/">
         <return orderId="531eaa8d-b32d-46dd-8e48-64b873886e70" errorCode="0" errorMessage="Success">
            <formUrl>https://tws.egopay.ru/ab/payment_ru.html?mdOrder=531eaa8d-b32d-46dd-8e48-64b873886e70</formUrl>
         </return>
      /ns1:registerOrderResponse
   /soap:Body
/soap:Envelope

Request for order registration with pre-authorization (WS)

When registering an order, it is necessary to additionally transfer the composition of the product Shopping cart. The Requirements for the generation of order registration requests with a Shopping Cart section contains a list of conditions necessary for the correct generation of the request.
Note If the Shopping cart with fiscalization data is not transmitted in the payment request, the default values specified in the settings of the personal area are transmitted to the fiscal data operator (for more information, see the instructions for working with the personal area).
Request parameters:

Name Type Mandatory Description
merchantOrderNumber ANS..32 yes The order number (identifier) in the store's system is unique for each store within the system. If the order number is generated on the payment gateway side, this parameter does not have to be transmitted.
description ANS..512 no Description of the order in any form. To enable sending this field to processing, contact technical support.
amount N..20 yes Payment amount in kopecks (or cents)
currency N3 no The payment currency code is ISO 4217. If not specified, it is considered equal to the default currency code.
language A2 no The language is encoded in ISO 639-1. If not specified, the default language specified in the store settings will be used.
pageView ANS..20 no

The value of this parameter determines which pages of the payment interface should be loaded for the client. Possible values are:

  • DESKTOP – for pages designed to be displayed on PC screens (pages with payment_<locale>.html and errors_<locale>.html will be searched for in the archive of the payment interface pages);
  • MOBILE – for pages designed to be displayed on mobile devices (pages with names mobile_payment_<locale>.html and mobile_errors_<locale>.html will be searched for in the archive of the payment interface pages);

  • If the store has added arbitrary prefixes to their page file names, value of the desired prefix should be passed in the pageView parameter for the corresponding pages to be loaded. For example, if iphone is passed in the parameter, pages with names iphone_payment_<locale>.html and iphone_error_<locale>.html will be searched for in the archive of the payment interface pages.
    where:

    • locale – language of the page encoded in ISO 639-1. For example, ru for Russian or en for English.

If the parameter is missing or does not match the format, the default value is pageView=DESKTOP.

sessionTimeoutSecs N...9 no The order lifetime in seconds. If the parameter is not specified, the value specified in the merchant's settings or the default time (1200 seconds = 20 minutes) will be used. If the expirationDate parameter is present in the request, the value of the sessionTimeoutSecs parameter is ignored.
bindingId AN..255 no ID of the binding created earlier. It can only be used if the store has permission to work with bindings. If this parameter is passed in this request, it means: 1. This order can only be paid using a binding; 2. The payer will be redirected to the payment page, where only CVC input is required.
expirationDate ANS no Date and time of the order lifetime expiration. Format: yyyy-MM-dd'T'HH:mm:ss. If this parameter is not passed in the request, then sessionTimeoutSecs is used to determine the end-of-life time of the order.
returnUrl AN..512 yes The address to which the user must be redirected in case of successful payment. 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>.
failUrl AN..512 no The address to which the user must be redirected in case of failed payment. 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>.
params - no

Tag containing attributes to pass additional parameters of the merchant.

The fields for additional information and its subsequent storage. To pass N parameters, the request must contain N Params tags, where the name attribute contains the name, and the value attribute contains the value:

Name Type Mandatory Description
name AN..20 yes Name of the additional parameter
value AN..1024 yes Value of the additional parameter

These fields can be passed to the Bank processing system to be subsequently displayed in the registries. This functionality can be enabled upon additional agreement with the bank during the integration period.
If sending notifications to a buyer is set up for a seller, the email address of a buyer must be passed in this tag in the email parameter.
clientId AN..255 no

The client's number (ID) in the store's system. It is used to implement the functionality of bindings. It can be present if creating bindings is allowed for the store.

Specifying this parameter when processing payments with the use of bindings is mandatory. Otherwise, a payment will be failed.
merchantLogin AN..255 no To register an order on behalf of a child merchant, specify the merchant login in this parameter.
features ANS..255 no AUTO_PAYMENT - if the request for order registration initiates auto-payments.
orderBundle N/A - Shopping cart of order items. The description is given below.
taxSystem N..2 yes - for fiscalization (for stores without fiscalization settings the parameter is not necessary)

Taxation system, the following values are available:

  • "0" - general;
  • "1" - simplified, income;
  • "2" - simplified, income minus expense;
  • "3" - unified imputed income tax;
  • "4" - unified agricultural tax;
  • "5" - patent taxation system.
autocompletionDate ANS..19 no The date and time of completion of the two-phase payment in the following format: 2017-12-29T13:02:51.

Note By default the following fields are passed to the bank processing system:

  • merchantOrderNumber – order number in the store system;

  • description – order description (no more than 99 characters; %, +, carriage return \r, and line feed \n cannot be used).
    If an additional parameter named merchantOrderId, is passed in the order, then its value will be passed to the processing system as the order number (instead of the value of the orderNumber field).


orderBundle parameter:
The compulsoriness of parameters is specified for use within the tag. If the tag is optional and not included in the request, then the parameters included in it should not be transferred.

Name Type Mandatory Description
orderCreationDate ANS..21 no Order creation date in the YYYY-MM-DDTHH:MM:SS format
customerDetails N/A no A block with attributes of buyer data. Its attributes are described below. The transmission limit for each of the enabled parameters is 64 characters.
cartItems N/A yes A tag with the attributes of the product items of the Shopping cart. The description is given below.
agent - no A block for transmitting agent data (see the description below).
supplierPhones array ANS..19 no An array of supplier's phone numbers in the +N format.

Parameters of the agent block

Name Type Mandatory Description
agentType N..2 yes (if a block is transmitted)

Agent type, one of the following values is possible:

  • "1" - bank payment agent;
  • "2" - bank payment subagent;
  • "3" - payment agent;
  • "4" - payment subagent;
  • "5" - designated agent;
  • "6" - commission agent;
  • "7" - other agent.
payingOperation ANS..24 no Name of the payment agent's operation.
payingPhones array ANS..19 no Array of phone numbers of the payment agent in the +N format..
paymentsOperatorPhones array ANS..19 no Array of phone numbers of the payment acceptance operator in the +N format..
MTOperatorPhones array ANS..19 no Array of phone numbers of the transfer operator in the +N format.
MTOperatorName ANS..64 no Name of the transfer operator.
MTOperatorAddress ANS..256 no Address of the transfer operator.
MTOperatorInn N10..12 no TIN of the transfer operator.


Parameters of the customerDetails:
The compulsoriness of parameters is specified for use within the tag. If the tag is optional and not included in the request, then the parameters included in it should not be transferred.

Name Type Mandatory Description
email ANS..40 no Buyer's email address. You can specify multiple email addresses separated by commas and without spaces - in this case the receipt will be sent to all specified addresses. Be sure to pass one of the two parameters: email or phone.
phone ANS.12 no Buyer's phone number. If the phone includes a country code, the number must begin with a plus sign (+). If the phone is passed without a plus sign (+), the country code should not be specified. Thus, the following options are acceptable: +79998887766; 9998887766. Be sure to pass one of the two parameters: email or phone.
contact ANS..40 no The method of communication with the buyer.
deliveryInfo N/A no A tag with the attributes of the address for delivery. The description is given below.
fullName ANS..100 no Last name, first name and patronymic of the payer.
passport ANS..100 no The series and number of the payer's passport in the following format: 2222888888.
inn ANS..12 no Taxpayer identification number. It is allowed to transmit 10 or 12 characters.


Parameters of the deliveryInfo:
The compulsoriness of parameters is specified for use within the tag. If the tag is optional and not included in the request, then the parameters included in it should not be transferred.

Name Type Mandatory Description
deliveryType ANS..20 no Type of delivery
country A..2 yes Country of delivery (according to ISO 3166-1)
city ANS..40 yes City of delivery
postAddress ANS..255 yes Address of delivery


Parameters of the cartItems:
The compulsoriness of parameters is specified for use within the tag. If the tag is optional and not included in the request, then the parameters included in it should not be transferred.

Name Type Mandatory Description
items N/A yes An array element with the attributes of the product item in the Shopping cart. The description is given below.


Attributes of the items element:
The compulsoriness of parameters is specified for use within the tag. If the tag is optional and not included in the request, then the parameters included in it should not be transferred.

Name Type Mandatory Description
positionId ANS..12 yes Unique identifier of the product item inside the Order Shopping Cart
name ANS..100 yes The name or description of the product item in free form
itemDetails - no An additional tag with the parameters of the description of the product item. The description is given below.
quantity N..18 yes An element describing the total number of product items of one positionId and their measure. A decimal point is used to indicate fractional numbers. The attribute is specified for this parameter: measure, ANS..20, mandatory (a product item quantity measure).
itemAmount N..18 No (see description) The sum of the cost of all product items of one positionID in minimum currency units. itemAmount is required to be transferred only if the itemPrice parameter was not transferred. Otherwise, itemAmount transfer is not required. If both parameters are transferred in the request: itemPrice and itemAmount, then itemAmount must be equal to ItemPrice quantity, otherwise the request will fail with an error. When calculating the itemAmount = ItemPrice quantity parameter, the result is rounded to the second digit after the decimal separator. For example, if the result of calculations is 100.255, then the final result will be 100.26.
itemCurrency N..3 no The currency code of the product item ISO 4217. If not specified, it is considered equal to the order currency.
itemCode ANS..100 yes The number (identifier) of the product item in the store's system
discount N/A no An additional tag with attributes describing the discount for the product item. The description is given below.
agentInterest N/A no An additional tag with attributes describing the agent fee for the sale of goods. The description is given below.
tax N/A yes - for fiscalization (for stores without fiscalization settings, the parameter is optional) Additional tag with tax description attributes. The description is given below.
itemPrice N..18 yes - for fiscalization (for stores without fiscalization settings, the parameter is optional) The cost of one product item of one positionID in money in minimum currency units. Mandatory for merchants with fiscalization
itemAttributes See description no A tag intended for transmitting a set of attributes of a product item. A description of the available attributes is provided below.

Parameters of the itemAttributes tag:
Attributes should be specified as follows

html 
        <attributes  name="attribute_name_1">attribute_value_1</attributes>
<attributes  name="attribute_name_2">attribute_value_2</attributes>
Name Type Mandatory Description
paymentMethod N..2 yes

Attribute of the payment method, the following values are available:

  • "1" - full preliminary payment before the transfer of the subject of payment;
  • "2" - partial preliminary payment until the transfer of the subject of payment;
  • "3" - advance;
  • "4" - full payment at the time of transfer of the subject of payment;
  • "5" - partial payment of the subject of payment at the time of its transfer with subsequent credit payment;
  • "6" - transfer of the subject of payment without its reimbursement at the time of its transfer with subsequent credit payment;
  • "7" - payment of the subject of payment after its transfer with credit payment..
paymentObject N..2 yes

The attribute of the subject of payment, the following values are available:

  • "1" - product;
  • "2" - excisable product;
  • "3" - work;
  • "4" - service;
  • "5" - gambling bet;
  • "6" - gambling winnings;
  • "7" - lottery ticket;
  • "8" - lottery winnings;
  • "9" - provision of IPR (intellectual property results);
  • "10" - payment;
  • "11" - agent fee;
  • "12" - compound subject of payment;
  • "13" - other subject of payment.
nomenclature ANS no The code of the product item in the hexadecimal representation. The maximum length is 32 bytes in HEX encoding.

Example of a representation:
1. 00 00 00 01 00 21 FA 41 00 23 05 41 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 12 00 AB 00
2. 000000010021FA4100230541000000000000000000000000000000001200AB00

Thus, the representation is possible with or without spaces.
The presence of spaces is optional.
supplier_info.phones Array ANS..19 no An array of supplier's phone numbers in the +N format.
supplier_info.name ANS..256 no Supplier's name.
supplier_info.inn N10..12 no Supplier's TIN.
agent_info.type N..2 Mandatory only if the agent_info object is transferred.

Agent type, one of the following values is possible:

  • "1" - bank payment agent;
  • "2" - bank payment subagent;
  • "3" - payment agent;
  • "4" - payment subagent;
  • "5" - designated agent;
  • "6" - commission agent;
  • "7" - other agent.
agent_info.paying.operation ANS..24 no Name of the payment agent's operation.
agent_info.paying.phones array ANS..19 no Array of phone numbers of the payment agent in the +N format..
agent_info.paymentsOperator.phones array ANS..19 no Array of phone numbers of the payment acceptance operator in the +N format..
agent_info.MTOperator.phones array ANS..19 no Array of phone numbers of the transfer operator in the +N format.
agent_info.MTOperator.name ANS..64 no Name of the transfer operator.
agent_info.MTOperator.address ANS..256 no Address of the transfer operator.
agent_info.MTOperator.inn ANS..256 no TIN of the transfer operator.


Parameters of the itemDetails tag:
The compulsoriness of parameters is specified for use within the tag. If the tag is optional and not included in the request, then the parameters included in it should not be transferred.

Name Type Mandatory Description
itemDetailsParams ANS..255 no Parameter that describes additional information about the item. The description is given below.


Parameters of the itemDetailsParams:
The compulsoriness of parameters is specified for use within the tag. If the tag is optional and not included in the request, then the parameters included in it should not be transferred.

Name Type Mandatory Description
name AN..255 yes Name of the product item detail description parameter


Parameters of the discount:
The compulsoriness of parameters is specified for use within the tag. If the tag is optional and not included in the request, then the parameters included in it should not be transferred.

Name Type Mandatory Description
discountType ANS..20 yes Type of discount for a product item
discountValue N..20 yes The value of the discount for the product item


Parameters of the agentInterest:
The compulsoriness of parameters is specified for use within the tag. If the tag is optional and not included in the request, then the parameters included in it should not be transferred.

Name Type Mandatory Description
interestType ANS..20 yes Type of agent fee for the product sale
interestValue N..20 yes Value of agent fee for the product sale


Parameters of the tax:
The compulsoriness of parameters is specified for use within the tag. If the tag is optional and not included in the request, then the parameters included in it should not be transferred.

Name Type Mandatory Description
taxType N..2 yes

VAT rate, the following values are available:

  • "0" – without VAT;
  • "1" – VAT at the rate of 0%;
  • "2" – receipt VAT at the rate of 10%;
  • "3" – receipt VAT at the rate of 18%;
  • "4" – receipt VAT at the estimated rate 10/110;
  • "5" – receipt VAT at the estimated rate 18/118;
  • "6" – receipt VAT at the rate of 20%;
  • "7" – receipt VAT at the estimated rate 20/120;

Mandatory for sellers with fiscalization
taxSum N..18 no The amount of tax calculated by the seller. Specified in minimum currency units.

Response parameters:

Name Type Mandatory Description
orderId ANS36 no The order number in the payment system. It is unique within the system. It is missing if the order registration failed due to an error detailed in errorCode.
formUrl AN..512 no URL of the payment form to which the client's browser is to be redirected. It is not returned if the order registration failed due to an error detailed in errorCode.
errorCode N3 yes Error code.
errorMessage AN..512 no Error description in the language passed in the language parameter in the request.

Error codes (ErrorCode field):

Meaning Description
0 Request processing took place without system errors
1 Invalid order number
1 Order with given order number is processed already
3 Currency is not defined
4 Empty amount
4 The order number cannot be empty
4 The return URL cannot be empty
5 The value of one of the parameters is incorrect
5 Access denied
5 The user must change password
7 System error
8 There is no mandatory parameter of the Shopping Cart indicating the name of the missing item
8 The currency in the Shopping Cart does not match the currency of the order
8 The amount of product items in the Shopping cart does not match the total amount of the order
8 The quantity value is too large or too small

Request example:

html 
        <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:mer="https://ecom.alfabank.ru/api/soap/merchant-ws/">
   <soapenv:Header/>
   <soapenv:Body>
      <mer:registerOrderPreAuth>
         <order merchantOrderNumber="23a89ioouygnuygjhv" description="short" amount="24000" currency="643" language="ru" pageView=" " sessionTimeoutSecs="5400" bindingId=" ">
            <returnUrl>https://tws.egopay.ru/ab/finish.html</returnUrl>
            <!--Zero or more repetitions:-->
            <params name=" " value=" "/>
            <!--Optional:-->
            <clientId>666</clientId>
            <!--Optional:-->
            <merchantLogin> </merchantLogin>
            <taxSystem>0</taxSystem>
             
             <orderBundle>
               <!-- Optional: -->
               <orderCreationDate>2013-07-12T13:51:00</orderCreationDate>
               <!-- Информация о покупателе -->
               <!-- Optional: -->
               <customerDetails>
                  <!-- Optional: -->
                  <email>johnsmith@mail.ru</email>
                  <!-- Optional: -->
                  <phone>79851231234</phone>
                  <!-- Optional: -->
                  <contact>Mega Tester</contact>
                  <!-- Optional: -->
                  <deliveryInfo>
                     <!-- Optional: -->
                     <deliveryType>courier</deliveryType>
                     <country>RU</country>
                     <city>Moscow</city>
                     <postAddress>Земляной Вал 50А стр.2</postAddress>
                  </deliveryInfo>
               </customerDetails>
 
               <!-- Состав Корзины -->
               <cartItems>
                  <!-- Zero or more repetitions: -->
                  <items positionId="1">
                     <name>Metzeler Enduro 3 Sahara</name>
                     <!-- Optional: -->
                     <itemDetails>
                        <!-- Zero or more repetitions: -->
                        <itemDetailsParams name="brand">Metzeler</itemDetailsParams>
                        <itemDetailsParams name="radius">17inch</itemDetailsParams>
                     </itemDetails>
                     <quantity measure="штук">1</quantity>
                     <itemAmount>8000</itemAmount>
                     <itemCurrency>643</itemCurrency>
                     <itemCode>T-M-14</itemCode>
                     <!-- Optional: -->
                     <discount>
                        <!-- Optional: -->
                        <discountType>percent</discountType>
                        <!-- Optional: -->
                        <discountValue>5</discountValue>
                     </discount>
                     <!-- Optional: -->
                     <agentInterest>
                        <!-- Optional: -->
                        <interestType>agentPercent</interestType>
                        <!-- Optional: -->
                        <interestValue>7</interestValue>
                     </agentInterest>
                     <tax>
                        <taxType>1</taxType>
                        <taxSum>111</taxSum>
                     </tax>
                     <itemPrice>8000</itemPrice>
                  </items>
 
                  <items positionId="2">
                     <name>Universal Mirror Enduro</name>
                     <!-- Optional: -->
                     <itemDetails>
                        <!-- Zero or more repetitions: -->
                        <itemDetailsParams name="brand">Noname</itemDetailsParams>
                        <itemDetailsParams name="diameter">12mm</itemDetailsParams>
                     </itemDetails>
                     <quantity measure="штук">1</quantity>
                     <itemAmount>8000</itemAmount>
                     <itemCurrency>643</itemCurrency>
                     <itemCode>NM-15</itemCode>
                     <!-- Optional: -->
                     <discount>
                        <!-- Optional: -->
                        <discountType>percent</discountType>
                        <!-- Optional: -->
                        <discountValue>5</discountValue>
                     </discount>
                     <!-- Optional: -->
                     <agentInterest>
                        <!-- Optional: -->
                        <interestType>agentPercent</interestType>
                        <!-- Optional: -->
                        <interestValue>7</interestValue>
                     </agentInterest>
                     <tax>
                        <taxType>1</taxType>
                        <taxSum>111</taxSum>
                     </tax>
                     <itemPrice>8000</itemPrice>
                  </items>
 
                  <items positionId="3">
                     <name>Warm Grips</name>
                     <!-- Optional: -->
                     <itemDetails>
                        <!-- Zero or more repetitions: -->
                        <itemDetailsParams name="brand">Noname</itemDetailsParams>
                     </itemDetails>
                     <quantity measure="штук">1</quantity>
                     <itemAmount>8000</itemAmount>
                     <itemCurrency>643</itemCurrency>
                     <itemCode>G-16</itemCode>
                     <!-- Optional: -->
                     <discount>
                        <!-- Optional: -->
                        <discountType>percent</discountType>
                        <!-- Optional: -->
                        <discountValue>5</discountValue>
                     </discount>
                     <!-- Optional: -->
                     <agentInterest>
                        <!-- Optional: -->
                        <interestType>agentPercent</interestType>
                        <!-- Optional: -->
                        <interestValue>7</interestValue>
                     </agentInterest>
                     <tax>
                        <taxType>1</taxType>
                        <taxSum>111</taxSum>
                     </tax>
                     <itemPrice>8000</itemPrice>
                  </items>
               </cartItems>
 
            </orderBundle>
 
         </order>
      </mer:registerOrderPreAuth>
   </soapenv:Body>
</soapenv:Envelope>

Response example:

html 
        <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns1:registerOrderPreAuthResponse xmlns:ns1="https://ecom.alfabank.ru/api/soap/merchant-ws/">
         <return orderId="8c76c56b-426c-435d-a24c-1c0927dd6fca" errorCode="0" errorMessage="Success">
            <formUrl>https://tws.egopay.ru/ab/payment_ru.html?mdOrder=8c76c56b-426c-435d-a24c-1c0927dd6fca</formUrl>
         </return>
      </ns1:registerOrderPreAuthResponse>
   </soap:Body>
</soap:Envelope>

Completion for the full amount of pre-authorization (WS)

To request the debit of the full amount of pre-authorization, the depositOrder request is used.
This operation can be performed if there are appropriate rights in the system.
Request parameters:

Name Type Mandatory Description
orderId AN..64 yes The order number in the payment system. It is unique within the system.
depositAmount N..5 yes To complete for the full amount of pre-authorization, you must transfer the full amount of the order in money or 0 in the request. If you do not specify the depositAmount parameter, the completion will also occur for the entire pre-authorized amount..
language A2 no The language is encoded in ISO 639-1. If not specified, it is assumed that the language is Russian. The error message will be returned in this language.
agent - no A block for transmitting agent data (see the description below).
supplierPhones array ANS..19 no An array of supplier's phone numbers in the +N format.

Parameters of the agent

Name Type Mandatory Description
agentType N..2 yes (if a block is transmitted)

Agent type, one of the following values is possible:

  • "1" - bank payment agent;
  • "2" - bank payment subagent;
  • "3" - payment agent;
  • "4" - payment subagent;
  • "5" - designated agent;
  • "6" - commission agent;
  • "7" - other agent.
payingOperation ANS..24 no Name of the payment agent's operation.
payingPhones array ANS..19 no Array of phone numbers of the payment agent in the +N format..
paymentsOperatorPhones array ANS..19 no Array of phone numbers of the payment acceptance operator in the +N format..
MTOperatorPhones array ANS..19 no Array of phone numbers of the transfer operator in the +N format.
MTOperatorName ANS..64 no Name of the transfer operator.
MTOperatorAddress ANS..256 no Address of the transfer operator.
MTOperatorInn N10..12 no TIN of the transfer operator.

Response parameters:

Name Type Mandatory Description
errorCode N3 yes Error code.
errorMessage AN..512 no Error description in the language passed in the language parameter in the request.

Error codes (ErrorCode field):

Meaning Description
0 Request processing took place without system errors
5 The deposit amount exceeds the reserved amount
5 The deposit amount must be greater than zero or at least one ruble
5 Access denied
5 The user must change password
6 Invalid order number
6 orderId not set
7 The payment must be in the correct state
7 System error
8 The specified completion amount does not match the full amount of the order. A Shopping Cart is needed to complete an incomplete amount of pre-authorization

Request example:

html 
        <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:mer="https://ecom.alfabank.ru/api/soap/merchant-ws/">
   <soapenv:Header/>
   <soapenv:Body>
      <mer:depositOrder>
         <order language="ru" orderId="8c76c56b-426c-435d-a24c-1c0927dd6fca" depositAmount=" ">
            <!--Optional:-->
            <!--Zero or more repetitions:-->
            <params name=" " value=" "/>
         </order>
      </mer:depositOrder>
   </soapenv:Body>
</soapenv:Envelope>

Response example:

html 
        <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns1:depositOrderResponse xmlns:ns1="https://ecom.alfabank.ru/api/soap/merchant-ws/">
         <return errorCode="0"/>
      </ns1:depositOrderResponse>
   </soap:Body>
</soap:Envelope>

Completion request for partial amount of pre-authorization (WS)

To request the deposit of a partial amount of pre-authorization, you can use the depositOrder with the mandatory indication of the Shopping cart.
To access this operation, the user shall have the appropriate rights in the system.
The "Requirements for the generation of requests for the order completion with a Shopping cart" contains a list of conditions necessary for the correct generation of the request.
Request parameters:

Name Type Mandatory Description
orderId AN..64 yes The order number in the payment system. It is unique within the system.
depositAmount N..5 yes The debit amount in the order currency (in minimum units). It must match the total amount of the debit for all product items in the Completion Shopping cart.
language A2 no The language is encoded in ISO 639-1. If not specified, it is assumed that the language is Russian. The error message will be returned in this language.
depositItems - yes A block with the attributes of the product items of the Shopping cart. The description is is given below.
agent - no A block for transmitting agent data (see the description below).
supplierPhones array ANS..19 no An array of supplier's phone numbers in the +N format.

Parameters of the agent

Name Type Mandatory Description
agentType N..2 yes (if a block is transmitted)

Agent type, one of the following values is possible:

  • "1" - bank payment agent;
  • "2" - bank payment subagent;
  • "3" - payment agent;
  • "4" - payment subagent;
  • "5" - designated agent;
  • "6" - commission agent;
  • "7" - other agent.
payingOperation ANS..24 no Name of the payment agent's operation.
payingPhones array ANS..19 no Array of phone numbers of the payment agent in the +N format..
paymentsOperatorPhones array ANS..19 no Array of phone numbers of the payment acceptance operator in the +N format..
MTOperatorPhones array ANS..19 no Array of phone numbers of the transfer operator in the +N format.
MTOperatorName ANS..64 no Name of the transfer operator.
MTOperatorAddress ANS..256 no Address of the transfer operator.
MTOperatorInn N10..12 no TIN of the transfer operator.


Parameters of the depositItems:
The compulsoriness of parameters is specified for use within the tag. If the tag is optional and not included in the request, then the parameters included in it should not be transferred.

Name Type Mandatory Description
items - yes An array element with the attributes of the product item in the Shopping cart. The description is given below**.


Attributes of the items:
The compulsoriness of parameters is specified for use within the tag. If the tag is optional and not included in the request, then the parameters included in it should not be transferred.

Name Type Mandatory Description
positionId ANS..12 yes Unique identifier of the product item inside the Order Shopping Cart
name ANS..100 yes The name or description of the product item in free form
itemDetails N/A no An additional tag with the parameters of the description of the product item. The description is given below. is given below.
quantity N..18 yes An element describing the total number of product items of one positionId and their measure. To specify fractional numbers, use a decimal point. For this parameter, the attribute is specified: measure, ..20, mandatory (a product item quantity measure).
itemAmount N..18 No (see description) The sum of the cost of all product items of one positionID in minimum currency units. itemAmount is required to be transferred only if the itemPrice parameter was not transferred. Otherwise, itemAmount transfer is not required. If both parameters are transferred in the request: itemPrice and itemAmount, then itemAmount must be equal to ItemPrice quantity, otherwise the request will fail with an error. When calculating the itemAmount = ItemPrice quantity parameter, the result is rounded to the second digit after the decimal separator. For example, if the result of calculations is 100.255, then the final result will be 100.26.
itemCurrency N..3 no The currency code of the product item ISO 4217. If not specified, it is considered equal to the order currency.
itemCode ANS..100 yes The number (identifier) of the product item in the store's system
discount N/A no An additional tag with attributes describing the discount for the product item. The description is given below.
agentInterest - no An additional tag with attributes describing the agent fee for the sale of goods
tax - yes - for fiscalization (for stores without fiscalization settings the parameter is not necessary) Additional tag with tax description attributes.
itemPrice N..18 yes - for fiscalization (for stores without fiscalization settings the parameter is not necessary) The cost of one product item of one positionId in minimum currency units. Mandatory for merchants with fiscalization
itemAttributes See description no A tag intended for transmitting a set of attributes of a product item. A description of the available attributes is provided below.

Parameters of the itemAttributes:
Attributes should be specified as follows

html 
        <attributes  name="attribute_name_1">attribute_value_1</attributes>
<attributes  name="attribute_name_2">attribute_value_2</attributes>
Name Type Mandatory Description
paymentMethod N..2 yes

Attribute of the payment method, the following values are available:

  • "1" - full preliminary payment before the transfer of the subject of payment;
  • "2" - partial preliminary payment until the transfer of the subject of payment;
  • "3" - advance;
  • "4" - full payment at the time of transfer of the subject of payment;
  • "5" - partial payment of the subject of payment at the time of its transfer with subsequent credit payment;
  • "6" - transfer of the subject of payment without its reimbursement at the time of its transfer with subsequent credit payment;
  • "7" - payment of the subject of payment after its transfer with credit payment..
paymentObject N..2 yes

The attribute of the subject of payment, the following values are available:

  • "1" - product;
  • "2" - excisable product;
  • "3" - work;
  • "4" - service;
  • "5" - gambling bet;
  • "6" - gambling winnings;
  • "7" - lottery ticket;
  • "8" - lottery winnings;
  • "9" - provision of IPR (intellectual property results);
  • "10" - payment;
  • "11" - agent fee;
  • "12" - compound subject of payment;
  • "13" - other subject of payment.
nomenclature ANS no The code of the product item in the hexadecimal representation. The maximum length is 32 bytes in HEX encoding.

Example of a representation:
1. 00 00 00 01 00 21 FA 41 00 23 05 41 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 12 00 AB 00
2. 000000010021FA4100230541000000000000000000000000000000001200AB00

Thus, the representation is possible with or without spaces.
The presence of spaces is optional.
supplier_info.phones Array ANS..19 no An array of supplier's phone numbers in the +N format.
supplier_info.name ANS..256 no Supplier's name.
supplier_info.inn N10..12 no Supplier's TIN.
agent_info.type N..2 Mandatory only if the agent_info object is transferred.

Agent type, one of the following values is possible:

  • "1" - bank payment agent;
  • "2" - bank payment subagent;
  • "3" - payment agent;
  • "4" - payment subagent;
  • "5" - designated agent;
  • "6" - commission agent;
  • "7" - other agent.
agent_info.paying.operation ANS..24 no Name of the payment agent's operation.
agent_info.paying.phones array ANS..19 no Array of phone numbers of the payment agent in the +N format..
agent_info.paymentsOperator.phones array ANS..19 no Array of phone numbers of the payment acceptance operator in the +N format..
agent_info.MTOperator.phones array ANS..19 no Array of phone numbers of the transfer operator in the +N format.
agent_info.MTOperator.name ANS..64 no Name of the transfer operator.
agent_info.MTOperator.address ANS..256 no Address of the transfer operator.
agent_info.MTOperator.inn ANS..256 no TIN of the transfer operator.


Parameters of the itemDetails:
The compulsoriness of parameters is specified for use within the tag. If the tag is optional and not included in the request, then the parameters included in it should not be transferred.

Name Type Mandatory Description
itemDetailsParams ANS..255 no Параметр описывающий дополнительную информацию по товарной позиции

Attributes of the itemDetailsParams parameter:
The compulsoriness of parameters is specified for use within the tag. If the tag is optional and not included in the request, then the parameters included in it should not be transferred.

Name Type Mandatory Description
name AN..255 yes Name of the product item detail description parameter


Parameters of the discount:
The compulsoriness of parameters is specified for use within the tag. If the tag is optional and not included in the request, then the parameters included in it should not be transferred.

Name Type Mandatory Description
discountType ANS..20 yes Type of discount for a product item
discountValue N..20 yes The value of the discount for the product item

Parameters of the agentInterest:
The compulsoriness of parameters is specified for use within the tag. If the tag is optional and not included in the request, then the parameters included in it should not be transferred.

Name Type Mandatory Description
interestType ANS..20 yes Type of agent fee for the product sale
interestValue N..20 yes Value of agent fee for the product sale

Parameters of the tax:
The compulsoriness of parameters is specified for use within the tag. If the tag is optional and not included in the request, then the parameters included in it should not be transferred.

Name Type Mandatory Description
taxType N..2 yes

VAT rate, the following values are available:

  • "0" – without VAT;
  • "1" – VAT at the rate of 0%;
  • "2" – receipt VAT at the rate of 10%;
  • "3" – receipt VAT at the rate of 18%;
  • "4" – receipt VAT at the estimated rate 10/110;
  • "5" – receipt VAT at the estimated rate 18/118;
  • "6" – receipt VAT at the rate of 20%;
  • "7" – receipt VAT at the estimated rate 20/120;

Mandatory for sellers with fiscalization
taxSum N..18 no The amount of tax calculated by the seller. Specified in minimum currency units.

Response parameters:

Name Type Mandatory Description
errorCode N3 yes Error code. Possible values and their description are presented in the table below.
errorMessage AN..512 no Error description in the language passed in the language parameter in the request. Missing when ErrorCode=0.

Error codes (ErrorCode field):

Meaning Description
0 Request processing took place without system errors
5 The deposit amount must be greater than zero or at least one ruble
5 Access denied
5 The user must change password
6 Invalid order number
6 orderId not set
7 The payment must be in the correct state
7 System error
8 The required Shopping cart parameter is missing
8 The deposit amount is more than the amount at registration
8 The currency in the Shopping Cart does not match the currency of the order
8 The amount of product items in the Shopping cart does not match the total amount of the order
8 The original order does not contain a product item with this number
8 The quantity value is too large or too small

Request example:

html 
        <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:mer="https://ecom.alfabank.ru/api/soap/merchant-ws/">
   <soapenv:Header/>
   <soapenv:Body>
      <mer:depositOrder>
         <order language="ru" orderId="76d7885f-562a-4bac-abc3-18ecaaaca797" depositAmount="20777">
            <!--Optional:-->
            <depositItems>
               <!--Zero or more repetitions:-->
                <items positionId="1">
                     <name>Metzeler Enduro 3 Sahara</name>
                     <!-- Optional: -->
                     <itemDetails>
                        <!-- Zero or more repetitions: -->
                        <itemDetailsParams name="brand">Metzeler</itemDetailsParams>
                        <itemDetailsParams name="radius">17inch</itemDetailsParams>
                     </itemDetails>
                     <quantity measure="штук">1</quantity>
                     <itemAmount>7777</itemAmount>
                     <itemCurrency>643</itemCurrency>
                     <itemCode>T-M-14</itemCode>
                     <!-- Optional: -->
                     <discount>
                        <!-- Optional: -->
                        <discountType>percent</discountType>
                        <!-- Optional: -->
                        <discountValue>5</discountValue>
                     </discount>
                     <!-- Optional: -->
                     <agentInterest>
                        <!-- Optional: -->
                        <interestType>agentPercent</interestType>
                        <!-- Optional: -->
                        <interestValue>7</interestValue>
                     </agentInterest>
                     <tax>
                        <taxType>1</taxType>
                        <taxSum>111</taxSum>
                     </tax>
                     <itemPrice>7777</itemPrice>
                  </items>
                  <items positionId="2">
                     <name>Universal Mirror Enduro</name>
                     <!-- Optional: -->
                     <itemDetails>
                        <!-- Zero or more repetitions: -->
                        <itemDetailsParams name="brand">Noname</itemDetailsParams>
                        <itemDetailsParams name="diameter">12mm</itemDetailsParams>
                     </itemDetails>
                     <quantity measure="штук">1</quantity>
                     <itemAmount>5000</itemAmount>
                     <itemCurrency>643</itemCurrency>
                     <itemCode>NM-15</itemCode>
                     <!-- Optional: -->
                     <discount>
                        <!-- Optional: -->
                        <discountType>percent</discountType>
                        <!-- Optional: -->
                        <discountValue>5</discountValue>
                     </discount>
                     <!-- Optional: -->
                     <agentInterest>
                        <!-- Optional: -->
                        <interestType>agentPercent</interestType>
                        <!-- Optional: -->
                        <interestValue>7</interestValue>
                     </agentInterest>
                     <tax>
                        <taxType>1</taxType>
                        <taxSum>111</taxSum>
                     </tax>
                     <itemPrice>5000</itemPrice>
                  </items>
                  <items positionId="3">
                     <name>Warm Grips</name>
                     <!-- Optional: -->
                     <itemDetails>
                        <!-- Zero or more repetitions: -->
                        <itemDetailsParams name="brand">Noname</itemDetailsParams>
                     </itemDetails>
                     <quantity measure="штук">1</quantity>
                     <itemAmount>8000</itemAmount>
                     <itemCurrency>643</itemCurrency>
                     <itemCode>G-16</itemCode>
                     <!-- Optional: -->
                     <discount>
                        <!-- Optional: -->
                        <discountType>percent</discountType>
                        <!-- Optional: -->
                        <discountValue>5</discountValue>
                     </discount>
                     <!-- Optional: -->
                     <agentInterest>
                        <!-- Optional: -->
                        <interestType>agentPercent</interestType>
                        <!-- Optional: -->
                        <interestValue>7</interestValue>
                     </agentInterest>
                     <tax>
                        <taxType>1</taxType>
                        <taxSum>111</taxSum>
                     </tax>
                     <itemPrice>8000</itemPrice>
                  </items>
            </depositItems>
            <!--Zero or more repetitions:-->
            <params name=" " value=" "/>
         </order>
      </mer:depositOrder>
   </soapenv:Body>
</soapenv:Envelope>

Response example:

html 
        <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns1:depositOrderResponse xmlns:ns1="https://ecom.alfabank.ru/api/soap/merchant-ws/">
         <return errorCode="0"/>
      </ns1:depositOrderResponse>
   </soap:Body>
</soap:Envelope>

Request for order payment cancellation (WS)

The reverseOrderrequest is used to request cancellation of an order. The cancellation function is available within a limited time after payment, the exact terms must be specified in the Bank.
The payment cancellation operation can be performed only once. If it ends with an error, the repeated payment cancellation operation will fail.
This function is available to stores in agreement with the Bank. To perform the cancellation operation, the user must have the appropriate rights.
Request parameters:

Name Type Compulsoriness Description
orderId ANS36 yes The order number in the payment system. It is unique within the system.
language A2 no The language is encoded in ISO 639-1. The error description is returned in this language. If the parameter is not available, the default language specified in the merchant's settings is used.

Response parameters:

Name Type Compulsoriness Description
errorCode N3 no Error code.
errorMessage AN..512 no Description of the error in the language.

Error codes (ErrorCode field):
Classification:

Meaning Description
0 Request processing took place without system errors
5 Incorrect value of a request parameter
6 Unregistered OrderId
7 System error

Decoding:

Meaning Description
0 Request processing took place without system errors
5 Access denied
5 The user must change password
5 orderId not set
6 Invalid order number
7 The operation is not possible for the current payment status
7 Reversal is impossible. Reason: incorrect internal values, check the amount of hold, deposit
7 System error

Request example:

html 
        <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:mer="https://ecom.alfabank.ru/api/soap/merchant-ws/"> 
    <soapenv:Header/> 
    <soapenv:Body> 
       <mer:reverseOrder> 
          <order language="ru" orderId="f88a2bbf-2021-4ccc-8783-8a13068a89f9"> 
             <!- Zero or more repetitions: -> 
             <params name=" " value=" "/> 
          </order> 
       </mer:reverseOrder> 
    </soapenv:Body> 
 </soapenv:Envelope>

Response example:

html 
        <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> 
    <soap:Body> 
       <ns1:reverseOrderResponse xmlns:ns1="https://ecom.alfabank.ru/api/soap/merchant-ws/"> 
          <return errorCode="7" errorMessage="Недопустимая операция для текущего состояния заказа"/> 
       </ns1:reverseOrderResponse> 
    </soap:Body> 
 </soap:Envelope>

Request for a full refund of the order payment (WS)

To request a full refund of the payment means, the refundOrder request is used. Upon this request, the funds for the specified order will be returned to the payer. The request will end with an error if the funds for this order have not been debited.
This operation is available to users who have the appropriate rights in the system.
Request parameters:

Name Type Mandatory Description
orderId AN..64 yes The order number in the payment system. It is unique within the system.
refundAmount N..5 yes The refund amount in the order currency in minimum currency units. It must be equal to the order amount.
language A2 no The language code in accordance with ISO 639-1. If not specified, it is assumed that the language is Russian. The error message will be returned in this language.
params N/A no An additional tag with attributes for transmitting additional merchant parameters.

The fields for additional information and its subsequent storage. These fields can be passed to the Bank processing system to be subsequently displayed in the registries.
This functionality can be enabled upon additional agreement with the bank during the integration period. To pass N parameters, the request must contain N params tags, where the name attribute contains the name, and the value attribute contains the value:

Name Type Mandatory Description
name AN..20 yes Name of the additional parameter
value AN..1024 yes Value of the additional parameter

Note By default, the orderNumber and its description fields are transferred 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 N3 yes Error code. Possible values and their description are presented in the table below.
errorMessage AN..512 no Error description in the language passed in the language parameter in the request.

Error codes (ErrorCode field):

Meaning Description
0 Request processing took place without system errors
5 Access denied
5 The user must change password
5 The order number is not specified
5 Incorrect amount
6 Invalid order number
7 The payment must be in the correct state
7 The refund amount exceeds the amount debited
7 System error
8 The specified refund amount does not match the full amount of the order. For a partial refund, a Shopping cart is required

Request example:

html 
        <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:mer="https://ecom.alfabank.ru/api/soap/merchant-ws/">
   <soapenv:Header/>
   <soapenv:Body>
      <mer:refundOrder>
         <order language="ru" orderId="3b32da16-1171-42c0-9d4e-bb6e243ff11d" refundAmount="24000">
            <!--Optional:-->
            <!--Zero or more repetitions:-->
            <params name=" " value=" "/>
         </order>
      </mer:refundOrder>
   </soapenv:Body>
</soapenv:Envelope>

Response example:

html 
        <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns1:refundOrderResponse xmlns:ns1="https://ecom.alfabank.ru/api/soap/merchant-ws/">
         <return errorCode="0"/>
      </ns1:refundOrderResponse>
   </soap:Body>
</soap:Envelope>

Запрос частичного возврата средств оплаты заказа(WS)

For a partial refund, a refundOrder request is used with the mandatory indication of the Shopping cart of returned goods. Upon this request, the funds for the order will be returned to the payer.
The request will end with an error if the funds for this order have not been debited. The system allows you to return funds more than 1 time, but not more than the initial debit amount.
Note For error-free processing of the request, it is enough to transfer the quantity and positionId parameters.
The Requirements for the generation of requests for the return of an order with a Shopping cart section contains a list of conditions necessary for the correct generation of the request.
Request parameters:

Name Type Mandatory Description
orderId AN..64 yes The order number in the payment system. It is unique within the system.
refundAmount N..5 yes The refund amount in the order currency (in minimum units). It shall match the total amount of all returned product items.
language A2 no The language is encoded in ISO 639-1. If not specified, it is assumed that the language is Russian. The error message will be returned in this language.
params N/A no An additional tag with attributes for transmitting additional merchant parameters (see the note below).
refundItems N/A - The tag for transmitting information about the returned products is the item number of the product in the request, name, details, unit of measurement, quantity, currency, product code, discount, agent's benefit. The description is given below.

Note The fields for additional information and its subsequent storage. These fields can be passed to the Bank processing system to be subsequently displayed in the registries.
This functionality can be enabled upon additional agreement with the bank during the integration period. To pass N parameters, the request must contain N params tags, where the name attribute contains the name, and the value attribute contains the value:

Name Type Mandatory Description
name AN..20 yes Name of the additional parameter
value AN..1024 yes Value of the additional parameter


By default, the order number and its description fields are transferred to the bank's processing system (no more than 99 characters; %, +, carriage return \r, and line feed \n cannot be used) : refundItems parameters**
The compulsoriness of parameters is specified for use within the tag. If the tag is optional and not included in the request, then the parameters included in it should not be transferred.

Name Type Mandatory Description
items N/A yes An array element with the attributes of the product item in the Shopping cart. The description is given below.


Attributes of the items element:
The compulsoriness of parameters is specified for use within the tag. If the tag is optional and not included in the request, then the parameters included in it should not be transferred.

Name Type Mandatory Description
positionId ANS..12 yes Unique identifier of the product item inside the Order Shopping Cart
name ANS..100 yes The name or description of the product item in free form
itemDetails N/A no An additional tag with the parameters of the description of the product item. The description is given below. is given below.
quantity N..18 yes An element describing the total number of product items of one positionId and their measure. A decimal point is used to indicate fractional numbers. The attribute is specified for this parameter: measure, ANS..20, mandatory (a product item quantity measure)..
itemAmount N..18 No (see description) The sum of the cost of all product items of one positionId in minimum currency units. itemAmount is required to be transferred only if the itemPrice parameter was not transferred. Otherwise, itemAmount transfer is not required. If both parameters are transferred in the request: ItemPrice and itemAmount, then itemAmount must be equal to ItemPrice quantity, otherwise the request will fail with an error. When calculating the itemAmount = `ItemPrice quantity` parameter, the result is rounded to the second digit after the decimal separator. For example, if the result of calculations is 100.255, then the final result will be 100.26.
itemCurrency N..3 no The currency code of the product item ISO 4217. If not specified, it is considered equal to the order currency.
itemCode ANS..100 yes The number (identifier) of the product item in the store's system
discount N/A no An additional tag with attributes describing the discount for the product item. The description is given below.
agentInterest N/A no An additional tag with attributes describing the agent fee for the sale of goods. The description is given below.
tax N/A no Additional tag with tax description attributes. If the fiscalization settings are specified for the store, this block can be transmitted, but it is not mandatory (the values of the parameters of this block will not be checked). The description is given below.
itemPrice N..18 no The cost of one product item of one positionId in minimum currency units. If the fiscalization settings are specified for the store, this field can be transferred, but it is not mandatory (the value of this field will not be checked).
itemAttributes See description no A tag intended for transmitting a set of attributes of a product item. A description of the available attributes is provided below.

Parameters of the itemAttributes:
Attributes should be specified as follows

html 
        <attributes  name="attribute_name_1">attribute_value_1</attributes>
<attributes  name="attribute_name_2">attribute_value_2</attributes>
Name Type Mandatory Description
paymentMethod N..2 yes

Attribute of the payment method, the following values are available:

  • "1" - full preliminary payment before the transfer of the subject of payment;
  • "2" - partial preliminary payment until the transfer of the subject of payment;
  • "3" - advance;
  • "4" - full payment at the time of transfer of the subject of payment;
  • "5" - partial payment of the subject of payment at the time of its transfer with subsequent credit payment;
  • "6" - transfer of the subject of payment without its reimbursement at the time of its transfer with subsequent credit payment;
  • "7" - payment of the subject of payment after its transfer with credit payment..
paymentObject N..2 yes

The attribute of the subject of payment, the following values are available:

  • "1" - product;
  • "2" - excisable product;
  • "3" - work;
  • "4" - service;
  • "5" - gambling bet;
  • "6" - gambling winnings;
  • "7" - lottery ticket;
  • "8" - lottery winnings;
  • "9" - provision of IPR (intellectual property results);
  • "10" - payment;
  • "11" - agent fee;
  • "12" - compound subject of payment;
  • "13" - other subject of payment.
nomenclature ANS no The code of the product item in the hexadecimal representation. The maximum length is 32 bytes in HEX encoding.

Example of a representation:
1. 00 00 00 01 00 21 FA 41 00 23 05 41 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 12 00 AB 00
2. 000000010021FA4100230541000000000000000000000000000000001200AB00

Thus, the representation is possible with or without spaces.
The presence of spaces is optional.
supplier_info.phones Array ANS..19 no An array of supplier's phone numbers in the +N format.
supplier_info.name ANS..256 no Supplier's name.
supplier_info.inn N10..12 no Supplier's TIN.
agent_info.type N..2 Mandatory only if the agent_info object is transferred.

Agent type, one of the following values is possible:

  • "1" - bank payment agent;
  • "2" - bank payment subagent;
  • "3" - payment agent;
  • "4" - payment subagent;
  • "5" - designated agent;
  • "6" - commission agent;
  • "7" - other agent.
agent_info.paying.operation ANS..24 no Name of the payment agent's operation.
agent_info.paying.phones array ANS..19 no Array of phone numbers of the payment agent in the +N format..
agent_info.paymentsOperator.phones array ANS..19 no Array of phone numbers of the payment acceptance operator in the +N format..
agent_info.MTOperator.phones array ANS..19 no Array of phone numbers of the transfer operator in the +N format.
agent_info.MTOperator.name ANS..64 no Name of the transfer operator.
agent_info.MTOperator.address ANS..256 no Address of the transfer operator.
agent_info.MTOperator.inn ANS..256 no TIN of the transfer operator.


Parameters of the itemDetails:
The compulsoriness of parameters is specified for use within the tag. If the tag is optional and not included in the request, then the parameters included in it should not be transferred.

Name Type Mandatory Description
itemDetailsParams ANS..255 no Parameter that describes additional information about the item. The description is given below.


Атрибуты параметра itemDetailsParams:
The compulsoriness of parameters is specified for use within the tag. If the tag is optional and not included in the request, then the parameters included in it should not be transferred.

Name Type Mandatory Description
name AN..255 yes Name of the product item detail description parameter


Parameters of the discount:
The compulsoriness of parameters is specified for use within the tag. If the tag is optional and not included in the request, then the parameters included in it should not be transferred.

Name Type Mandatory Description
discountType ANS..20 yes Type of discount for a product item
discountValue N..20 yes The value of the discount for the product item


Parameters of the agentInterest:
The compulsoriness of parameters is specified for use within the tag. If the tag is optional and not included in the request, then the parameters included in it should not be transferred.

Name Type Mandatory Description
interestType ANS..20 yes Type of agent fee for the product sale
interestValue N..20 yes Value of agent fee for the product sale


Parameters of the tax:
The compulsoriness of parameters is specified for use within the tag. If the tag is optional and not included in the request, then the parameters included in it should not be transferred.

Name Type Mandatory Description
taxType N..2 yes

VAT rate, the following values are available:

  • "0" – without VAT;
  • "1" – VAT at the rate of 0%;
  • "2" – receipt VAT at the rate of 10%;
  • "3" – receipt VAT at the rate of 18%;
  • "4" – receipt VAT at the estimated rate 10/110;
  • "5" – receipt VAT at the estimated rate 18/118;
  • "6" – receipt VAT at the rate of 20%;
  • "7" – receipt VAT at the estimated rate 20/120;

Mandatory for sellers with fiscalization
taxSum N..18 no The amount of tax calculated by the seller. Specified in minimum currency units.

Response parameters:

Name Type Mandatory Description
errorCode N3 yes Error code. Possible values are shown in the table below.
errorMessage AN..512 no Error description in the language passed in the language parameter in the request. May be missing if errorCode=0.

Error codes (ErrorCode field):

Meaning Description
0 Success
5 Access denied
5 The user must change password
5 orderId not set
5 Incorrect amount
6 Invalid order number
7 The payment must be in the correct state
7 The refund amount exceeds the amount debited
7 System error
8 The required parameter of the Shopping cart is missing
8 The currency in the Shopping Cart does not match the currency of the order
8 Incorrect item for return
8 The quantity of the returned item in the Shopping Cart has been exceeded
8 The cost of the returned item has been exceeded

Request example:

html 
        <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:mer="https://ecom.alfabank.ru/api/soap/merchant-ws/">
   <soapenv:Header/>
   <soapenv:Body>
      <mer:refundOrder>
         <order language="ru" orderId="531eaa8d-b32d-46dd-8e48-64b873886e70" refundAmount="10000">
            <!--Optional:-->
            <refundItems>
               <!--Zero or more repetitions:-->
                  <items positionId="1">
                     <name>Metzeler Enduro 3 Sahara</name>
                     <!-- Optional: -->
                     <itemDetails>
                        <!-- Zero or more repetitions: -->
                        <itemDetailsParams name="brand">Metzeler</itemDetailsParams>
                        <itemDetailsParams name="radius">17inch</itemDetailsParams>
                     </itemDetails>
                     <quantity measure="штук">1</quantity>
                     <itemAmount>7000</itemAmount>
                     <itemCurrency>643</itemCurrency>
                     <itemCode>T-M-14</itemCode>
                     <!-- Optional: -->
                     <discount>
                        <!-- Optional: -->
                        <discountType>percent</discountType>
                        <!-- Optional: -->
                        <discountValue>5</discountValue>
                     </discount>
                     <!-- Optional: -->
                     <agentInterest>
                        <!-- Optional: -->
                        <interestType>agentPercent</interestType>
                        <!-- Optional: -->
                        <interestValue>7</interestValue>
                     </agentInterest>
                     <tax>
                        <taxType>1</taxType>
                        <taxSum>111</taxSum>
                     </tax>
                     <itemPrice>7000</itemPrice>
                  </items>
                  <items positionId="2">
                     <name>Universal Mirror Enduro</name>
                     <!-- Optional: -->
                     <itemDetails>
                        <!-- Zero or more repetitions: -->
                        <itemDetailsParams name="brand">Noname</itemDetailsParams>
                        <itemDetailsParams name="diameter">12mm</itemDetailsParams>
                     </itemDetails>
                     <quantity measure="штук">1</quantity>
                     <itemAmount>3000</itemAmount>
                     <itemCurrency>643</itemCurrency>
                     <itemCode>NM-15</itemCode>
                     <!-- Optional: -->
                     <discount>
                        <!-- Optional: -->
                        <discountType>percent</discountType>
                        <!-- Optional: -->
                        <discountValue>5</discountValue>
                     </discount>
                     <!-- Optional: -->
                     <agentInterest>
                        <!-- Optional: -->
                        <interestType>agentPercent</interestType>
                        <!-- Optional: -->
                        <interestValue>7</interestValue>
                     </agentInterest>
                     <tax>
                        <taxType>1</taxType>
                        <taxSum>111</taxSum>
                     </tax>
                     <itemPrice>3000</itemPrice>
                  </items>
            </refundItems>
            <!--Zero or more repetitions:-->
            <params name=" " value=" "/>
         </order>
      </mer:refundOrder>
   </soapenv:Body>
</soapenv:Envelope>

Response example:

html 
        <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns1:refundOrderResponse xmlns:ns1="https://ecom.alfabank.ru/api/soap/merchant-ws/">
         <return errorCode="0"/>
      </ns1:refundOrderResponse>
   </soap:Body>
</soap:Envelope>

Advanced order status request (WS)

The getOrderStatusExtended request is used to request the status of a registered order.
Request parameters

Name Type Mandatory Description
orderId ANS36 yes* The order number in the payment system. It is unique within the systema
language A2 no The language is encoded in ISO 639-1. If not specified, it is assumed that the language is Russian. The error message will be returned in this language.
merchantOrderNumber ANS..32 yes* The order number (ID) in the store's system.

Note The request must pass either the OrderID parameter or the merchantOrderNumber parameter. If both parameters are passed in the request, orderId has a higher priority..
Response parameters
There are several sets of response parameters. Exactly what kind of sets of parameters will be returned depends on the version of getOrderStatusExtended, specified in the seller's settings.

Name Type Mandatory Description getOrderStatusExtended version
orderNumber AN..32 yes The order number (ID) in the store's system. All versions.
orderStatus N2 no All versions.
actionCode N3 yes Response code. All versions.
actionCodeDescription AN..512 yes Decryption of the response code in the language transmitted in the language parameter in the request. All versions.
errorCode N3 no

Error code. The following options are possible:

  • '0' Request processing took place without system errors;
  • '1' orderId or orderNumber expected;
  • '5' Access denied;
  • '5' The user must change password;
  • '6' Order not found;
  • '7' System error.
All versions.
errorMessage AN..512 no Error description in the language passed in the language parameter in the request. All versions.
amount N..20 yes Payment amount in kopecks (or cents) All versions.
currency N3 no The payment currency code is ISO 4217. If not specified, it is considered equal to 810 (Russian rubles). All versions.
date ANS yes Order registration date. All versions.
orderDescription AN..512 no Description of the order transmitted during its registration All versions.
ip AN..20 yes The buyer's IP address. All versions.
The merchantOrderParams element is present in the response if the order contains additional seller parameters. Each additional order parameter is presented in a separate element of merchantOrderParams.*
Name Type Mandatory Description getOrderStatusExtended version
name AN..20 no Name of the additional parameter All versions.
value AN..1024 no Value of the additional parameter All versions.

The cardAuthInfo element contains a structure consisting of a list of the secureAuthInfo element and the following parameters :

Name Type Mandatory Description getOrderStatusExtended version
pan N..19 no The masked number of the card that was used for payment. Указан только после оплаты заказа. All versions.
expiration N6 no Card expiration date in the YYYYMM format. Указан только после оплаты заказа. All versions.
cardholderName A..64 no Cardholder's name. It is specified only after payment of the order. All versions.
approvalCode AN6 no Payment authorization code. This field has a fixed length (6 characters) and can contain digits and Latin letters. It is specified only after payment of the order. All versions.
chargeback A..5 no Whether the funds were forcibly returned to the buyer by the bank. The following values are possible: true; false. 06 and above.
paymentSystem N..10 yes Payment system name. The following options are available: VISA; MASTERCARD; AMEX; JCB; CUP; MIR. 08 and above.
product AN..255 yes Additional information about corporate cards. This information is filled in by the technical support in the management console. If there is no such information, an empty value is returned. 08 and above.
paymentWay AS..14 yes The method of making the payment (payment with the input of card data, payment by bindings, etc.). 09 and above.

The secureAuthInfo element (the element consists of an eci element and a threeDSInfo element, which is a list of the cavv and xid parameters*):

Name Type Mandatory Description getOrderStatusExtended version
eci N..4 no Electronic commercial indicator. It is specified only after the order payment and in case of appropriate permission. All versions.
cavv ANS..200 no The value of checking the authentication of the cardholder. It is specified only after the order payment and in case of appropriate permission. All versions.
xid ANS..80 no Electronic commercial transaction ID. It is specified only after the order payment and in case of appropriate permission. All versions.

The bindingInfo element consists of the following parameters:

Name Type Mandatory Description getOrderStatusExtended version
clientId ANS..255 no The client's number (ID) in the store's system, transmitted during the order registration. Present only if the store is allowed to create bindings. All versions.
bindingId AN..255 no ID of the binding created when paying for the order or used for payment. Present only if the store is allowed to create bindings. All versions.
authDateTime ANS no Date/time of authorization. 02 and above.
authRefNum AN..24 no The payment authorization account number that is assigned when registering the payment. 02 and above.
terminalId AN..10 no Terminal ID. 02 and above.

The paymentAmountInfo element consists of the following parameters:

Name Type Mandatory Description getOrderStatusExtended version
approvedAmount N..20 no The amount reserved on the card (used only for two-phase payments). 03 and above.
depositedAmount N..20 no The amount confirmed for debiting from the card. 03 and above.
refundedAmount N..20 no Refund amount. 03 and above.
paymentState A..10 no Order status. 03 and above.
feeAmount N..20 no Fee amount. 11 and above.

The bankInfo element consists of the following parameters:

Name Type Mandatory Description getOrderStatusExtended version
bankName AN..200 no Name of the Issuing bank. 03 and above.
bankCountryCode AN..4 no Country code of the issuing bank. 03 and above.
bankCountryName AN..160 no Name of the issuing bank's country in the language passed in the language parameter in the request, or in the language of the user who called the method, if the language is not specified in the request. 03 and above.
orderBundle См. описание no The block containing the Shopping cart of order items. Its attributes are described below. 03 and above.


OrderBundle Content

Name Type Mandatory Description getOrderStatusExtended version
customerDetails See description no The block of customer data. 03 and above.
cartItems See description no The block with the attributes of product items of the Shopping Cart. Its attributes are described below.. 03 and above.

CustomerDetails Content

Name Type Mandatory Description getOrderStatusExtended version
email ANS..40 no The buyer's email address. 03 and above.
phone N.12 no Buyer's phone number. 03 and above.
fullName N..100 no Last name, first name and patronymic of the payer. 13 and above.
passport N.100 no The series and number of the payer's passport in the following format: 2222888888. 13 and above.
inn N.12 no Taxpayer identification number. It is allowed to transmit 10 or 12 characters. 13 and above.


cartItems content

Name Type Mandatory Description getOrderStatusExtended version
items See description no An array element with the attributes of the product item in the Shopping cart. The description его атрибутов is given below. 03 and above.


items content

Name Type Mandatory Description getOrderStatusExtended version
name ANS..100 no The name or description of the product item in free form 03 and above.
quantity N..18 no This parameter transfers the total number of items of one positionId. A decimal point is used to indicate fractional numbers. The measure is transferred as an attribute: measure, ANS..20, optional (a product item quantity measure). 03 and above.
itemAmount N..18 no Сумма стоимости всех товарных позиций одного positionId в минимальных единицах валюты. 03 and above.
itemCurrency N..3 no Код валюты товарной позиции ISO 4217. 03 and above.
itemCode ANS..100 no The number (identifier) of the product item in the store's system. Параметр должен быть уникальным в рамках запроса. 03 and above.

Request example:

html 
        <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:mer="https://ecom.alfabank.ru/api/soap/merchant-ws/"> 
    <soapenv:Header/> 
    <soapenv:Body> 
       <mer:getOrderStatusExtended> 
          <order orderId="942e8534-ac73-4e3c-96c6-f6cc448018f7" language="en"> 
             <!--Optional:--> 
             <merchantOrderNumber> </merchantOrderNumber> 
            </order> 
       </mer:getOrderStatusExtended> 
    </soapenv:Body> 
 </soapenv:Envelope>

Response example:

html 
        <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns1:getOrderStatusExtendedResponse xmlns:ns1="https://ecom.alfabank.ru/api/soap/merchant-ws/">
         <return orderNumber="1499420313736" orderStatus="2" actionCode="0" actionCodeDescription="" amount="10500" currency="643" date="2017-07-07T12:41:11.654+03:00" orderDescription="Описание" ip="127.0.0.1" errorCode="0" errorMessage="Success">
            <attributes name="mdOrder" value="dc84ffbc-1d04-4748-94dc-75d87e91a745"/>
            <cardAuthInfo pan="555555**5599" expiration="202012" cardholderName="Test" approvalCode="111111"/>
            <authDateTime>2017-07-07T12:41:12.185+03:00</authDateTime>
            <terminalId>12345678</terminalId>
            <authRefNum>111111111111</authRefNum>
            <paymentAmountInfo paymentState="DEPOSITED" approvedAmount="10500" depositedAmount="10500" refundedAmount="0"/>
            <bankInfo bankName="SOME BANK IN USA" bankCountryCode="US" bankCountryName="Соединенные Штаты Америки"/>
            <orderBundle>
               <cartItems>
                  <items positionId="1">
                     <name>Universal Mirror Enduro</name>
                     <quantity measure="штук">3.0</quantity>
                     <itemAmount>6000</itemAmount>
                     <itemCurrency>643</itemCurrency>
                     <itemCode>NM-15</itemCode>
                  </items>
                  <items positionId="2">
                     <name>Билет в Москву</name>
                     <quantity measure="штук">1.0</quantity>
                     <itemAmount>4500</itemAmount>
                     <itemCurrency>643</itemCurrency>
                     <itemCode>GFCCHC</itemCode>
                  </items>
               </cartItems>
            </orderBundle>
         </return>
      </ns1:getOrderStatusExtendedResponse>
   </soap:Body>
</soap:Envelope>

Rest Interface

Request for order registration

To register an order in the payment acceptance pattern on the payment system side, the register.do register.do request is used - see the Connection coordinates section.
The product Shopping Cart is transferred in the orderBundle parameter.
The Requirements for the generation of order registration requests with a Shopping Cart section contains a list of conditions necessary for the correct generation of the request.
Note If the Shopping cart with fiscalization data is not transmitted in the payment request, the default values specified in the settings of the personal area are transmitted to the fiscal data operator (for more information, see the instructions for working with the personal area).
Request parameters:

Name Type Mandatory Description
userName AN..30 yes The store's login received when connecting
password AN..30 yes The store's password received when connecting
orderNumber AN..32 yes The order number (identifier) in the store's system is unique for each store within the system
amount N..12 yes Payment amount in kopecks (or cents)
currency N3 no The payment currency code is ISO 4217. If not specified, it is considered equal to the default currency code.
returnUrl AN..512 yes The address to which the user must be redirected in case of successful payment. 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>.
failUrl AN..512 no The address to which the user must be redirected in case of failed payment. 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>.
description ANS..512 no Description of the order in any form
language A2 no The language is encoded in ISO 639-1. If not specified, the default language specified in the store settings will be used.
pageView ANS..20 no

The value of this parameter determines which pages of the payment interface should be loaded for the client. Possible values are:

  • DESKTOP – for pages designed to be displayed on PC screens (pages with payment_<locale>.html and errors_<locale>.html will be searched for in the archive of the payment interface pages);
  • MOBILE – for pages designed to be displayed on mobile devices (pages with names mobile_payment_<locale>.html and mobile_errors_<locale>.html will be searched for in the archive of the payment interface pages);

  • If the store has added arbitrary prefixes to their page file names, value of the desired prefix should be passed in the pageView parameter for the corresponding pages to be loaded. For example, if iphone is passed in the parameter, pages with names iphone_payment_<locale>.html and iphone_error_<locale>.html will be searched for in the archive of the payment interface pages.
    where:

    • locale – language of the page encoded in ISO 639-1. For example, ru for Russian or en for English.

If the parameter is missing or does not match the format, the default value is pageView=DESKTOP.

clientId AN..255 no

The client's number (ID) in the store's system. It is used to implement the functionality of bindings. It can be present if creating bindings is allowed for the store.

Specifying this parameter when processing payments with the use of bindings is mandatory. Otherwise, a payment will be failed.
merchantLogin AN..255 no To register an order on behalf of a child merchant, specify the merchant login in this parameter.
jsonParams AN..1024 no

A block for passing additional merchant parameters. The fields for additional information and its subsequent storage are passed as: 

        {"<name1>":"<value1>",...,"<nameN>":"<valueN>"}

These fields can be passed to the Bank processing system to be subsequently displayed in the registries. This functionality can be enabled upon additional agreement with the bank during the integration period.
If sending notifications to a buyer is set up for a seller, the email address of a buyer must be passed in this block in the email parameter.
sessionTimeoutSecs N...9 no The order lifetime in seconds. If the parameter is not specified, the value specified in the merchant's settings or the default time (1200 seconds = 20 minutes) will be used. If the expirationDate parameter is present in the request, the value of the sessionTimeoutSecs parameter is ignored.
expirationDate ANS no Date and time of the order lifetime expiration. Format: yyyy-MM-DDThh:mm:ss. If this parameter is not passed in the request, then sessionTimeoutSecs is used to determine the end-of-life time of the order.
bindingId AN..255 no ID of the binding created earlier. It can only be used if the store has permission to work with bindings. If this parameter is passed in this request, it means: 1. This order can only be paid using a binding; 2. The payer will be redirected to the payment page, where only CVC input is required.
features ANS..255 no AUTO_PAYMENT - if the request for order registration initiates auto-payments.
bindingId AN..255 no Идентификатор связки, созданной ранее. Может использоваться, только если у магазина есть разрешение на работу со связками. Если этот параметр передаётся в данном запросе, то это означает: 1. Данный заказ может быть оплачен только с помощью связки; 2. Плательщик будет перенаправлен на платёжную страницу, где требуется только ввод CVC.
orderBundle N/A N/A Блок, содержащий Корзину товаров заказа. Описание его атрибутов представлено в таблице "Параметр orderBundle" ниже.
taxSystem N..2 yes - for fiscalization (for stores without fiscalization settings the parameter is not necessary)

Taxation system, the following values are available:

  • "0" - general;
  • "1" - simplified, income;
  • "2" - simplified, income minus expense;
  • "3" - unified imputed income tax;
  • "4" - unified agricultural tax;
  • "5" - patent taxation system.

Note By default the following fields are passed to the bank processing system:

  • orderNumber – order number in the store system;

  • description – order description (no more than 99 characters; %, +, carriage return \r, and line feed \n cannot be used).
    If an additional parameter named merchantOrderId, is passed in the order, then its value will be passed to the processing system as the order number (instead of the value of the orderNumber).


Parameters of the orderBundle block:
Note The compulsoriness of parameters is specified for use within the block. If the block is optional and not included in the request, then the parameters included in it should not be transferred..*

Name Type Mandatory Description
orderCreationDate ANS..21 no Order creation date in the YYYY-MM-DDTHH:MM:SS format
customerDetails - no A block with attributes of buyer data. Its attributes are described below. The transmission limit for each of the enabled parameters is 64 characters. The description is given below.
cartItems - yes A block with the attributes of the product items of the Shopping cart. Its attributes are described below.
agent - no A block for transmitting agent data (see the description below).
supplierPhones array ANS..19 no An array of supplier's phone numbers in the +N format.

Parameters of the agent

Name Type Mandatory Description
agentType N..2 yes (if a block is transmitted)

Agent type, one of the following values is possible:

  • "1" - bank payment agent;
  • "2" - bank payment subagent;
  • "3" - payment agent;
  • "4" - payment subagent;
  • "5" - designated agent;
  • "6" - commission agent;
  • "7" - other agent.
payingOperation ANS..24 no Name of the payment agent's operation.
payingPhones array ANS..19 no Array of phone numbers of the payment agent in the +N format..
paymentsOperatorPhones array ANS..19 no Array of phone numbers of the payment acceptance operator in the +N format..
MTOperatorPhones array ANS..19 no Array of phone numbers of the transfer operator in the +N format.
MTOperatorName ANS..64 no Name of the transfer operator.
MTOperatorAddress ANS..256 no Address of the transfer operator.
MTOperatorInn N10..12 no TIN of the transfer operator.


Parameters of the customerDetails:
The compulsoriness of parameters is specified for use within the tag. If the block is optional and not included in the request, then the parameters included in it should not be transferred

Name Type Mandatory Description
email ANS..40 no Buyer's email address. You can specify multiple email addresses separated by commas and without spaces - in this case the receipt will be sent to all specified addresses. Be sure to pass one of the two parameters: email or phone.
phone N.12 no Buyer's phone number. If the phone includes a country code, the number must begin with a plus sign (+). If the phone is passed without a plus sign (+), the country code should not be specified. Thus, the following options are acceptable: +79998887766; 9998887766. Be sure to pass one of the two parameters: email or phone..
contact ANS..40 no The method of communication with the buyer.
deliveryInfo - no A block with the attributes of the address for delivery. Its attributes are described below.
fullName ANS..100 no Last name, first name and patronymic of the payer.
passport ANS..100 no The series and number of the payer's passport in the following format: 2222888888.
inn ANS..12 no Taxpayer identification number. It is allowed to transmit 10 or 12 characters.


Parameters of the deliveryInfo block:
The compulsoriness of parameters is specified for use within the block. If the block is optional and not included in the request, then the parameters included in it should not be transferred.

Name Type Mandatory Description
deliveryType ANS..20 no Type of delivery
country A..2 yes Country of delivery
city ANS..40 yes City of delivery
postAddress ANS..255 yes Address for delivery


Parameters of the cartItems:
The compulsoriness of parameters is specified for use within the block. If the block is optional and not included in the request, then the parameters included in it should not be transferred.

Name Type Mandatory Description
items - yes An array of blocks describing the product items in the Shopping Cart. The description of parameters of the blocks is presented below. Information on each product item of the Shopping Cart is transmitted in a separate block included in the items. The description is given below.


Parameters of the block included in items:
The compulsoriness of parameters is specified for use within the block. If the block is optional and not included in the request, then the parameters included in it should not be transferred.

Name Type Mandatory Description
positionId N..12 yes Unique identifier of the product item inside the Order Shopping Cart
name ANS..100 yes The name or description of the product item in free form
itemDetails - no An additional block with the parameters of the description of the product item. Its attributes are described below.
quantity - yes An element describing the total number of product items of one positionId and their measure. Its attributes are described below.
itemAmount N..18 yes The sum of the cost of all product items of one positionID in minimum currency units. itemAmount is required to be transferred only if the itemPrice parameter was not transferred. Otherwise, itemAmount transfer is not required. If both parameters are transferred in the request: itemPrice and itemAmount, then itemAmount must be equal to ItemPrice quantity, otherwise the request will fail with an error. When calculating the itemAmount = ItemPrice quantity parameter, the result is rounded to the second digit after the decimal separator. For example, if the result of calculations is 100.255, then the final result will be 100.26.
itemCurrency N3 no The currency code of the product item ISO 4217. If not specified, it is considered equal to the order currency.
itemCode ANS..100 yes The number (identifier) of the product item in the store's system. The parameter must be unique within the request.
discount - no An additional block with attributes describing the discount for the product item. Its attributes are described below.
agentInterest - no An additional block with attributes describing the agent fee for the sale of goods. Its attributes are described below.
tax - yes - for fiscalization (for stores without fiscalization settings the parameter is not necessary) Additional block with tax description attributes. The description is given below.
itemPrice N..18 yes - for fiscalization (for stores without fiscalization settings the parameter is not necessary) The cost of one product item of one positionId in money in minimum currency units. Mandatory for merchants with fiscalization
itemAttributes See description no A block intended for transmitting a set of attributes of a product item. A description of the available attributes is provided below.

Parameters of the itemAttributes:
Attributes should be specified as follows

        "itemAttributes":{"attributes":[{"name":"paymentMethod","value":"1"},{"name":"paymentObject","value":"1"}]}
Name Type Mandatory Description
paymentMethod N..2 yes

Attribute of the payment method, the following values are available:

  • "1" - full preliminary payment before the transfer of the subject of payment;
  • "2" - partial preliminary payment until the transfer of the subject of payment;
  • "3" - advance;
  • "4" - full payment at the time of transfer of the subject of payment;
  • "5" - partial payment of the subject of payment at the time of its transfer with subsequent credit payment;
  • "6" - transfer of the subject of payment without its reimbursement at the time of its transfer with subsequent credit payment;
  • "7" - payment of the subject of payment after its transfer with credit payment..
paymentObject N..2 yes

The attribute of the subject of payment, the following values are available:

  • "1" - product;
  • "2" - excisable product;
  • "3" - work;
  • "4" - service;
  • "5" - gambling bet;
  • "6" - gambling winnings;
  • "7" - lottery ticket;
  • "8" - lottery winnings;
  • "9" - provision of IPR (intellectual property results);
  • "10" - payment;
  • "11" - agent fee;
  • "12" - compound subject of payment;
  • "13" - other subject of payment.
nomenclature ANS no The code of the product item in the hexadecimal representation. The maximum length is 32 bytes in HEX encoding.

Example of a representation:
1. 00 00 00 01 00 21 FA 41 00 23 05 41 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 12 00 AB 00
2. 000000010021FA4100230541000000000000000000000000000000001200AB00

Thus, the representation is possible with or without spaces.
The presence of spaces is optional.
supplier_info.phones Array ANS..19 no An array of supplier's phone numbers in the +N format.
supplier_info.name ANS..256 no Supplier's name.
supplier_info.inn N10..12 no Supplier's TIN.
agent_info.type N..2 Mandatory only if the agent_info object is transferred.

Agent type, one of the following values is possible:

  • "1" - bank payment agent;
  • "2" - bank payment subagent;
  • "3" - payment agent;
  • "4" - payment subagent;
  • "5" - designated agent;
  • "6" - commission agent;
  • "7" - other agent.
agent_info.paying.operation ANS..24 no Name of the payment agent's operation.
agent_info.paying.phones array ANS..19 no Array of phone numbers of the payment agent in the +N format..
agent_info.paymentsOperator.phones array ANS..19 no Array of phone numbers of the payment acceptance operator in the +N format..
agent_info.MTOperator.phones array ANS..19 no Array of phone numbers of the transfer operator in the +N format.
agent_info.MTOperator.name ANS..64 no Name of the transfer operator.
agent_info.MTOperator.address ANS..256 no Address of the transfer operator.
agent_info.MTOperator.inn ANS..256 no TIN of the transfer operator.


Parameters of the quantity:
The compulsoriness of parameters is specified for use within the block. If the block is optional and not included in the request, then the parameters included in it should not be transferred.

Name Type Mandatory Description
value N..18 yes The number of product items of this positionId. To specify fractional numbers, use a decimal point.
measure ANS..20 yes A product item quantity measure


Parameters of the itemDetails:
The compulsoriness of parameters is specified for use within the block. If the block is optional and not included in the request, then the parameters included in it should not be transferred.

Name Type Mandatory Description
itemDetailsParams - no Additional information on the product item. It is an array of blocks, each of which conveys information about a certain characteristic of a product item. The description is given below.


Parameters of the, входящего в состав itemDetailsParams:
The compulsoriness of parameters is specified for use within the block. If the block is optional and not included in the request, then the parameters included in it should not be transferred.

Name Type Mandatory Description
value ANS..255 yes Additional information on the product item
name ANS..255 yes Name of the product item detail description parameter


Parameters of the discount:
The compulsoriness of parameters is specified for use within the block. If the block is optional and not included in the request, then the parameters included in it should not be transferred.

Name Type Mandatory Description
discountType ANS..20 yes Type of discount for a product item
discountValue N..20 yes The value of the discount for the product item


Parameters of the agentInterest:
The compulsoriness of parameters is specified for use within the block. If the block is optional and not included in the request, then the parameters included in it should not be transferred.

Name Type Mandatory Description
interestType ANS..20 yes Type of agent fee for the product sale
interestValue N..20 yes Value of agent fee for the product sale


Parameters of the tax:
The compulsoriness of parameters is specified for use within the block. If the block is optional and not included in the request, then the parameters included in it should not be transferred.

Name Type Mandatory Description
taxType N..2 yes

VAT rate, the following values are available:

  • "0" – without VAT;
  • "1" – VAT at the rate of 0%;
  • "2" – receipt VAT at the rate of 10%;
  • "3" – receipt VAT at the rate of 18%;
  • "4" – receipt VAT at the estimated rate 10/110;
  • "5" – receipt VAT at the estimated rate 18/118;
  • "6" – receipt VAT at the rate of 20%;
  • "7" – receipt VAT at the estimated rate 20/120;

Mandatory for sellers with fiscalization
taxSum N..18 no The amount of tax calculated by the seller. Specified in minimum currency units.

Response parameters:

Name Type Mandatory Description
orderId ANS36 no The order number in the payment system. It is unique within the system. It is missing if the order registration failed due to an error detailed in errorCode.
formUrl AN..512 no URL of the payment form to which the client's browser is to be redirected. It is not returned if the order registration failed due to an error detailed in ErrorCode.
errorCode N3 no Error code. It may be missing if the result did not lead to an error.
errorMessage AN..512 no Error description in the language passed in the language parameter in the request.

Error codes (поле errorCode):

Meaning Description
1 Order with given order number is processed already.
1 Invalid order number.
3 Unknown currency.
4 The order number cannot be empty.
4 The merchant's name cannot be empty.
4 Empty amount.
4 The return URL cannot be empty.
4 The password cannot be empty.
5 The value of one of the parameters is incorrect.
5 Access denied.
5 The user is disabled.
7 System error.
8 Absence of a mandatory Shopping Cart parameter.
8 The currency in the Shopping Cart does not match the currency of the order.
8 The amount of items in the Shopping cart does not match the total amount of the order.
8 Invalid Shopping Cart format.
8 The amount_bonus additional parameter is forbidden to be transferred if the request contains a Shopping Cart.
8 The quantity value is too large or too small.

Example of a POST request:

        amount=24000&
currency=643&
language=ru&
orderNumber=04f04a87d6f4а5rg3r3d21&
returnUrl=https://tws.egopay.ru/ab/finish.html&
jsonParams={"name1":"value1"}&
sessionTimeoutSecs=5400&
merchantLogin=merch_child&
taxSystem=0&

orderBundle=
{ 

"orderCreationDate":"2013-07-12T13:51:00",  

"customerDetails":{ "email":"email@email.com", "phone":"79851231234", "contact": "Mega  Tester","deliveryInfo":{ "deliveryType":"courier", "country":"RU",  "city":"Moscow",
"postAddress":"Earthen Rampart 50A p.2" }},  

"cartItems":  

{ "items": 

[ 
{ "positionId": "1",
"name": "Metzeler Enduro 3 Sahara", 
"itemDetails": { "itemDetailsParams":[{ "value": "Metzeler ", "name": "brand" }, { "value": "17inch", "name": "radius" }]},
"quantity": { "value": 0.71, "measure": "штук" }, 
"itemAmount": 8000, 
"itemCurrency": "643",
"itemCode": "NM-15", 
"discount": { "discountType": "percent", "discountValue": "5" },
"agentInterest": { "interestType": "agentPercent", "interestValue": "7" }, 
"tax": {"taxType": 1,"taxSum": 111}, 
"itemPrice": 11267
},

{ "positionId": "2", 
"name": "Universal Mirror Enduro", 
"itemDetails": { "itemDetailsParams":[{ "value": "Noname", "name": "brand" }, { "value": "12mm", "name": "diameter" }]},
"quantity": { "value": 1.0, "measure": "штук" }, 
"itemAmount": 8000, 
"itemCurrency": "643",
"itemCode": "NM-15", 
"discount": { "discountType": "percent", "discountValue": "5" },
"agentInterest": { "interestType": " agentPercent ", "interestValue": "7" }, 
"tax": {"taxType": 1,"taxSum": 111}, 
"itemPrice": 8000 
},

{ "positionId": "3", 
"name": "Warm Grips", 
"itemDetails": { "itemDetailsParams":[ { "value": "Noname", "name": "brand" }]},  "quantity": { "value": 1.0, "measure": "штук" },
"itemAmount": 8000, 
"itemCurrency": 643, 
"itemCode": "G-16",
"discount": { "discountType": "percent", "discountValue": "5" },
"agentInterest": { "interestType": " agentPercent ", "interestValue": "7" }, 
"tax": {"taxType": 1,"taxSum": 111}, 
"itemPrice": 8000 
}
] 

} 

}

Response example: 

        {"formUrl":"https://tws.egopay.ru/ab/789/payment_ru.html?
mdOrder=ece47318-19f2-466a-93cd-bdb08c1587ec","orderId":"ece47318-19f2-466a-93cd-bdb08c1587ec"}

Request for order registration with pre-authorization

To register an order with pre-authorization, the registerPreAuth.do request is used - see the section "Connection coordinates".
The product Shopping Cart is transferred in the orderBundle parameter.
The Requirements for the generation of order registration requests with a Shopping Cart section contains a list of conditions necessary for the correct generation of the request.
Note If the Shopping cart with fiscalization data is not transmitted in the payment request, the default values specified in the settings of the personal area are transmitted to the fiscal data operator (for more information, see the instructions for working with the personal area).
Request parameters:

Name Type Mandatory Description
userName AN..30 yes The store's login received when connecting
password AN..30 yes The store's password received when connecting
orderNumber AN..32 yes The order number (identifier) in the store's system is unique for each store within the system
amount N..12 yes Payment amount in kopecks (or cents)
currency N3 no The payment currency code is ISO 4217. If not specified, it is considered equal to the default currency code.
returnUrl AN..512 yes The address to which the user must be redirected in case of successful payment. 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>.
failUrl AN..512 no The address to which the user must be redirected in case of failed payment. 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>.
description ANS..512 no Description of the order in any form
language A2 no The language is encoded in ISO 639-1. If not specified, the default language specified in the store settings will be used.
pageView ANS..20 no

The value of this parameter determines which pages of the payment interface should be loaded for the client. Possible values are:

  • DESKTOP – for pages designed to be displayed on PC screens (pages with payment_<locale>.html and errors_<locale>.html will be searched for in the archive of the payment interface pages);
  • MOBILE – for pages designed to be displayed on mobile devices (pages with names mobile_payment_<locale>.html and mobile_errors_<locale>.html will be searched for in the archive of the payment interface pages);

  • If the store has added arbitrary prefixes to their page file names, value of the desired prefix should be passed in the pageView parameter for the corresponding pages to be loaded. For example, if iphone is passed in the parameter, pages with names iphone_payment_<locale>.html and iphone_error_<locale>.html will be searched for in the archive of the payment interface pages.
    where:

    • locale – language of the page encoded in ISO 639-1. For example, ru for Russian or en for English.

If the parameter is missing or does not match the format, the default value is pageView=DESKTOP.

clientId AN..255 no

The client's number (ID) in the store's system. It is used to implement the functionality of bindings. It can be present if creating bindings is allowed for the store.

Specifying this parameter when processing payments with the use of bindings is mandatory. Otherwise, a payment will be failed.
merchantLogin AN..255 no To register an order on behalf of a child merchant, specify the merchant login in this parameter.
jsonParams AN..1024 no

A block for passing additional merchant parameters. The fields for additional information and its subsequent storage are passed as: 

        {"<name1>":"<value1>",...,"<nameN>":"<valueN>"}

These fields can be passed to the Bank processing system to be subsequently displayed in the registries. This functionality can be enabled upon additional agreement with the bank during the integration period.
If sending notifications to a buyer is set up for a seller, the email address of a buyer must be passed in this block in the email parameter.
sessionTimeoutSecs N...9 no The order lifetime in seconds. If the parameter is not specified, the value specified in the merchant's settings or the default time (1200 seconds = 20 minutes) will be used. If the expirationDate parameter is present in the request, the value of the sessionTimeoutSecs parameter is ignored.
expirationDate ANS no Date and time of the order lifetime expiration. Format: yyyy-MM-DDThh:mm:ss. If this parameter is not passed in the request, then sessionTimeoutSecs is used to determine the end-of-life time of the order.
bindingId AN..255 no ID of the binding created earlier. It can only be used if the store has permission to work with bindings. If this parameter is passed in this request, it means: 1. This order can only be paid using a binding; 2. The payer will be redirected to the payment page, where only CVC input is required.
features ANS..255 no AUTO_PAYMENT - if the request for order registration initiates auto-payments.
bindingId AN..255 no ID of the binding created earlier. It can only be used if the store has permission to work with bindings. If this parameter is passed in this request, it means: 1. This order can only be paid using a binding; 2. The payer will be redirected to the payment page, where only CVC input is required.
orderBundle N/A N/A The block containing the Shopping cart of order items. A description of its attributes is provided in the "OrderBundle Parameter" table below.
taxSystem N..2 yes - for fiscalization (for stores without fiscalization settings the parameter is not necessary)

Taxation system, the following values are available:

  • "0" - general;
  • "1" - simplified, income;
  • "2" - simplified, income minus expense;
  • "3" - unified imputed income tax;
  • "4" - unified agricultural tax;
  • "5" - patent taxation system.
autocompletionDate ANS..19 no The date and time of completion of the two-phase payment in the following format: 2017-12-29T13:02:51.

By default the following fields are passed to the bank processing system:

  • orderNumber – order number in the store system;

  • description – order description (no more than 99 characters; %, +, carriage return \r, and line feed \n cannot be used).
    If an additional parameter named merchantOrderId, is passed in the order, then its value will be passed to the processing system as the order number (instead of the value of the orderNumber).


The orderBundle parameter:
The compulsoriness of parameters is specified for use within the block. If the block is optional and not included in the request, then the parameters included in it should not be transferred.

Name Type Mandatory Description
orderCreationDate ANS..21 no Order creation date in the YYYY-MM-DDTHH:MM:SS format
customerDetails N/A no A block with attributes of buyer data. Its attributes are described below. The transmission limit for each of the enabled parameters is 64 characters.
cartItems N/A yes A block with the attributes of the product items of the Shopping cart. The description is is given below.
agent - no A block for transmitting agent data (see the description below).
supplierPhones array ANS..19 no An array of supplier's phone numbers in the +N format.

Parameters of the agent

Name Type Mandatory Description
agentType N..2 yes (if a block is transmitted)

Agent type, one of the following values is possible:

  • "1" - bank payment agent;
  • "2" - bank payment subagent;
  • "3" - payment agent;
  • "4" - payment subagent;
  • "5" - designated agent;
  • "6" - commission agent;
  • "7" - other agent.
payingOperation ANS..24 no Name of the payment agent's operation.
payingPhones array ANS..19 no Array of phone numbers of the payment agent in the +N format..
paymentsOperatorPhones array ANS..19 no Array of phone numbers of the payment acceptance operator in the +N format..
MTOperatorPhones array ANS..19 no Array of phone numbers of the transfer operator in the +N format.
MTOperatorName ANS..64 no Name of the transfer operator.
MTOperatorAddress ANS..256 no Address of the transfer operator.
MTOperatorInn N10..12 no TIN of the transfer operator.


Parameters of the customerDetails block:

Name Type Mandatory Description
email ANS..40 no Buyer's email address. You can specify multiple email addresses separated by commas and without spaces - in this case the receipt will be sent to all specified addresses. Be sure to pass one of the two parameters: email or phone.
phone N.12 no Buyer's phone number. If the phone includes a country code, the number must begin with a plus sign (+). If the phone is passed without a plus sign (+), the country code should not be specified. Thus, the following options are acceptable: +79998887766; 9998887766. Be sure to pass one of the two parameters: email or phone.
contact ANS..40 no The method of communication with the buyer.
deliveryInfo N/A no A block with the attributes of the address for delivery. The description is given below.
fullName ANS..100 no Last name, first name and patronymic of the payer.
passport ANS..100 no The series and number of the payer's passport in the following format: 2222888888.
inn ANS..12 no Taxpayer identification number. It is allowed to transmit 10 or 12 characters.


Parameters of the deliveryInfo:
The compulsoriness of parameters is specified for use within the block. If the block is optional and not included in the request, then the parameters included in it should not be transferred.

Name Type Mandatory Description
deliveryType ANS..20 no Type of delivery
country A..2 yes Country of delivery
city ANS..40 yes City of delivery
postAddress ANS..255 yes Address for delivery


Parameters of the cartItems:
The compulsoriness of parameters is specified for use within the block. If the block is optional and not included in the request, then the parameters included in it should not be transferred.

Name Type Mandatory Description
items N/A yes An array element with the attributes of the product item in the Shopping cart. The description is given below.


Attributes of the items:
The compulsoriness of parameters is specified for use within the block. If the block is optional and not included in the request, then the parameters included in it should not be transferred.

Name Type Mandatory Description
positionId N..12 yes Unique identifier of the product item inside the Order Shopping Cart
name ANS..100 yes The name or description of the product item in free form
itemDetails N/A no An additional block with the parameters of the description of the product item. The description is given below.
quantity N/A yes An element describing the total number of product items of one positionId and their measure. The description is given below.
itemAmount N..18 No (see description) The sum of the cost of all product items of one positionID in minimum currency units. itemAmount is required to be transferred only if the itemPrice parameter was not transferred. Otherwise, itemAmount transfer is not required. If both parameters are transferred in the request: itemPrice and itemAmount, then itemAmount must be equal to ItemPrice quantity, otherwise the request will fail with an error. When calculating the itemAmount = ItemPrice quantity parameter, the result is rounded to the second digit after the decimal separator. For example, if the result of calculations is 100.255, then the final result will be 100.26..
itemCurrency N3 no The currency code of the product item ISO 4217. If not specified, it is considered equal to the order currency.
itemCode ANS..100 yes The number (identifier) of the product item in the store's system
discount N/A no An additional block with attributes describing the discount for the product item. The description is given below.
agentInterest N/A no An additional block with attributes describing the agent fee for the sale of goods. The description is given below.
tax N/A yes - for fiscalization (for stores without fiscalization settings the parameter is not necessary) Additional block with tax description attributes. The description is given below.
itemPrice N..18 yes - for fiscalization (for stores without fiscalization settings, the parameter is optional) The cost of one product item of one positionId in minimum currency units. Mandatory for merchants with fiscalization
itemAttributes See description no A block intended for transmitting a set of attributes of a product item. A description of the available attributes is provided below.

Parameters of the itemAttributes:
Attributes should be specified as follows

        "itemAttributes":{"attributes":[{"name":"paymentMethod","value":"1"},{"name":"paymentObject","value":"1"}]}
Name Type Mandatory Description
paymentMethod N..2 yes

Attribute of the payment method, the following values are available:

  • "1" - full preliminary payment before the transfer of the subject of payment;
  • "2" - partial preliminary payment until the transfer of the subject of payment;
  • "3" - advance;
  • "4" - full payment at the time of transfer of the subject of payment;
  • "5" - partial payment of the subject of payment at the time of its transfer with subsequent credit payment;
  • "6" - transfer of the subject of payment without its reimbursement at the time of its transfer with subsequent credit payment;
  • "7" - payment of the subject of payment after its transfer with credit payment..
paymentObject N..2 yes

The attribute of the subject of payment, the following values are available:

  • "1" - product;
  • "2" - excisable product;
  • "3" - work;
  • "4" - service;
  • "5" - gambling bet;
  • "6" - gambling winnings;
  • "7" - lottery ticket;
  • "8" - lottery winnings;
  • "9" - provision of IPR (intellectual property results);
  • "10" - payment;
  • "11" - agent fee;
  • "12" - compound subject of payment;
  • "13" - other subject of payment.
nomenclature ANS no The code of the product item in the hexadecimal representation. The maximum length is 32 bytes in HEX encoding.

Example of a representation:
1. 00 00 00 01 00 21 FA 41 00 23 05 41 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 12 00 AB 00
2. 000000010021FA4100230541000000000000000000000000000000001200AB00

Thus, the representation is possible with or without spaces.
The presence of spaces is optional.
supplier_info.phones Array ANS..19 no An array of supplier's phone numbers in the +N format.
supplier_info.name ANS..256 no Supplier's name.
supplier_info.inn N10..12 no Supplier's TIN.
agent_info.type N..2 Mandatory only if the agent_info object is transferred.

Agent type, one of the following values is possible:

  • "1" - bank payment agent;
  • "2" - bank payment subagent;
  • "3" - payment agent;
  • "4" - payment subagent;
  • "5" - designated agent;
  • "6" - commission agent;
  • "7" - other agent.
agent_info.paying.operation ANS..24 no Name of the payment agent's operation.
agent_info.paying.phones array ANS..19 no Array of phone numbers of the payment agent in the +N format..
agent_info.paymentsOperator.phones array ANS..19 no Array of phone numbers of the payment acceptance operator in the +N format..
agent_info.MTOperator.phones array ANS..19 no Array of phone numbers of the transfer operator in the +N format.
agent_info.MTOperator.name ANS..64 no Name of the transfer operator.
agent_info.MTOperator.address ANS..256 no Address of the transfer operator.
agent_info.MTOperator.inn ANS..256 no TIN of the transfer operator.


Attributes of the quantity element:
The compulsoriness of parameters is specified for use within the block. If the block is optional and not included in the request, then the parameters included in it should not be transferred.

Name Type Mandatory Description
value N..18 yes The number of product items of this positionId. To specify fractional numbers, use a decimal point.
measure ANS..20 yes A product item quantity measure


Parameters of the  itemDetails block:

Name Type Mandatory Description
itemDetailsParams N/A no Parameter that describes additional information about the item. The description is given below.


Parameters of the itemDetailsParams parameter:
The compulsoriness of parameters is specified for use within the block. If the block is optional and not included in the request, then the parameters included in it should not be transferred.

Name Type Mandatory Description
value ANS..255 yes Additional information on the product item
name ANS..255 yes Name of the product item detail description parameter


Parameters of the discount:
The compulsoriness of parameters is specified for use within the block. If the block is optional and not included in the request, then the parameters included in it should not be transferred.

Name Type Mandatory Description
discountType ANS..20 yes Type of discount for a product item
discountValue N..20 yes The value of the discount for the product item


Parameters of the agentInterest:
The compulsoriness of parameters is specified for use within the block. If the block is optional and not included in the request, then the parameters included in it should not be transferred.

Name Type Mandatory Description
interestType ANS..20 yes Type of agent fee for the product sale
interestValue N..20 ла Value of agent fee for the product sale


Parameters of the tax:
The compulsoriness of parameters is specified for use within the block. If the block is optional and not included in the request, then the parameters included in it should not be transferred.

Name Type Mandatory Description
taxType N..2 yes

VAT rate, the following values are available:

  • "0" – without VAT;
  • "1" – VAT at the rate of 0%;
  • "2" – receipt VAT at the rate of 10%;
  • "3" – receipt VAT at the rate of 18%;
  • "4" – receipt VAT at the estimated rate 10/110;
  • "5" – receipt VAT at the estimated rate 18/118;
  • "6" – receipt VAT at the rate of 20%;
  • "7" – receipt VAT at the estimated rate 20/120;

Mandatory for sellers with fiscalization
taxSum N..18 no The amount of tax calculated by the seller. Specified in minimum currency units.

Response parameters:

Name Type Mandatory Description
orderId ANS36 no The order number in the payment system. It is unique within the system. It is missing if the order registration failed due to an error detailed in errorCode.
formUrl AN..512 no URL of the payment form to which the client's browser is to be redirected. It is not returned if the order registration failed due to an error detailed in ErrorCode.
errorCode N3 no Error code. It may be missing if the result did not lead to an error.
errorMessage AN..512 no Error description in the language passed in the language parameter in the request.

Error codes ( errorCode field):

Meaning Description
1 Order with given order number is processed already
3 Currency is not defined
4 The order number cannot be empty
4 The merchant's name cannot be empty
4 Empty amount
4 The return URL cannot be empty
4 The password cannot be empty
5 The value of one of the parameters is incorrect
5 Access denied
5 The user is disabled
7 System error
8 Absence of a mandatory Shopping Cart parameter
8 The currency in the Shopping Cart does not match the currency of the order
8 The amount of product items in the Shopping cart does not match the total amount of the order
8 Invalid Shopping Cart format
8 The quantity value is too large or too small

Example of a POST request:

        amount=24000&
currency=643&
language=ru&
orderNumber=01a287222222299&
returnUrl=https://tws.egopay.ru/ab/finish.html&
jsonParams={"name1":"value1"}&
merchantLogin=merch_child&
taxSystem=0&

orderBundle=
{ 

"orderCreationDate":"2013-07-12T13:51:00",

"customerDetails":{ "email":"email@email.com", "phone": "79851231234","contact": "Mega  Tester", "deliveryInfo":{ "deliveryType":"courier", "country":"RU",  "city":"Moscow",
"postAddress":"Zemlyanoy Val 50A  bid.2" }},

"cartItems":  

{ "items": 

[  
{ "positionId": "1", 
"name": "Metzeler Enduro 3 Sahara",
"itemDetails": { "itemDetailsParams": [{ "value": "Metzeler ", "name": "brand" },
{ "value": "17inch", "name": "radius" }]}, 
"quantity": { "value": 0.71, "measure": "штук" },
"itemAmount": 8000, 
"itemCurrency": "643", 
"itemCode": "NM-15",
"discount": { "discountType": "percent", "discountValue": "5" },
"agentInterest": { "interestType": "agentPercent", "interestValue": "7" }, 
"tax": {"taxType": 1,"taxSum": 111}, 
"itemPrice": 11267
},

{ "positionId": "2", 
"name": "Universal Mirror Enduro",
"itemDetails": { "itemDetailsParams": [{ "value": "Noname", "name": "brand" },
{ "value": "12mm", "name": "diameter" }]}, 
"quantity": { "value": 1.0, "measure": "штук" },
"itemAmount": 8000, 
"itemCurrency": "643", 
"itemCode": "NM-15",
"discount": { "discountType": "percent", "discountValue": "5" },
"agentInterest": { "interestType": " agentPercent ", "interestValue": "7" }, 
"tax": {"taxType": 1,"taxSum": 111}, 
"itemPrice": 8000 
},

{ "positionId": "3", 
"name": "Warm Grips",
"itemDetails": { "itemDetailsParams": [ { "value": "Noname", "name": "brand" }]},
"quantity": { "value": 1.0, "measure": "штук" }, 
"itemAmount": 8000, 
"itemCurrency": 643,
"itemCode": "G-16", 
"discount": { "discountType": "percent", "discountValue": "5" },
"agentInterest": { "interestType": " agentPercent ", "interestValue": "7" }, 
"tax": {"taxType": 1,"taxSum": 111}, 
"itemPrice": 8000 
}
] 

} 

}

Response example: 

        {"formUrl":"https://tws.egopay.ru/ab/merchants/789/payment_ru.html?mdOrder=fc122907-e237-440e-9f25-48bf6120984b","orderId":"fc122907-e237-440e-9f25-48bf6120984b"}

Completion request for the full amount of pre-authorization

To request the debit of the full amount of pre-authorization, the deposit.do.
This operation is available to users who have the appropriate rights in the system.
Request parameters:

Name Type Mandatory Description
userName AN..30 yes The store's login received when connecting
password AN..30 yes The store's password received when connecting
orderId AN..64 yes The order number in the payment system. It is unique within the system.
amount N..5 yes To complete for the full amount of pre-authorization, you must transfer the full amount of the order in money or 0 in the request.
language A2 no The language is encoded in ISO 639-1. The error message will be returned in this language.
agent - no A block for transmitting agent data (see the description below).
supplierPhones array ANS..19 no An array of supplier's phone numbers in the +N format.

Parameters of the agent

Name Type Mandatory Description
agentType N..2 yes (if a block is transmitted)

Agent type, one of the following values is possible:

  • "1" - bank payment agent;
  • "2" - bank payment subagent;
  • "3" - payment agent;
  • "4" - payment subagent;
  • "5" - designated agent;
  • "6" - commission agent;
  • "7" - other agent.
payingOperation ANS..24 no Name of the payment agent's operation.
payingPhones array ANS..19 no Array of phone numbers of the payment agent in the +N format..
paymentsOperatorPhones array ANS..19 no Array of phone numbers of the payment acceptance operator in the +N format..
MTOperatorPhones array ANS..19 no Array of phone numbers of the transfer operator in the +N format.
MTOperatorName ANS..64 no Name of the transfer operator.
MTOperatorAddress ANS..256 no Address of the transfer operator.
MTOperatorInn N10..12 no TIN of the transfer operator.

Response parameters:

Name Type Mandatory Description
errorCode N3 yes Error code. Possible values are shown in the table below.
errorMessage AN..512 no Error description in the language passed in the language parameter in the request.

Error codes (ErrorCode field):

Meaning Description
0 Request processing took place without system errors
5 The deposit amount exceeds the reserved amount
5 The deposit amount must be greater than zero or at least one ruble
5 Access denied
5 The user must change password
6 Invalid order number
6 orderId not set
7 The payment must be in the correct state
7 System error
8 The specified completion amount does not match the full amount of the order. A Shopping Cart is needed to complete an incomplete amount of pre-authorization

Example of a POST request 

        currency=643&language=ru&orderId=f57db9df-5885-483d-8d5e-8e592d60ec9d&amount=0

Response example

        {"errorCode":"0","errorMessage":"Success"}

Completion for a partial amount of pre-authorization

To request the debit of the partial amount of pre-authorization, the deposit.do request is used.
This operation is available to users who have the appropriate rights in the system.
The The Requirements for the generation of requests for the order completion with a Shopping cart section contains a list of conditions necessary for the correct generation of the request.
Request parameters:

Name Type Mandatory Description
userName AN..30 yes The store's login received when connecting
password AN..30 yes The store's password received when connecting
orderId AN..64 yes The order number in the payment system. It is unique within the system.
amount N..5 yes The debit amount in the order currency (in minimum units). It must match the total amount of the debit for all product items in the Completion Shopping cart.
language A2 no The language is encoded in ISO 639-1. The error message will be returned in this language.
depositItems - yes A tag with the attributes of the product items of the Shopping Cart
agent - no A block for transmitting agent data (see the description below).
supplierPhones array ANS..19 no An array of supplier's phone numbers in the +N format.

Parameters of the agent

Name Type Mandatory Description
agentType N..2 yes (if a block is transmitted)

Agent type, one of the following values is possible:

  • "1" - bank payment agent;
  • "2" - bank payment subagent;
  • "3" - payment agent;
  • "4" - payment subagent;
  • "5" - designated agent;
  • "6" - commission agent;
  • "7" - other agent.
payingOperation ANS..24 no Name of the payment agent's operation.
payingPhones array ANS..19 no Array of phone numbers of the payment agent in the +N format..
paymentsOperatorPhones array ANS..19 no Array of phone numbers of the payment acceptance operator in the +N format..
MTOperatorPhones array ANS..19 no Array of phone numbers of the transfer operator in the +N format.
MTOperatorName ANS..64 no Name of the transfer operator.
MTOperatorAddress ANS..256 no Address of the transfer operator.
MTOperatorInn N10..12 no TIN of the transfer operator.

Parameters of the depositItems:
The compulsoriness of parameters is specified for use within the block. If the block is optional and not included in the request, then the parameters included in it should not be transferred.

Name Type Mandatory Description
items N/A yes An array element with the attributes of the product item in the Shopping cart. The description is given below.


Attributes of the items:
The compulsoriness of parameters is specified for use within the block. If the block is optional and not included in the request, then the parameters included in it should not be transferred.

Name Type Mandatory Description
positionId ANS..12 yes Unique identifier of the product item inside the Order Shopping Cart
name ANS..100 yes The name or description of the product item in free form
itemDetails N/A no An additional tag with the parameters of the description of the product item. The description is given below.
quantity N/A yes The block of parameters describing the total number of product items of one positionId and their measure.The description is given below.
itemAmount N..18 No (see description) The sum of the cost of all product items of one positionID in minimum currency units. itemAmount is required to be transferred only if the itemPrice parameter was not transferred. Otherwise, itemAmount transfer is not required. If both parameters are transferred in the request: itemPrice and itemAmount, then itemAmount must be equal to ItemPrice quantity, otherwise the request will fail with an error. When calculating the itemAmount = ItemPrice quantity parameter, the result is rounded to the second digit after the decimal separator. For example, if the result of calculations is 100.255, then the final result will be 100.26.
itemCurrency N..3 no The currency code of the product item ISO 4217. If not specified, it is considered equal to the order currency.
itemCode ANS..100 yes The number (identifier) of the product item in the store's system
discount N/A no An additional tag with attributes describing the discount for the product item. The description is given below.
agentInterest N/A no An additional tag with attributes describing the agent fee for the sale of goods. The description is given below.
tax N/A yes - for fiscalization (for stores without fiscalization settings the parameter is not necessary) Additional block with tax description attributes. The description is is given below.
itemPrice N..18 yes - for fiscalization (for stores without fiscalization settings the parameter is not necessary) The cost of one product item of one positionId in minimum currency units. Mandatory for merchants with fiscalization.
itemAttributes See description no A block intended for transmitting a set of attributes of a product item. A description of the available attributes is provided below.

Parameters of the itemAttributes:
Attributes should be specified as follows

        <attributes  name="attribute_name_2">attribute_value_2</attributes>
Name Type Mandatory Description
paymentMethod N..2 yes

Attribute of the payment method, the following values are available:

  • "1" - full preliminary payment before the transfer of the subject of payment;
  • "2" - partial preliminary payment until the transfer of the subject of payment;
  • "3" - advance;
  • "4" - full payment at the time of transfer of the subject of payment;
  • "5" - partial payment of the subject of payment at the time of its transfer with subsequent credit payment;
  • "6" - transfer of the subject of payment without its reimbursement at the time of its transfer with subsequent credit payment;
  • "7" - payment of the subject of payment after its transfer with credit payment..
paymentObject N..2 yes

The attribute of the subject of payment, the following values are available:

  • "1" - product;
  • "2" - excisable product;
  • "3" - work;
  • "4" - service;
  • "5" - gambling bet;
  • "6" - gambling winnings;
  • "7" - lottery ticket;
  • "8" - lottery winnings;
  • "9" - provision of IPR (intellectual property results);
  • "10" - payment;
  • "11" - agent fee;
  • "12" - compound subject of payment;
  • "13" - other subject of payment.
nomenclature ANS no The code of the product item in the hexadecimal representation. The maximum length is 32 bytes in HEX encoding.

Example of a representation:
1. 00 00 00 01 00 21 FA 41 00 23 05 41 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 12 00 AB 00
2. 000000010021FA4100230541000000000000000000000000000000001200AB00

Thus, the representation is possible with or without spaces.
The presence of spaces is optional.
supplier_info.phones Array ANS..19 no An array of supplier's phone numbers in the +N format.
supplier_info.name ANS..256 no Supplier's name.
supplier_info.inn N10..12 no Supplier's TIN.
agent_info.type N..2 Mandatory only if the agent_info object is transferred.

Agent type, one of the following values is possible:

  • "1" - bank payment agent;
  • "2" - bank payment subagent;
  • "3" - payment agent;
  • "4" - payment subagent;
  • "5" - designated agent;
  • "6" - commission agent;
  • "7" - other agent.
agent_info.paying.operation ANS..24 no Name of the payment agent's operation.
agent_info.paying.phones array ANS..19 no Array of phone numbers of the payment agent in the +N format..
agent_info.paymentsOperator.phones array ANS..19 no Array of phone numbers of the payment acceptance operator in the +N format..
agent_info.MTOperator.phones array ANS..19 no Array of phone numbers of the transfer operator in the +N format.
agent_info.MTOperator.name ANS..64 no Name of the transfer operator.
agent_info.MTOperator.address ANS..256 no Address of the transfer operator.
agent_info.MTOperator.inn ANS..256 no TIN of the transfer operator.


Parameters of the quantity block:
The compulsoriness of parameters is specified for use within the block. If the block is optional and not included in the request, then the parameters included in it should not be transferred.

Name Type Mandatory Description
value N..18 yes The number of product items of this positionId. To specify fractional numbers, use a decimal point
measure ANS..20 yes A product item quantity measure


Parameters of the itemDetails:
The compulsoriness of parameters is specified for use within the block. If the block is optional and not included in the request, then the parameters included in it should not be transferred.

Name Type Mandatory Description
itemDetailsParams ANS..255 no An array of blocks, each of which conveys information about a certain characteristic of a product item. The description is given below.


Parameters of the itemDetailsParams block:
The compulsoriness of parameters is specified for use within the block. If the block is optional and not included in the request, then the parameters included in it should not be transferred.

Name Type Mandatory Description
name AN..255 yes Name of the product item detail description parameter


Parameters of the discount:
The compulsoriness of parameters is specified for use within the block. If the block is optional and not included in the request, then the parameters included in it should not be transferred.

Name Type Mandatory Description
discountType ANS..20 yes Type of discount for a product item
discountValue N..20 yes The value of the discount for the product item


Parameters of the agentInterest:
The compulsoriness of parameters is specified for use within the block. If the block is optional and not included in the request, then the parameters included in it should not be transferred.

Name Type Mandatory Description
interestType ANS..20 yes Type of agent fee for the product sale
interestValue N..20 yes Value of agent fee for the product sale


Parameters of the tax:
The compulsoriness of parameters is specified for use within the block. If the block is optional and not included in the request, then the parameters included in it should not be transferred.

Name Type Mandatory Description
taxType N..2 yes

VAT rate, the following values are available:

  • "0" – without VAT;
  • "1" – VAT at the rate of 0%;
  • "2" – receipt VAT at the rate of 10%;
  • "3" – receipt VAT at the rate of 18%;
  • "4" – receipt VAT at the estimated rate 10/110;
  • "5" – receipt VAT at the estimated rate 18/118;
  • "6" – receipt VAT at the rate of 20%;
  • "7" – receipt VAT at the estimated rate 20/120;

Mandatory for sellers with fiscalization
taxSum N..18 no The amount of tax calculated by the seller. Specified in minimum currency units.

Response parameters:

Name Type Mandatory Description
errorCode N3 yes Error code.
errorMessage AN..512 no Error description in the language passed in the language parameter in the request.

Missing when ErrorCode=0 |
Error codes (ErrorCode field):

Meaning Description
0 Request processing took place without system errors
5 The deposit amount must be greater than zero or at least one ruble
5 Access denied
5 The user must change password
6 Invalid order number
6 orderId not set
7 The payment must be in the correct state
7 System error
8 The required Shopping cart parameter is missing
8 The deposit amount is more than the amount at registration
8 The currency in the Shopping Cart does not match the currency of the order
8 The amount of product items in the Shopping cart does not match the total amount of the order
8 The original order does not contain a product item with this number
8 The quantity value is too large or too small

Example of a POST request 

        orderId=9659c922-f0fa-4b4f-9b09-8a754ad99c63&
amount=4441&
depositItems=
{"items": 

[
{ "positionId": "2", 
"name": "Universal Mirror Enduro",
"itemDetails": { "itemDetailsParams": [{ "value": "Noname", "name": "brand" },{"value": "12mm", "name": "diameter" }]}, 
"quantity": { "value": 1.0, "measure": "штук" },
"itemAmount": 3330, 
"itemCurrency": "643", 
"itemCode": "NM-15",
"discount": { "discountType": "percent", "discountValue": "5" },
"agentInterest": { "interestType": " agentPercent ", "interestValue": "7" }, 
"tax": {"taxType": 1,"taxSum": 111}, 
"itemPrice": 3330
},

{ "positionId": "3", 
"name": "Warm Grips",
"itemDetails": { "itemDetailsParams": [ { "value": "Noname", "name": "brand" }]},
"quantity": { "value": 1.0, "measure": "штук" }, 
"itemAmount": 1111, 
"itemCurrency": 643,
"itemCode": "G-16", 
"discount": { "discountType": "percent", "discountValue": "5" },
"agentInterest": { "interestType": " agentPercent ", "interestValue": "7" }, 
"tax": {"taxType": 1,"taxSum": 111},
"itemPrice": 1111
}
] 

}

Response example

        {"errorCode":"0","errorMessage":"Success"}

Request for order payment cancellation

The reverse.dorequest is used to cancel the order payment. The cancellation function is available within a limited time after payment, the exact terms must be specified in the Bank.
The payment cancellation operation can be performed only once. If it ends with an error, the repeated payment cancellation operation will fail.
This function is available to stores in agreement with the Bank. To perform the cancellation operation, the user must have the appropriate rights.
Request parameters:

Name Type Compulsoriness Description
userName AN..30 yes The store's login received when connecting
password AN..30 yes The store's password received when connecting
orderId ANS36 yes The order number in the payment system. It is unique within the system.
language A2 no The language is encoded in ISO 639-1. The error description is returned in this language. If the parameter is not available, the default language specified in the merchant's settings is used.

Response parameters:

Name Type Compulsoriness Description
errorCode N3 no Error code.
errorMessage AN..512 no Description of the error in the language.

Error codes (ErrorCode field):

Meaning Description
0 Request processing took place without system errors
5 Access denied
5 The user must change password
5 orderId not set
6 Invalid order number
7 The operation is not possible for the current payment status
7 Reversal is impossible. Reason: incorrect internal values, check the amount of hold, deposit
7 System error

Example of a POST request:

        language=ru&orderId=9231a838-ac68-4a3e-bddb-d9781433d852

Response example:

        {"errorCode":"0","errorMessage":"Success"}

Request for a full refund of the order payment

To request a full refund of the payment means, the refund.do request is used. Upon this request, the funds for the specified order will be returned to the payer. The request will end with an error if the funds for this order have not been debited.
This operation is available to users who have the appropriate rights in the system.
Request parameters:

Name Type Mandatory Description
userName AN..30 yes The store's login received when connecting
password AN..30 yes The store's password received when connecting
orderId AN..64 yes The order number in the payment system. It is unique within the system.
amount N..5 yes The refund amount in the order currency (in minimum units). It must be equal to the order amount in money.
language A2 no The language is encoded in ISO 639-1. The error message will be returned in this language.
jsonParams AN..1024 no

A block for passing additional merchant parameters. The fields for additional information and its subsequent storage are passed as: 

        {"<name1>":"<value1>",...,"<nameN>":"<valueN>"}

These fields can be passed to the Bank processing system to be subsequently displayed in the registries. This functionality can be enabled upon additional agreement with the bank during the integration period.
If sending notifications to a buyer is set up for a seller, the email address of a buyer must be passed in this block in the email parameter.

Response parameters:

Name Type Mandatory Description
errorCode N3 yes Error code. Possible values and their description are presented in the table below.
errorMessage AN..512 no Error description in the language passed in the language parameter in the request.

Error codes (ErrorCode field):

Meaning Description
0 Request processing took place without system errors
5 Access denied
5 The user must change password
5 The order number is not specified
5 Incorrect amount
6 Invalid order number
7 The payment must be in the correct state
7 The refund amount exceeds the amount debited
7 System error
8 The specified refund amount does not match the full amount of the order. For a partial refund, a Shopping cart is required

Example of a POST request 

        language=ru&orderId=c84105aa-0713-44e1-ae3b-4c5e09d49a7d&jsonParams={"name1":"value1"}&amount=24000

Response example

        {"errorCode":"0","errorMessage":"Success"}

Request for a partial refund of the order payment

The refund.do request is used for a partial refund of the order payment.
This operation is available to users who have the appropriate rights in the system.
Note For error-free processing of the request, it is enough to transfer the quantity and positionId parameters.

The Requirements for the generation of requests for the return of an order with a Shopping cart section contains a list of conditions necessary for the correct generation of the request.
Request parameters:

Name Type Mandatory Description
userName AN..30 yes The store's login received when connecting
password AN..30 yes The store's password received when connecting
orderId AN..64 yes The order number in the payment system. It is unique within the system.
amount N..20 yes The refund amount in the order currency (in minimum units). It shall match the total amount of all returned product items.
refundItems N/A N/A Shopping cart of order items. The description is given below.
language A2 no The language is encoded in ISO 639-1. The error message will be returned in this language
jsonParams AN..1024 no

A block for passing additional merchant parameters. The fields for additional information and its subsequent storage are passed as: 

        {"<name1>":"<value1>",...,"<nameN>":"<valueN>"}

These fields can be passed to the Bank processing system to be subsequently displayed in the registries. This functionality can be enabled upon additional agreement with the bank during the integration period.
If sending notifications to a buyer is set up for a seller, the email address of a buyer must be passed in this block in the email parameter.


Parameters of the refundItems block:
The compulsoriness of parameters is specified for use within the block. If the block is optional and not included in the request, then the parameters included in it should not be transferred.

Name Type Mandatory Description
items - no An array of blocks describing the product items in the Shopping Cart. The description of parameters of the blocks is presented below below. Information on each product item of the Shopping Cart is transmitted in a separate block included in the items.


Parameters of the, included in items:
The compulsoriness of parameters is specified for use within the block. If the block is optional and not included in the request, then the parameters included in it should not be transferred.

Name Type Mandatory Description
positionId N..12 yes Unique identifier of the product item inside the Order Shopping Cart
name ANS..100 yes The name or description of the product item in free form
itemDetails N/A no An additional block with the parameters of the description of the product item. Its attributes are described below.
quantity N/A yes An element describing the total number of product items of one positionId and their measure. Its attributes are described below.
itemAmount N..18 yes The amount refunded for this positionId in minimum currency units. It may be less than the payment amount for this positionId.
itemCurrency N3 no The currency code of the product item ISO 4217. If not specified, it is considered equal to the order currency.
itemCode ANS..100 yes The number (identifier) of the product item in the store's system
discount N/A no An additional block with attributes describing the discount for the product item. The description is given below.
agentInterest N/A no An additional block with attributes describing the agent fee for the sale of goods. The description is given below.
tax N/A no Additional block with tax description attributes. If the fiscalization settings are specified for the store, this block can be transmitted, but it is not mandatory (the values of the parameters of this block will not be checked). The description is given below.
itemPrice N..18 no The cost of one product item of one positionID in money in minimum currency units. If the fiscalization settings are specified for the store, this field can be transferred, but it is not mandatory (the value of this field will not be checked).
itemAttributes See description no A block intended for transmitting a set of attributes of a product item. A description of the available attributes is provided below.

Parameters of the itemAttributes block:
Attributes should be specified as follows

        <attributes  name="attribute_name_2">attribute_value_2</attributes>
Name Type Mandatory Description
paymentMethod N..2 yes

Attribute of the payment method, the following values are available:

  • "1" - full preliminary payment before the transfer of the subject of payment;
  • "2" - partial preliminary payment until the transfer of the subject of payment;
  • "3" - advance;
  • "4" - full payment at the time of transfer of the subject of payment;
  • "5" - partial payment of the subject of payment at the time of its transfer with subsequent credit payment;
  • "6" - transfer of the subject of payment without its reimbursement at the time of its transfer with subsequent credit payment;
  • "7" - payment of the subject of payment after its transfer with credit payment..
paymentObject N..2 yes

The attribute of the subject of payment, the following values are available:

  • "1" - product;
  • "2" - excisable product;
  • "3" - work;
  • "4" - service;
  • "5" - gambling bet;
  • "6" - gambling winnings;
  • "7" - lottery ticket;
  • "8" - lottery winnings;
  • "9" - provision of IPR (intellectual property results);
  • "10" - payment;
  • "11" - agent fee;
  • "12" - compound subject of payment;
  • "13" - other subject of payment.
nomenclature ANS no The code of the product item in the hexadecimal representation. The maximum length is 32 bytes in HEX encoding.

Example of a representation:
1. 00 00 00 01 00 21 FA 41 00 23 05 41 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 12 00 AB 00
2. 000000010021FA4100230541000000000000000000000000000000001200AB00

Thus, the representation is possible with or without spaces.
The presence of spaces is optional.
supplier_info.phones Array ANS..19 no An array of supplier's phone numbers in the +N format.
supplier_info.name ANS..256 no Supplier's name.
supplier_info.inn N10..12 no Supplier's TIN.
agent_info.type N..2 Mandatory only if the agent_info object is transferred.

Agent type, one of the following values is possible:

  • "1" - bank payment agent;
  • "2" - bank payment subagent;
  • "3" - payment agent;
  • "4" - payment subagent;
  • "5" - designated agent;
  • "6" - commission agent;
  • "7" - other agent.
agent_info.paying.operation ANS..24 no Name of the payment agent's operation.
agent_info.paying.phones array ANS..19 no Array of phone numbers of the payment agent in the +N format..
agent_info.paymentsOperator.phones array ANS..19 no Array of phone numbers of the payment acceptance operator in the +N format..
agent_info.MTOperator.phones array ANS..19 no Array of phone numbers of the transfer operator in the +N format.
agent_info.MTOperator.name ANS..64 no Name of the transfer operator.
agent_info.MTOperator.address ANS..256 no Address of the transfer operator.
agent_info.MTOperator.inn ANS..256 no TIN of the transfer operator.


Parameters of the quantity block:
The compulsoriness of parameters is specified for use within the block. If the block is optional and not included in the request, then the parameters included in it should not be transferred.

Name Type Mandatory Description
value N..18 yes The number of product items of one positionId.
measure ANS..20 yes A product item quantity measure


Parameters of the itemDetails block:
The compulsoriness of parameters is specified for use within the block. If the block is optional and not included in the request, then the parameters included in it should not be transferred.

Name Type Mandatory Description
itemDetailsParams N/A no Additional information on the product item. It is an array of blocks, each of which conveys information about a certain characteristic of a product item. The description is given below.


Parameters of the block included in itemDetailsParams:
The compulsoriness of parameters is specified for use within the block. If the block is optional and not included in the request, then the parameters included in it should not be transferred.

Name Type Mandatory Description
value ANS..255 yes Additional information on the product item
name ANS..255 yes Name of the product item detail description parameter


Parameters of the discount block:
The compulsoriness of parameters is specified for use within the block. If the block is optional and not included in the request, then the parameters included in it should not be transferred.

Name Type Mandatory Description
discountType ANS..20 yes Type of discount for a product item
discountValue N..20 yes The value of the discount for the product item


Parameters of the agentInterest:
The compulsoriness of parameters is specified for use within the block. If the block is optional and not included in the request, then the parameters included in it should not be transferred.

Name Type Mandatory Description
interestType ANS..20 yes Type of agent fee for the product sale
interestValue N..20 yes Value of agent fee for the product sale


Parameters of the tax:
The compulsoriness of parameters is specified for use within the block. If the block is optional and not included in the request, then the parameters included in it should not be transferred.

Name Type Mandatory Description
taxType N..2 yes

VAT rate, the following values are available:

  • "0" – without VAT;
  • "1" – VAT at the rate of 0%;
  • "2" – receipt VAT at the rate of 10%;
  • "3" – receipt VAT at the rate of 18%;
  • "4" – receipt VAT at the estimated rate 10/110;
  • "5" – receipt VAT at the estimated rate 18/118;
  • "6" – receipt VAT at the rate of 20%;
  • "7" – receipt VAT at the estimated rate 20/120;

Mandatory for sellers with fiscalization
taxSum N..18 no The amount of tax calculated by the seller. Specified in minimum currency units.

Response parameters:

Name Type Mandatory Description
errorCode N3 yes Error code.
errorMessage AN..512 no An error description in the language transferred in the language or default language parameter.

Error codes (ErrorCode field)

Meaning Description
5 Authorization denied
5 Access denied
6 Invalid order number
7 The payment must be in the correct state
7 Incorrect deposit amount (less than one ruble)
7 System error
8 Invalid format of the refundItems parameter
8 The required Shopping cart parameter is missing
8 The currency in the Shopping Cart does not match the currency of the order
8 The amount of product items in the Shopping cart does not match the total amount of the order
8 The quantity value is too large or too small
8 The original order does not contain a product item with the specified number

Example of a POST request 

        language=ru&
orderId=830603cd-a886-483a-9a23-c37fb8018096&
jsonParams={"name1":"value1"}&
amount=9000&
refundItems=
{"items": 

[  
{ "positionId": "2", 
"name": "Universal Mirror Enduro", 
"itemDetails":{ "itemDetailsParams": [{"value": "Noname", "name": "brand"}, {"value": "12mm", "name": "diameter" }]},
"quantity": { "value": 1.0, "measure": "штук" },
"itemAmount": 6000, 
"itemCurrency": "643", 
"itemCode": "NM-15",
"discount": { "discountType": "percent", "discountValue": "5" },
"agentInterest": { "interestType": " agentPercent ", "interestValue": "7" }, 
"tax": {"taxType": 1,"taxSum": 111}, 
"itemPrice": 6000
},

{ "positionId": "3", 
"name": "Warm Grips", 
"itemDetails": { "itemDetailsParams":[ { "value": "Noname", "name": "brand" }]}, 
"quantity": { "value": 1.0, "measure": "штук" },
"itemAmount": 3000, 
"itemCurrency": 643, 
"itemCode": "G-16",
"discount": { "discountType": "percent", "discountValue": "5" },
"agentInterest": { "interestType": " agentPercent ", "interestValue": "7" }, 
"tax": {"taxType": 1,"taxSum": 111}, 
"itemPrice": 3000
}
] 

}

Response example

        {"errorCode":"0","errorMessage":"Success"}

Request for information about the cash receipt

To get information about the receipts for the order, the getReceiptStatus.do. request is used. The following data can be transmitted in the request:

  • Order ID orderId or orderNumber;

  • reciept ID - uuid.
    If an order ID (OrderID or OrderNumber) is transferred, the response returns all receipts for this order. When transmitting only the receipt ID, the response returns information only about this receipt. If both the order ID and the receipt ID are specified, the response returns all the order receipts.
    Request parameters

    Name Type Compulsoriness Description
    userName AN..30 yes The store's login received when connecting.
    password AN..30 yes The store's password received when connecting.
    orderId ANS36 no The order number in the payment system. It is unique within the system. To fulfill the request, either the order number or the identifier in the fiscalizer must be specified.
    orderNumber AN..32 no The order number (ID) in the store's system. To fulfill the request, either the order number or the identifier in the fiscalizer must be specified.
    uuid ANS..32 no ID of the receipt in the fiscalizer. To fulfill the request, either the order number or the identifier in the fiscalizer must be specified.
    language A2 no The language is encoded in ISO 639-1. If not specified, it is assumed that the language is Russian. The error message will be returned in this language.

    Response parameters
    Note Some of the parameters returned may depend on the fiscal data operator used.

    Name Type Compulsoriness Description
    errorCode N3 no Error code
    errorMessage AN..512 no Error description in the language passed in the language parameter in the request.
    orderNumber AN..32 no Order number (ID) in the store's system
    orderId ANS36 no The order number in the payment system. It is unique within the system
    receipt - no Block with receipt parameters

    The Receipt block attributes are shown in the table below.

    Name Type Compulsoriness Description
    receiptStatus N2 yes The value of this parameter determines the status of the receipt. The field can take the following values: 0 - Payment sent; 1 - Payment delivered; 2 - Payment error; 3 - Refund sent; 4 - Refund delivered; 5 - Refund error.
    uuid ANS..32 no ID of the receipt in the fiscalizer.
    shift_number N no Shift number.
    receipt_number N no The number of the receipt in the shift.
    receipt_datetime S no The date and time of the receipt in the fiscal memory device. It is specified as the number of milliseconds that have passed since 00:00 on 1 January 1970.
    fn_number S..16 no The number of the fiscal memory device.
    ecrregistrationnumber S..20 no Registration number of the cash register equipment.
    device_number S..20 no Registration number of the cash register equipment.
    fiscaldocumentnumber N no Fiscal number of the document.
    fiscaldocumentattribute S..10 no Fiscal attribute of the document.
    amount_total NS..11 no The total amount of the receipt in rubles.
    serial_number S..20 no Factory number of the cash register equipment.
    OFD N/A no A block with parameters of the fiscal data operator. The description is given below.


The attributes of the OFD block are shown in the table below.

Name Type Compulsoriness Description
name S..256 no Name of the fiscal data operator.
website S..58 no Website of the fiscal data operator.
INN S12 no Taxpayer identification number of the fiscal data operator.

Error codes
The table below shows error codes and messages.

Error code Message
1 At least one of the parameters is required: orderId, orderNumber, uuid.
5 Access denied.
6 The receipt was not found.
7 System error.

Request example

        https://tws.egopay.ru/ab/rest/getReceiptStatus.do?userName=login-api&password=password&orderId=abd60d0c-e096-42c3-8b17-6081c67db214

Response example

        {"errorCode":"0","orderNumber":"220170606034051002_177","orderId":"abd60d0c-e096-42c3-8b17-6081c67db214","receipt":[{"receiptStatus":1,"uuid":"790925e5-739c-430c-9e92-79d9f14481a4","shift_number":"27","fiscal_receipt_number":"21","receipt_date_time":1499256900000,"fn_number":"9999078900006364","ecr_registration_number":"1234567890023481","fiscal_document_number":"21","fiscal_document_attribute":"3713381819","amount_total":10000}]}

Advanced request for order status

In order to request the status of a registered order, the getOrderStatusExtended.dorequest is used.
Request parameters

Name Type Compulsoriness Description
userName AN..30 yes The store's login received when connecting
password AN..30 yes The store's password received when connecting
orderId ANS36 yes* The order number in the payment system. It is unique within the system.
orderNumber AN..32 yes* Order number (ID) in the store's system.
language A2 no The language is encoded in ISO 639-1. If not specified, it is assumed that the language is Russian. The error message will be returned in this language.

Note The request must contain either orderId, либо orderNumber. If both parameters are present in the request, the OrderID is prioritized.
There are several sets of response parameters. Exactly what kind of sets of parameters will be returned depends on the version of getOrderStatusExtended specified in the seller's settings.

Name Type Mandatory Description getOrderStatusExtended version
orderNumber AN..32 yes The order number (ID) in the store's system. All versions.
orderStatus N2 no

The value of this parameter determines the order status in the payment system. List of possible values:

  • '0' The order is registered, but not paid for;
  • '1' The pre-authorized amount is reserved (for two-phase payments);
  • '2' Full authorization of the order amount has been carried out;
  • '3' Authorization canceled;
  • '4' A refund operation was performed on the transaction;
  • '5' Authorization has been initiated through the issuing bank's ACS;
  • '6' Authorization denied.

It is missing if the order has not been found.

 All versions.
actionCode N3 yes Response code. All versions.
actionCodeDescription AN..512 yes Decryption of the response code in the language transmitted in the language parameter in the request. All versions.
errorCode N3 no

Error code. The following options are possible:

  • '0' Request processing took place without system errors;
  • '1' orderId or orderNumber expected;
  • '5' Access denied;
  • '5' The user must change password;
  • '6' Order not found;
  • '7' System error.
All versions.
errorMessage AN..512 no Error description in the language passed in the language parameter in the request. All versions.
amount N..20 yes Payment amount in kopecks (or cents) All versions.
currency N3 no The payment currency code is ISO 4217. If not specified, it is considered equal to 810 (Russian rubles). All versions.
date ANS yes Order registration date. All versions.
orderDescription AN..512 no Description of the order transmitted during its registration All versions.
ip AN..20 yes The buyer's IP address. All versions.

The merchantOrderParams element is present in the response if the order contains additional seller parameters. Each additional order parameter is presented in a separate element of merchantOrderParams.

Name Type Mandatory Description getOrderStatusExtended version
name AN..20 no Name of the additional parameter All versions.
value AN..1024 no Value of the additional parameter All versions.

The cardAuthInfo element contains a structure consisting of a list of the secureAuthInfo element and the following parameters:

Name Type Mandatory Description getOrderStatusExtended version
pan N..19 no The masked number of the card that was used for payment. It is specified only after payment of the order. All versions.
expiration N6 no Card expiration date in the YYYYMM format. It is specified only after payment of the order. All versions.
cardholderName A..64 no Cardholder's name. It is specified only after payment of the order. All versions.
approvalCode AN6 no Payment authorization code. This field has a fixed length (6 characters) and can contain digits and Latin letters. It is specified only after payment of the order. All versions.
chargeback A..5 no Whether the funds were forcibly returned to the buyer by the bank. The following values are possible: true; false. 06 and above.
paymentSystem N..10 yes Payment system name. The following options are available: VISA; MASTERCARD; AMEX; JCB; CUP; MIR. 08 and above.
product AN..255 yes Additional information about corporate cards. This information is filled in by the technical support in the management console. If there is no such information, an empty value is returned. 08 and above.
paymentWay AS..14 yes The method of making the payment (payment with the input of card data, payment by bindings, etc.). 09 and above.

The secureAuthInfo element (the element consists of an eci element and a threeDSInfo element, which is a list of the cavv and xid parameters):

Name Type Mandatory Description getOrderStatusExtended version
eci N..4 no Electronic commercial indicator. It is specified only after the order payment and in case of appropriate permission. All versions.
cavv ANS..200 no The value of checking the authentication of the cardholder. It is specified only after the order payment and in case of appropriate permission. All versions.
xid ANS..80 no Electronic commercial transaction ID. It is specified only after the order payment and in case of appropriate permission. All versions.

The bindingInfo element consists of the following parameters:

Name Type Mandatory Description getOrderStatusExtended version
clientId ANS..255 no The client's number (ID) in the store's system, transmitted during the order registration. Present only if the store is allowed to create bindings. All versions.
bindingId AN..255 no ID of the binding created when paying for the order or used for payment. Present only if the store is allowed to create bindings. All versions.
authDateTime ANS no Date/time of authorization. 02 and above.
authRefNum AN..24 no The payment authorization account number that is assigned when registering the payment. 02 and above.
terminalId AN..10 no Terminal ID. 02 and above.

The paymentAmountInfo element consists of the following parameters:

Name Type Mandatory Description getOrderStatusExtended version
approvedAmount N..20 no The amount reserved on the card (used only for two-phase payments). 03 and above.
depositedAmount N..20 no The amount confirmed for debiting from the card. 03 and above.
refundedAmount N..20 no Refund amount. 03 and above.
paymentState A..10 no Order status. 03 and above.
feeAmount N..20 no Fee amount. 11 and above.

The bankInfo element consists of the following parameters:

Name Type Mandatory Description getOrderStatusExtended version
bankName AN..200 no Name of the Issuing bank. 03 and above.
bankCountryCode AN..4 no Country code of the issuing bank. 03 and above.
bankCountryName AN..160 no Name of the issuing bank's country in the language passed in the language parameter in the request, or in the language of the user who called the method, if the language is not specified in the request. 03 and above.
orderBundle See description no The block containing the Shopping cart of order items. Its attributes are described below. 03 and above.


orderBundle content

Name Type Mandatory Description getOrderStatusExtended version
customerDetails See description no The block of customer data. See the description below. 03 and above.
cartItems See description no The block with the attributes of product items of the Shopping Cart. Its attributes are described below. 03 and above.


customerDetails content

Name Type Mandatory Description getOrderStatusExtended version
email ANS..40 no The buyer's email address. 03 and above.
phone N.12 no Buyer's phone number. 03 and above.
fullName N..100 no Last name, first name and patronymic of the payer. 13 and above.
passport N.100 no The series and number of the payer's passport in the following format: 2222888888. 13 and above.
inn N.12 no Taxpayer identification number. It is allowed to transmit 10 or 12 characters. 13 and above.


cartItems content

Name Type Mandatory Description getOrderStatusExtended version
items See description no An array of blocks describing the product items in the product Shopping Cart. The description of the block parameters is presented below. Information on each product item of the shopping cart is transmitted in a separate block included in the items. 03 and above.


items content

Name Type Mandatory Description getOrderStatusExtended version
positionId N..12 no Unique identifier of the product item inside the Order Shopping Cart. 03 and above.
name ANS..100 no The name or description of the product item in free form. 03 and above.
quantity See description no An element describing the total number of product items of one positionId and their measure. Its attributes are described below. 03 and above.
itemAmount N..18 no The sum of the value of all product items of one positionId in money in minimum currency units. 03 and above.
depositedItemAmount N..18 no The amount in minimum currency units (for example, in kopecks) of one positionId, confirmed for debiting from the card. 03 and above.
itemCurrency N3 no The currency code of the product item ISO 4217. 03 and above.
itemCode ANS..100 no The number (identifier) of the product item in the store's system. The parameter must be unique within the request. 03 and above.


quantity content

Name Type Mandatory Description getOrderStatusExtended version
value N..18 no The number of product items of this positionId. To specify fractional numbers, use a decimal point. 03 and above.
measure ANS..20 no A product item quantity measure. 03 and above.

Example of a POST request:

        orderId=b9054496-c65a-4975-9418-1051d101f1b9&language=ru&merchantOrderNumber=0784sse49d0s134567890

Response example:

        {"errorCode":"0","errorMessage":"Success","orderNumber":"220170606034051002_28","orderStatus":2,"actionCode":0,"actionCodeDescription":"","amount":52500,"currency":"643","date":1499343399327,"depositedDate":1499343424170,"orderDescription":"","ip":"127.0.0.1","merchantOrderParams":[],"attributes":[{"name":"mdOrder","value":"467db186-3aaf-4ba1-a66d-403bdde6c86f"}],"cardAuthInfo":{"expiration":"202012","cardholderName":"test","approvalCode":"123456","paymentSystem":"VISA","pan":"411111**1111"},"authDateTime":1499343423166,"terminalId":"123456","authRefNum":"111111111111","paymentAmountInfo":{"paymentState":"DEPOSITED","approvedAmount":52500,"depositedAmount":52500,"refundedAmount":0,"feeAmount":0},"bankInfo":{"bankName":"test","bankCountryCode":"RU","bankCountryName":"Russia"},"orderBundle":{"customerDetails":{"email":"test@test.ru","phone":"79998887766"},"cartItems":{"items":[{"positionId":"1","name":"name","quantity":{"value":1.0,"measure":"me"},"itemAmount":52500,"depositedItemAmount":52500,"itemCurrency":643,"itemCode":"1246754788"}]}},"chargeback":false,"paymentWay":"CARD"}

Connection coordinates


When registering the seller, the representative is provided with a login and password that can be used in the personal area, and also needs to be used in the protocols.
The description of the test service (WSDL) is located at: https://tws.egopay.ru/ab/webservices/merchant-ws?wsdl .
URL for accessing REST methods:

Method name URL
Order registration https://tws.egopay.ru/ab/rest/register.do
Order registration with pre-authorization https://tws.egopay.ru/ab/rest/registerPreAuth.do
Request for order payment completion https://tws.egopay.ru/ab/rest/deposit.do
Request for order payment cancellation https://tws.egopay.ru/ab/rest/reverse.do
Request for a refund of the order payment https://tws.egopay.ru/ab/rest/refund.do
The original order does not contain a product item with the specified number https://tws.egopay.ru/ab/rest/getReceiptStatus.do
Advanced request for order status https://tws.egopay.ru/ab/rest/getOrderStatusExtended.do

Credentials for testing fiscalization (Orange Data FDO)

To test the fiscalization functionality through the Orange Data fiscal data operator in the payment gateway's personal area, use the following credentials:

  • TIN - 7728168971;

  • Group - 1.