Appendix № 5. Version 1 

 
Эта страница больше не поддерживается. Новый Протокол приема платежей для магазинов.
 

Information Exchange Protocol for Transfers to Merchants. HTTP

commonHTTP version 3.0
13 June 2013

1. Overview

Yandex.Money payment service provides the protocol allowing merchants (hereinafter ‘Counterparty’) to receive notifications about accepted funds transfers instantly. By processing received data via their information system Counterparties will be able to reduce time between funds transfer and services or goods delivery to the Payer.
The following document describes the protocol that allows for the delivery of notifications to the Counterparty regardless of which technological platform and device the Counterparty uses.
1.1. Funds transfer flow diagram
The Counterparty shall put the ‘payment form’ containing information about the purchase (such as order amount, Counterparty’s ID, etc.) on the webpage where the customer (hereinafter ‘Payer’) can initiate a payment. By default the payment form shall be a static HTML, perhaps, with fields to be completed by the Payer. For instance, fields could be labeled ‘player account number’ and ‘total amount’ for deposit operations on an online game.
Simply put, the payer's web browser transmits the completed payment form to the Operator (see step 1 on the chart). The real method of data transfer invovles encryption of the transferred data.
On the basis of the data on the payment form, the Operator will prepare a contract for payment and send a check-order request to the Counterparty (steps 4-5). The Counterparty checks the order parameters and the Payer confirms the contract for payment (see steps 2-5 on the chart).
If the Counterparty confirms the check-order request and the Payer confirmed the contract for payment, then the Operator shall transfer money from the Payer’s account (step 6) and, if successful, shall send a ‘Notification of funds transfer’ (paymentAviso) to the Counterparty (steps 8-9).
The Counterparty may decline the order (funds transfer) at the ‘check-order’ stage only. The ‘Notification of funds transfer’ (paymentAviso) sent by the Operator to the Counterparty confirms the transfer of the funds.
As a result, the Payer receives a web page on the Operator's website (on the Yandex.Money portal), that informs him whether funds transfer was successful or not (step 7). Also a link with the text ‘Return to store’ appears. The Payer will be transferred to a URL determined by the Counterparty (successURL, failURL).
When the Payer clicks the link he can be redirected to the homepage of the Counterpart's site or the Counterparty can display the status of the Payer's order (step 10-11).
If the Counterparty’s response to the check-order request is affirmative, but the Counterparty doesn’t receive a ‘Notification of funds transfer’, then the Counterparty shall contact the Merchant Web Services to find out whether or not the funds transfer was processed or not. Once a day the Operator will send the Counterparty a list of successful funds transfers (hereinafter ‘register’). The Counterparty shall check the register against the ‘notifications of funds transfer’ received.
1.2. Operator-to-Counterparty session interaction sample scenario
1. The Payer fills out the payment form and sends it to the Operator.
Parameter nameValue
shopId13
shopArticleId456
Sum87.1
scid 1643
CustomerNumber8123294469
paymentTypeGP
paymentTypeProviderSVZNY
cps_emailname@domain.com
cps_phone81231234567
MyFieldCounterparty's custom field
2. The Operator creates a contract based on the information on the payment form, sends it to the Payer, and waits for confirmation of payment.
3. The Payer confirms the transfer.
4. The Operator requests that the Counterparty check the order.
Parameter nameValue
requestDatetime2011-05-04T20:38:00.000+04:00
actioncheckOrder
shopId13
shopArticleId456
invoiceId1234567
CustomerNumber8123294469
orderCreatedDatetime2011-05-04T20:38:00.000+04:00
orderSumAmount87.10
orderSumCurrencyPaycash643
orderSumBankPaycash1001
shopSumAmount86.23
shopSumCurrencyPaycash643
shopSumBankPaycash1001
paymentPayerCode42007148320
paymentTypeGP
MyFieldCounterparty's custom field
5. The Counterparty confirms the order is correct.
<?xml version="1.0" encoding="UTF-8"?>
<checkOrderResponse performedDatetime ="2011-05-04T20:38:01.000+04:00"
code="0" invoiceId="1234567"
shopId="13"/>
6. The Operator accepts and checks the transfer.
7. The Operator returns the result to the Payer’s web browser — a webpage with information about the successful (or unsuccessful) transfer. The link with the text ‘Return to store’ (step 10) also appears on this page.
8. The Operator notifies the Counterparty that the funds transfer has been processed.
Parameter nameValue
requestDatetime2011-05-04T20:38:00.000+04:00
actionpaymentAviso
shopId13
shopArticleId456
invoiceId1234567
CustomerNumber8123294469
orderCreatedDatetime2011-05-04T20:38:00.000+04:00
orderSumAmount87.10
orderSumCurrencyPaycash643
orderSumBankPaycash1001
shopSumAmount86.23
shopSumCurrencyPaycash643
shopSumBankPaycash1001
paymentPayerCode42007148320
paymentTypeGP
MyFieldCounterparty's custom field
9. The Counterparty confirms receipt of funds transfer notification.
<?xml version="1.0" encoding="UTF-8"?>
<paymentAvisoResponse
performedDatetime ="2011-05-04T20:38:11.000+04:00"
code="0" invoiceId="1234567"
shopId="13"/>
10. The Payer clicks the link ‘Return to store’.
11. The Counterparty creates a page for the Payer to be sent to. In this case, it's a static page.
Thanks for your purchase! A courier will contact you with the exact delivery time of your order.

2. Counterparty's integration options

To get started, the Counterparty should select, and provide the Operator with, the following options for the Counterparty's integration with the Operator:
2.1 Message format
The following options are mutually exclusive, so it is possible to choose only one format.
2.1.1 NVP/MD5 (default)
The data are transferred via HTTP/1.1 protocol using the POST request method. The message parameters (payment details) are packed into parameters of a POST request as the ‘name-value’ pairs. MIME-type: application/x-www-form-urlencoded.
One of the parameters (md5) contains the hash of the payment form data together with the secret word. The secret word should be set by the Counterparty.
2.1.1.3 The Counterparty's secret word
The rules for generating the hash for the payment form are described in a separate part of the document. If this format is chosen, the Counterparty shall provide the secret word to generate the hash. The Counterparty should check that the hash matches the data in the payment form, and decline the order (funds transfer) if the hash doesn't match the payment form data. If this option is selected, it should be noted that its security level is quite low (due to both the risk of disclosure of the secret word and the reliability of the md5 algorithm).
2.1.2 XML/PKCS#7
The data are transferred via HTTP/1.1 protocol using POST request method. The message parameters (payment details) are presented as an XML-document, put into a cryptographic message container in PKCS#7 format. MIME-type: application/pkcs7-mime. Data shall be verified by the Operator’s SSL-certificate.
The Counterparty shall verify digital signature and decline the order (funds transfer) if signature verification fails.
The Counterparty may keep the cryptographic messages for financial disagreement settlements.
The document conforms to the XML 1.0 (Fifth Edition) standard published here: http://www.w3.org/TR/xml/.
The generated document is put into PKCS#7 cryptographic message, described in the standard: http://www.ietf.org/rfc/rfc5652.txt. The PKCS#7 cryptographic message contains digital signature of the document. The PKCS#7 cryptographic message contains the current certificate of the Operator. Certification authority chains are not included. Data compression is not used. No encryption is used. The PKCS#7 cryptographic message is represented in PEM format (OpenSSL). The Operator’s certificates are compliant to the X.509 Version 3 standard: (http://www.ietf.org/rfc/rfc2459.txt).
This format is recommended as a high security alternative to the format described in p.2.1.1.
2.2 Character encoding
The option determines the character encoding of text data.
2.2.1 UTF-8 (default).
2.2.2 Windows-1251.
2.3 Counterparty name
The Counterparty's name will be displayed in the contract and may contain up to 128 characters.
2.4 Display of declined payment message
The option determines the ability of the Counterparty to show its own message to be displayed to the Payer in response to checkOrder request. See the ‘message’ parameter of the checkOrder response.
Possible values:
  • 2.4.1 True — message is displayed to the Payer on the unsuccessful transfer page if the funds transfer is declined;
  • 2.4.1 False — no message is displayed (default).
2.5 Transfers accounting if the notification of funds transfer is not delivered
This option determines the actions of both the Counterparty and the Operator in the case that the ‘notification of funds transfer’ is unable to be delivered to the Counterparty’s webserver (due to a lack of response from the Counterparty’s webserver for a long period of time or permanent technical errors on the Counterparty's webserver).
Possible values:
  • 2.5.1 Deem unsuccessful. The Operator stops attempts to deliver the notification, marks the notification as not delivered to the Counterparty and excludes the transfer from the register. Funds for an unsuccessful transfer will not be credited to the Counterparty’s bank account. If delivery of the notification of funds transfer fails, the money shall be returned to the Payer within two to three business days. The Counterparty can find ‘missed notifications’ using Merchant Web Services (by default).
  • 2.5.2 Deem successful. The Operator stops attempts to deliver the notification and marks the notification delivered/funds transfer successful. The Counterparty can find ‘missed notifications’ by using Merchant Web Services or by checking the register. The transfer will be included in the register according to the time the last notification is delivered.
2.6 Protocol for redirecting the Payer after funds transfer
This option determines the protocol for redirecting the Payer to the Counterparty’s website upon completion of the transfer.
Possible values:
  • 2.6.1 Static addresses for each of the Counterparty's articles as defined in the following settings for the article.
    NameDescription
    successURLURL for the link with the text ‘Return to store’ on the page displayed to the Payer after successful payment.
    failURLURL for the link with the text ‘Return to store’ on the page displayed to the Payer after unsuccessful payment.
  • 2.6.2 The addresses the Counterparty gives in the payment form.
    In this case the Counterparty should provide the payment form fields.
    NameDescription
    shopSuccessURLURL for the link with the text ‘Return to store’ on the page displayed to the Payer after successful payment.
    shopFailURLURL for the link with the text ‘Return to store’ on the page displayed to the Payer after unsuccessful payment.
2.7 Addresses for receiving requests from the Operator
Table 2.7.1. Address settings for receiving requests from the Operator
NameDescription
paymentAvisoURLURL(https), for ‘Notifications of funds transfer’ (paymentAviso) requests.
checkURLURL(https) for ‘check order parameters’ (checkOrder) requests.
2.8 Changes to the payment contract
Possible values:
  • 2.8.1 Fixed contract. The Operator displays the amount to be paid. The Counterparty may agree to accept the transfer as it is or refuse to receive the transfer (default).
  • 2.8.2 The Counterparty may change the transfer amount. The Operator displays the transfer amount. The Counterparty may agree to accept the transfer as it is, change the transfer amount, or refuse to accept the transfer.

3. Protocol overview

3.1 Payment form
The payment form determines order details and sending of the payment form initiates the funds transfer order and its processing (see steps 1-2 on funds transfer flow diagram).
There are two types of payment form parameters:
  • Operator’s parameters — the Counterparty receives the values from the Operator as constants upon integration;
  • User-defined custom parameters — those that are determined by the Counterparty itself, for example for identifying orders.
The Counterparty can assign unique numbers to orders, including them on the payment form (the ‘orderNumber’ field). The value of the field must be unique from all orders in the history of operations with the Counterparty. From the Operator’s side, the ‘orderNumber’ uniqueness is tracked in combination with the ‘shopID’ parameter.
If the amount of the order or its content is changed, the altered order must be assigned a new order number. If the Payer reaches step 3 (confirmation of payment) and then returns to the Counterpaty's site to change the order, and the order number remains the same, then the funds transfer will be declined and the Payer will receive an error message.
It should be taken into account, that all payment form fields are visible to the Payer and may be altererd by an unscrupulous payer. For example, if the payment form displays both the order number and total amount, an unscrupulous payer could leave the number unmodified and change the amount from 30,000 rubles to 30 rubles.
So the Counterparty should always verify all order details that come with the ‘checkOrder’ request (see steps 4-5) and decline any order (answer code=100 to the checkOrder request) if the details deviate from the expected ones.
The same verification is recommended after a funds transfer has been made (‘paymentAviso’ request from the Operator). For example, if the transfer amount is less than the order amount, the goods should not be shipped to the Payer until an additional payment is processed.
The Counterparty may specify the payment method that the Payer should use to complete the payment. The payment form fields ‘paymentType’ and ‘cps_provider’ should be used for specification of the payment method. If the payment method is omitted or contains an invalid value, the payment will be processed from the Payer’s Yandex.Money account or linked bank card (default payment method =‘PC’).
‘paymentType’ sepcifies the method by which the payment should be processed, and ‘cps_provider’ serves for clarification of any payment method details. Values for the parameters ‘paymentType’ and ‘cps_provider’ are case-sensitive.
If the Counterparty does not have the right to process payments with the method specified in the payment form fields ‘paymentType’ and ‘cps_provider’, the Payer will not be able to complete the payment.
Table 3.1.1. Payment form fields
NameDescriptionTypeRequired field
shopIdCounterparty ID. Issued by the Operator.xs:longYes
shopArticleIdArticle ID. Issued by the Operator.xs:longIf the Counterparty uses various payment forms for different articles (goods).
scidCounterparty's payment form ID. Issued by the Operator.xs:longYes
sumOrder total.CurrencyAmountYes
customerNumberPayer ID.
Phone number, contract number, etc., unique for the Counterparty.
xs:normalizedString, up to 64 charactersYes
orderNumberUnique order number in the Counterparty's system.xs:normalizedString, up to 64 charactersNo
shopSuccessURLURL for Payer redirection if funds transfer is successful (url-encoded value).xs:string, up to 250 charactersIf option 2.6.2 is used.
shopFailURLURL for Payer redirection if an error occurs (url-encoded value).xs:string, up to 250 charactersIf option 2.6.2 is used.
cps_providerPayment method details.PaymentTypeProviderUsed for payments at payment kiosks paymentType ="GP"
cps_emailPayer's email address.xs:string, up to 100 charactersNo
cps_phonePayer's phone number.xs:string, up to 15 characters, numbers onlyNo
paymentTypePayment method that should be used. Possible values:
PC — Yandex.Money account.
AC — bank card.
GP — via a code at a payment kiosk.
MC — cell phone payment.
List of possible values may be expanded.
PaymentTypeNo. ‘PC’ by default.
3.2 3.2. Operator to Counterparty request parameters
It is strongly recommended that the Counterparty use SSL (HTTPS) for receiving messages from the Operator to ensure that payment data is protected.
Requests must be authorized by the Counterparty according to the selected message format (options 2.1.1, 2.1.2).
It is also recommended that the Counterparty verify the IP addresses from which the Counterparty receives the Operator’s requests (a list of IP addresses will be provided during integration).
Table 3.2.1. Operator-to-Counterparty request parameters
Parameter nameDescriptionTypeNotes
requestDatetimeThe moment the request was generated in the Operator's system.xs:dateTime 
actionRequest code.
‘checkOrder’ (without quotation marks) for the ‘Order verification’ request.
‘paymentAviso’ (without quotation marks) for the ‘Notification of funds transfer’.
xs:normalizedString, up to 16 charactersOnly for NVP/MD5.
md5MD5 hash of the payment form, rules for generating it are described in a separate section of this document.xs:normalizedString, exactly 32 hexidecimal characters, all caps.Only if a password is specified in the Counterparty's settings.
Only for NVP/MD5.
shopIdCounterparty’s ID in Yandex.Money’s service. Assigned by the Operator.xs:long  
shopArticleIdArticle ID, assigned by the Operator.xs:longIf the Counterparty uses separate payment forms for different goods (articles).
invoiceIdUnique transaction number in the Operator's system.xs:long 
orderNumberOrder number in the Counterparty’s system (sent in the payment form).xs:normalizedString, up to 64 characters.Provided only if specified on the payment form.
customerNumberPayer ID (sent in the payment form).
Phone number, contract number, etc., unique for the Counterparty.
xs:normalizedString, up to 64 characters.  
orderCreatedDatetimeThe moment (exact time) of the order's registration in the Operator's system.xs:dateTime  
orderSumAmountOrder total.CurrencyAmountMay differ from the real amount paid by the Payer if the currency of the funds transfer differs from the currency of the article (if this is the case, the Operator is responsible for all currency conversions).
orderSumCurrencyPaycashCurrency code for the order total.CurrencyCode  
orderSumBankPaycashThe Operator's processing center code for the order total.CurrencyBank  
shopSumAmountAmount to be received on the Counterparty's bank account: the order total less the Operator's commission.CurrencyAmount  
shopSumCurrencyPaycashCurrency code for the amount to be received on the Counterparty's bank account.CurrencyCode  
shopSumBankPaycashThe Operator's processing center code for the amount to be received on the Counterparty's bank account.CurrencyBank 
paymentPayerCodePayer's virtual account number in the Operator's system.YMAccountMay be omitted if the ‘Order verification’ request is initiated before the contract is shown to the Payer.
paymentDatetimeThe moment (exact time) of the order's payment in the Operator's system.xs:dateTimeNot included in the ‘checkOrder’ request
paymentTypePayment method used.PaymentType  
Any names not listed aboveFields added to the payment form by the Counterparty.xs:stringThe total length of all fields added by the Counterparty should not exceed 4096 characters.
3.3. Counterparty webserver response format
The response to the Operator’s request should be returned as an XML document within the body of the response to the HTTP request. The XML document must conform to the XML 1.0 (Fifth Edition) standard, available at http://www.w3.org/TR/xml/. The element and attribute names are case-sensitive.
MIME type: application/xml, the data transferred will be encoded in accordance with merchant integration option 2.2.
Table 3.3.1. Counterparty response fields
NameDescriptionTypeNotes
performedDatetimeRequest processing timestamp according to the Counterparty's timezone.xs:dateTimeFull ISO8601 time, including displacement relative to UTC
codeProcessing result code.xs:intSee Table 3.3.2.
shopIdCounterparty IDxs:longShould be identical to the request's ‘shopId’ field.
invoiceIdOrder number in the Operator's system.xs:longShould be identical to the request's ‘invoiceId’ field.
orderSumAmountAmount of the contract to be paid, displayed by the Operator.CurrencyAmountThe amount of the contract may only be displayed by the Counterparty in the currency defined by the parameter of the request ‘orderSumCurrencyPaycash’.
MessageMessage in case the order is declined by the Counterparty.Xs:string, up to 255 charactersThe Payer will see this text.
techMessageAdditional text description from Counterparty.xs:string, up to 64 charactersOptional field.
Generally used as extra information about errors.
Table 3.3.2. Result codes (‘code’ field values)
CodeNameNotes
0SuccessSuccess, including when the Operator has sent repeated notifications about the transfer.
1Authorization errorDigital signature or hash function verification failed.
2Success with payment contract changeSuccess. Consent to accepting the transfer with the paramerters given by the Counterparty. Changing the contract is only allowed in the ‘Order verification’ stage.
100Transfer declinedAcceptable only for response to “checkOrder” request.
If the Operator receives this code, it will not process the funds transfer.
200Bad requestThe Counterparty's webserver is unable to process the request due to incorrect parameter values.
1000Technical errorTemporary webserver errors.
Note: see description of operations.
Response examples shown below in description of operations.
Note: see description of operations.
Response examples shown below in description of operations.

Data types

Table 3.4.1 Data type definitions
TypeDescription
xs:int32-bit signed integer number. Int32 as defined by standard: http://www.w3.org/TR/xmlschema-2/#int
xs:long64-bit signed integer number. Int64, as defined by standard: http://www.w3.org/TR/xmlschema-2/#long
xs:decimalFixed-point decimal number as defined by standard: http://www.w3.org/TR/xmlschema-2/#decimal
xs:booleanLogical value (true/false), as defined by the standard: http://www.w3.org/TR/xmlschema-2/#boolean
xs:stringCharacter string as defined by standard: http://www.w3.org/TR/xmlschema-2/#string
xs:normalizedStringCharacter string as defined by standard: http://www.w3.org/TR/xmlschema-2/#normalizedString
xs:dateTimeTimestamp value in format conforms to these specifications:
The format is determined in the following way:
YYYY-MM-DDThh:mm:ss.fZZZZZ
Format description
YYYYyear, exactly 4 digits
MMmonth, exactly 2 digits (01=January, etc.)
DDday of the month, exactly 2 digits (from 01 to 31)
TLatin character ‘T’, should be uppercase
hhhours, exactly 2 digits (24-hour format, from 00 to 23)
mmminutes, exactly 2 digits (from 00 to 59)
ssseconds, exactly 2 digits (from 00 to 59)
ffraction of a second (from 1 to 6 digits),
may be omitted, in which case the delimiter ‘.’ should be omitted as well.
ZZZZZTime zone indicator, acceptable values:
Z — UTC, symbol ‘Z’ should be uppercase.
+hh:mm or -hh:mm — displacement relative to UTC (GMT) (indicates how many hours and minutes the given time zone is ahead or behind UTC).

All of the above elements are required except fractions of a second (in which case the delimiter ‘.’ should be omitted). If you can only give the date, then the time should be displayed as 00:00:00.
Examples:
2011-07-24T19:00:00+04:00 — 19 hours 00 minutes 24 July 2011, time zone — UTC + 4 hours.
2004-07-24T15:00:00Z — the same time in canonical form.
2004-07-24T15:00:00.666Z — the same time plus 666 milliseconds.
YMAccountVirtual account number in the Yandex.Money service, string of decimal numbers between 11 and 33 digits long.
< xs:simpleType name="YMAccount">
< xs:restriction base="xs:normalizedString">
< xs:minLength value="11"/>
<xs:maxLength value="33"/>
< xs:pattern value="[0-9]+"/>
</xs:restriction>
< /xs:simpleType>
CurrencyAmount
<xs:simpleType name="CurrencyAmount">
<xs:restriction base="xs:decimal">
<xs:minExclusive value="0"/>
<xs:maxInclusive value="9999999999999"/>
<xs:fractionDigits value="2"/>
</xs:restriction>
</xs:simpleType>
CurrencyCodeCurrency code. Possible values:
  • 643 — Russian ruble;
  • 10643 — test currency (demo-rubles for Yandex.Money demo-service).
<xs:simpleType name="CurrencyBank">
<xs:restriction base="xs:int">
</xs:restriction>
</xs:simpleType>
CurrencyBankOperator's Processing Center Code. Possible values:
  • 1001 — EkomBank;
  • 1003 — DemoBank.
<xs:simpleType name="CurrencyBank">
<xs:restriction base="xs:int">
</xs:restriction>
</xs:simpleType>
PaymentTypePayment method selected by the Payer. Case-sensitive string, two characters long. Possible values:
  • PC — for payments from a Yandex.Money user account or bank card linked to it.
  • AC — for payments from any bank cards not linked to a user's Yandex.Money account.
  • GP — for payments made at payment kiosks.
  • MC — for payments from cell phone balances.

The list of possible values may be expanded.
< xs:simpleType name="PaymentType">
<xs:restriction base="xs:normalizedString">
<xs:minLength value="2"/>
<xs:maxLength value="2"/>
</xs:restriction>
</xs:simpleType>
PaymentTypeProviderPayment method details. Case-sensitive string with length up to 5 characters. May carry different meanings, depending on the value of the parameter ‘paymentType’. If paymentType=GP (payment kiosk as payment method), PaymentTypeProvider may have the following values:
  • SVZNY — for payments made at Svyaznoy kiosks.
  • EURST — for payments made at Euroset stores.
  • OTHER — for payments made at any other payment kiosk.

The list of possible values may be expanded.
<xs:simpleType name="PaymentType">
<xs:restriction base="xs:normalizedString">
<xs:minLength value="1"/>
<xs:maxLength value="5"/>
</xs:restriction>
</xs:simpleType>

3.5. Link with the text ‘Return to store’

After the Payer clicks on the link ‘Return to store’ (see steps 10-11 in the flow chart),he will be redirected to the URL, specified in the Counterparty’s settings (successURL or failURL depending on whether the funds transfer was successful or not).
Additionally, in the case of successful transfer, ‘?action=PaymentSuccess’ is added to the URL while ‘?action=PaymentFail’ is added in the case of an unsuccessful transfer, as well as all parameters described in Table 3.2.1. ‘Operator-to-Counterparty request parameters’. Redirecting is performed using the GET method in the case of a successful transfer and using the POST method in the case of an unsuccessful transfer. It's important to understand that step 10 is performed from the Payer’s computer, so the Counterparty needs to authorize the Payer using its own means if they want to display personal information for the Payer. The standard authorization on the Counterparty’s website can be used (via cookies, etc.), otherwise the Counterparty's session keys can be added to the payment form (the Operator adds these parameters when redirecting to successURL/ failURL).

3.6. Rules for generating the hash of the payment form in the Operator's requests

MD5 hash is applied to the text generated as a succession of values of a subset separated by a semicolon  — ‘;’. This applies if the NVP/MD5 method of connection is selected.
Order of parameters sequence
action;orderSumAmount;orderSumCurrencyPaycash;orderSumBankPaycash;shopId;invoiceId;customerNumber;shopPassword
Example:
String (without carryovers)Result
checkOrder;87.10;643;1001;13;55;8123294469;s<kY23653f,{9fcnshwq1B35ABE38AA54F2931B0C58646FD1321

4. Protocol operations

4.1 Order verification (сheckOrder)
A request is sent to check whether the order with the given parameters can be issued to the Payer.
If the Counterparty‘s response is affirmative, the Operator will transfer money from the Payer's account, then, if the funds transfer is successful, send to the Counterparty a “Notification of funds transfer”.
The Counterparty can decline the transfer, in which case the Payer's account will not be charged.
If the integration option 2.2 is used, the Counterparty may change the amount to be paid. The amount to be paid should be displayed in the same currency as the price of the good.
The Counterparty should check the parameters of the funds transfer notification (paymentAviso, see below), to make sure the actual transfer was completed with the parameters requested by the Counterparty.
4.1 Counterparty response codes (the ‘code’ field)
0SuccessThe Counterparty has given consent and is ready to accept the transfer.
The Operator transfers funds from the Payer's account and, if that is successful, sends a ‘Notification of funds transfer’ (paymentAviso).
1Authorization errorDigital signature or hash verification failed. The Operator considers the error final and will not process the transfer.
2Success with payment contract changeSuccess. Consent to accepting the transfer with the parameters given by the Counterparty. The Operator will transfer funds from the Payer's account and, if this is successful, send a ‘Notification of funds transfer’ (paymentAviso).
100Transfer declinedThe Counterparty refuses to accept the order with the given parameters. The Operator considers the error final and will not process the funds transfer.
200Bad requestThe Counterparty webserver is unable to process the request. The Operator considers the error final and will not complete the transfer.
1000Technical errorTemporary webserver error.
The Operator will consider this error definitive and will not complete the transfer.
Example request in NVP/MD5 format
requestDatetime 2011-05-04T20:38:00.000+04:00
action checkOrder
md5 8256D2A032A35709EAF156270C9EFE2E
shopId 13
shopArticleId 456
invoiceId 1234567
customerNumber 8123294469
orderCreatedDatetime 2011-05-04T20:38:00.000+04:00
orderSumAmount 87.10
orderSumCurrencyPaycash 643
orderSumBankPaycash 1001
shopSumAmount 86.23
shopSumCurrencyPaycash 643
shopSumBankPaycash 1001
paymentPayerCode 42007148320
paymentType AC
MyField Counterparty's custom field
Example request in XML/PKCS#7 format
<?xml version="1.0" encoding="UTF-8"?>
<checkOrderRequest
requestDatetime="2011-05-04T20:38:00.000+04:00" invoiceId="1234567"
shopId="13" shopArticleId="1101"
customerNumber="№1-abcd/2010"
orderCreatedDatetime="2011-05-04T20:38:00.000+04:00"
paymentPayerCode="410011234567"
orderSumAmount="1000.00"
orderSumCurrencyPaycash="643" orderSumBankPaycash="1001"
shopSumAmount="990.00"
shopSumCurrencyPaycash="643" shopSumBankPaycash="1001"
paymentType="AC">
<param key="MyField" val="Counterparty's custom field"/>
</checkOrderRequest>
Example response from Counterparty's system: ‘Order verification’ successfully processed, the Counterparty has given consent and is ready to receive the transfer.
<?xml version="1.0" encoding="UTF-8"?>
<checkOrderResponse performedDatetime="2011-05-04T20:38:01.000+04:00"
code="0" invoiceId="1234567"
shopId="13"/>
Example response of the Counterparty's system: ‘Order verification’ successfully processed, the Counterparty has approved acceptance of the transfer and also changed the amount to be paid.
<?xml version="1.0" encoding="UTF-8"?>
<checkOrderResponse performedDatetime="2011-05-04T20:38:01.000+04:00"
code="2" invoiceId="1234567"
shopId="13" orderSumAmount="123.45"/>
Example: The Counterparty declined the transfer at the order verification stage. The Operator will not accept the transfer from the Payer.
<?xml version="1.0" encoding="UTF-8"?>
<checkOrderResponse performedDatetime="2011-05-04T20:38:01.000+04:00"
code="100" invoiceId="1234567"
shopId="13"
message="The phone number indicated does not exist"
techMessage="Invalid phone number"/>

4.2 Notification of funds transfer (paymentAviso)

The Counterparty's notification of accepted funds transfer from the Payer.
This request signifies the fact of successful funds transfer from the Payer to the Counterparty and the Counterparty's obligation to issue the good(s) to the Payer or another person, specified by the Payer.
The Counterparty cannot refuse to accept notifications about funds transfer.
Table 4.2. Counterparty response codes (‘code’ field)
0SuccessSuccessful. Including when the Operator sends multiple ‘Notifications of funds transfer’ (paymentAviso).
1Authorization errorDigital signature or hash verification failed. The Operator will not repeat the request and will mark the order with ‘Notification not delivered to the Counterparty’.
200Bad requestThe Counterparty's webserver cannot process the request. The Operator will not repeat the request and will mark the order: ‘Notification not delivered to the Counterparty’.
1000Technical errorTemporary webserver error.
The Operator will repeat this request.
Example request in NVP/MD5 format
requestDatetime 2011-05-04T20:38:00.000+04:00
action paymentAviso
md5 45125C95A20A7F25B63D58EA304AFED2
shopId 13
shopArticleId 456
invoiceId 1234567
customerNumber 8123294469
orderCreatedDatetime 2011-05-04T20:38:00.000+04:00
orderSumAmount 87.10
orderSumCurrencyPaycash 643
orderSumBankPaycash 1001
shopSumAmount 86.23
shopSumCurrencyPaycash 643
shopSumBankPaycash 1001
paymentDatetime 2011-05-04T20:38:10.000+04:00
paymentPayerCode 42007148320
paymentType AC
MyField Counterparty's custom field
Example request in XML/PKCS#7 format
<?xml version="1.0" encoding="UTF-8"?>
<paymentAvisoRequest
requestDatetime="2011-05-04T20:38:00.000+04:00" invoiceId="1234567"
shopId="1018" shopArticleId="1101"
customerNumber="№1-abcd/2010" orderCreatedDatetime="2011-05-04T20:38:00.000+04:00"
paymentPayerCode="410011234567"
orderSumAmount="1000.00"
orderSumCurrencyPaycash="643" orderSumBankPaycash="1001"
shopSumAmount="990.00"
shopSumCurrencyPaycash="643" shopSumBankPaycash="1001"
paymentDatetime="2011-05-04T20:38:10.000+04:00"
paymentType="AC">
<param key="MyField" val="Counterparty's custom field"/>
</paymentAvisoRequest>
Example Counterparty response — ‘Notification of funds transfer’ successfully processed by the Counterparty.
<?xml version="1.0" encoding="UTF-8"?>
<paymentAvisoResponse
performedDatetime ="2011-05-04T20:38:11.000+04:00"
code="0" invoiceId="1234567"
shopId="13"/>

5. Rules for the Counterparty's processing of Operator requests

1. The Counterparty's system should be able to respond to the Operator's requests within 10 seconds.
2. If the Counterparty does not respond to an ‘Order verification’ request or gives an answer other than ‘successful’, the Operator will inform the Payer that the transfer cannot be completed and will not charge the Payer's account.
3. If there is no response from the Counterparty after several repeated ‘Notifcation of funds transfer’ requests or multiple technical errors occur with the Counterparty's system, the Operator will stop attempts to deliver the notifications of funds transfer (first attempt after 1 minute, then up to 5 times with 5-30 minute intervals), after which the final status ‘unsuccessful’ will be assigned to the transfer.
4. The Operator assigns a unique number (invoiceId) to each funds transfer. The Counterparty should be ready to receive multiple ‘Notification of funds transfer’ messages for the same order (in case of connection troubles or error responses by the Counterparty’s webserver). The Counterparty should respond to repetitive notifications with a ‘successfully processed’ message. The Counterparty should identify transfers using the invoiceId parameter to prevent processing duplicated orders with identical invoiceIDs.