Payment notification (paymentAviso)

Attention. This is an old version of the API. Switch to the Yandex.Checkout API.

Description

Yandex.Checkout uses this request to tell the merchant that the user's money was successfully transferred to the merchant's address. This means that the merchant is obligated to provide the user with the product or service that was paid for.

Method name

paymentAviso

Address for receiving request

avisoURL — The URL in the merchant's system. Stored on Yandex.Checkout. You can set it during activation.

Request parameters

Parameter

Type

Description

requestDatetime

dateTime

Time when request was formed in Yandex.Checkout.

paymentDatetime

dateTime

Time when the order payment was registered in Yandex.Checkout.

action

normalizedString, maximum 16 characters

Request type. Value: paymentAviso

When exchanging data in PKCS#7 format, it is passed as the opening tag of an XML document.

md5

normalizedString, exactly 32 uppercase hexadecimal characters

MD5 hash of the payment form parameters (rules for forming it)

shopId

long

Merchant ID issued by Yandex.Checkout.

shopArticleId

long

Product ID issued by Yandex.Checkout.

invoiceId

long

Unique transaction number in Yandex.Checkout.

orderNumber

normalizedString, maximum 64 characters

Order number in merchant's system. Passed only if it was indicated in the payment form.

customerNumber

normalizedString, maximum 64 characters

Customer ID assigned by merchant (sent in the payment form).

For example, the contract number, phone number, etc.

orderCreatedDatetime

dateTime

Time when order was registered in Yandex.Checkout.

orderSumAmount

CurrencyAmount

The order total sent in the sum parameter in the payment form.

orderSumCurrencyPaycash

CurrencyCode

Currency code for the order amount.

orderSumBankPaycash

CurrencyBank

Yandex.Checkout processing center code for order total.

shopSumAmount

CurrencyAmount

Total to be paid into merchant's account (order total minus Yandex.Checkout commission).

shopSumCurrencyPaycash

CurrencyCode

Currency code for shopSumAmount.

shopSumBankPaycash

CurrencyBank

Yandex.Checkout processing center code for shopSumAmount.

paymentPayerCode

YMAccount

Yandex.Money account number used for payment.

paymentType

normalizedString

Payment method for order. Payment method codes

cps_user_country_code

string, 2 characters

Payer's two-letter country code conforming to ISO 3166-1 alpha-2.

Parameters for B2B payments (paymentType=2S)
payment_purpose string Payment purpose.
vatType string Type of VAT. Possible values:
  • calculated — taxable;
  • untaxed — non-taxable.
vatRate string

VAT rate. Shown if vatType=calculated.

Possible values:

  • 0 — 0% VAT rate;
  • 7 — 7% VAT rate;
  • 10 — 10% VAT rate;
  • 18 — 18% VAT rate;
vatSum CurrencyAmount The VAT amount you sent in the payment form. Shown if vatType=calculated.
Information about the buyer company for B2B payments (paymentType=2S)
b2b_full_name string

Full name of the organization.

b2b_short_name string

Abbreviated name. Shown if available.

b2b_adress string

Address.

b2b_inn string

INN (TIN).

b2b_kpp string

KPP (TRRC).

b2b_bank string

Name of the bank.

b2b_bank_office string

Bank branch.

b2b_bik string

BIC.

b2b_account string Account number.

Any names other than those listed above

string

Parameters added to the payment form by the merchant.

Tip.
  • The Payer's country code (cps_user_country_code) comes from technical sources corresponding to the selected payment method. The customer does not confirm this information anywhere. Yandex.Checkout is likewise not responsible for the validity of this data.
  • Yandex.Checkout requests may contain parameters not described in this document. The merchant should ignore them.
  • Requests don't have to contain all the parameters. Only parameters that are needed for calculating the MD5 checksum are required (action, orderSumAmount, orderSumCurrencyPaycash, orderSumBankPaycash, shopId, invoiceId, customerNumber).
Parameters for electronic payment receipt

These parameters are present in the request if you set up interaction with your cloud sales register via Yandex.Checkout and transfer parameters for creating a receipt in the payment request. See Sending details for the receipt

Parameter Type Value
penReceiptDateTime string

Date and time of creating the receipt as recorded in the fiscal storage.

Format: dd.MM.yyyy HH:mm:ss

penReceiptTotal decimal (2 digits after the point) Total amount in the receipt.
penFnNumber string, maximum of 16 characters Number of the fiscal storage.
penFiscalDocumentNumber int Fiscal number of the document.
penFiscalDocumentAttribute string, maximum of 19 characters Fiscal feature of the document.
Note.

If the payment notification was not delivered (the merchant does not respond to repeated paymentAviso requests, or returns technical errors), the payment is considered unsuccessful by default. This means that Yandex.Checkout stops attempting to deliver notifications, marks the payment as undelivered, and does not enter it in the report of accepted payments. The amount of the unsuccessful payment will be automatically returned to the payer. The merchant can find "lost" notifications by using payment management (MWS) methods for cross-checking.

If you want these payments to be considered successful, you can choose a different processing option for undelivered notifications. In this case, Yandex.Checkout stops attempting to deliver notifications and marks the transfer as successful. The payment will be included in the accepted payments report according to the time of the last attempt to deliver the paymentAviso request. The merchant can then find these "lost notifications" by checking the report or by using payment management (MWS) methods.

You can change how this situation is handled on request. If you want to consider undelivered notifications successful, inform your Yandex.Checkout manager.

When paying via B2B payments (paymentType=2S) the payment is considered successful in any case, regardless of your response to the notification of payment.

Request example using an MD5 checksum

POST /path_to_paymentAviso HTTP/1.1
Host: someshop.ru
Content-Type: application/x-www-form-urlencoded

Request parameters

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

cps_user_country_code

RU

additionalField

Additional field added by the merchant

Request example in PKCS#7 format

POST /path_to_paymentAviso HTTP/1.1
Host: someshop.ru
Content-Type: application/pkcs7-mime
<?xml version="1.0" encoding="UTF-8"?><paymentAvisoRequest        requestDatetime="2011-05-04T20:38:00.000+04:00"         invoiceId="1234567"        shopId="13"         shopArticleId="456"        customerNumber="8123294469"        orderCreatedDatetime="2011-05-04T20:38:00.000+04:00"        paymentPayerCode="42007148320"        orderSumAmount="87.10"        orderSumCurrencyPaycash="643"         orderSumBankPaycash="1001"        shopSumAmount="86.23"        shopSumCurrencyPaycash="643"         shopSumBankPaycash="1001"        paymentDatetime="2011-05-04T20:38:10.000+04:00"        paymentType="AC">    <param key="additionalField1" val="Additional field 1"></param>    <param key="additionalField2" val="Additional field 2"></param></paymentAvisoRequest>

Response parameters

Parameter

Type

Description

performedDatetime

dateTime

Time in merchant's system when request was processed.

code

int

Code of the processing result. The table below lists possible values.

shopId

long

Store ID. Must match the shopId field in the request.

invoiceId

long

Yandex.Checkout transaction ID. Must match the invoiceId field in the request.

orderSumAmount

CurrencyAmount

The amount of the order in the currency defined by the orderSumCurrencyPaycash request parameter.

message

string, maximum of 255 characters

Text explanation if the payment is not accepted.

techMessage

string, maximum of 64 characters

Explanation of the merchant's response.

This is usually used for more detailed information about errors. Optional field.

Request processing result codes

Code

Value

Description

0

Successful

The merchant agreed and is ready to accept the transfer.

1

Authorization error

md5 parameter does not match result of calculating hash function. Fatal error.

200

Request parsing error

Merchant is not able to parse request. Fatal error.

Response example for successful processing

<paymentAvisoResponse performedDatetime="2011-05-04T20:38:11.000+04:00" code="0" invoiceId="1234567" shopId="13"/>

Response example with error

<paymentAvisoResponse performedDatetime="2011-05-04T20:38:11.000+04:00" code="1" message="md5 parameter value doesn't match the result of the calculation of the hash function"/>