Payment notification (paymentAviso)

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

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

customerNumber

normalizedString, maximum 64 characters

The customer ID assigned by the 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

Method of paying for the order. Payment method codes

cps_user_country_code

string, 2 characters

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

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, shopPassword).
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 data for receipts

ParameterTypeValue
penReceiptDateTimestring

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.
penFnNumberstring, maximum of 16 charactersNumber of the fiscal storage.
penFiscalDocumentNumberintFiscal number of the document.
penFiscalDocumentAttributestring, maximum of 19 charactersFiscal feature of the document.

Note. 

If the transfer 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.

You can choose a different method of processing undelivered notifications and consider such payments successful. In this case, Yandex.Checkout stops attempting to deliver notifications and marks the transfer as successful. The transfer is shown in the report on accepted transfers according to the time of the last attempt to deliver paymentAviso. The merchant can detect "lost notifications" by checking the report or using the 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.

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

paymentType

cps_user_country_code

42007148320

AC

RU

additionalField

Additional field added by the merchant

<param key="additionalField" val="Additional field added by the merchant"></param>

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

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

200

Request parsing error

The merchant is not able to parse the 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="The value of the md5 parameter doesn't match the hash result"/>