cURL
PHP
Python
 
Yandex.Checkout API Reference
The Yandex.Checkout API Reference describes all the Yandex.Checkout API methods. The API allows you to process online payments: send payment requests, save details for recurring payments, make refunds, and more.
More about integration via the Yandex.Checkout API 
cURL
PHP
Python
 
Payments
The API allows you to create, capture, and cancel payments, as well as receive payment information. How to process a payment 
cURL
PHP
Python
 
Payment object
The
Payment
object contains all currently relevant information about the payment. The object is generated during creation of a payment, and sent in response to any payment-related requests.
Parameter descriptions
Parameters
Description
 
id
string, required
Payment ID in Yandex.Checkout.
 
status
string, required
Payment status. Possible values:
pending
,
waiting_for_capture
,
succeeded
, and
canceled
. More about the life cycle of a payment 
 
amount
object, required
Payment amount. Sometimes Yandex.Checkout's partners charge additional commission from the users that is not included in this amount.
Nested parameters
 
value
string, required
Amount in the selected currency, in the form of a string with a dot separator, for example,
10.00
. The number of digits after the dot depends on the selected currency.
 
currency
string, required
Currency code in the ISO-4217 format. It should match the currency of your subaccount (
recipient.gateway_id
) if you separate payment flows, or the currency of the account (shopId in the Merchant Profile) if you don't.
 
income_amount
object, optional
Amount of payment to be received by the store: the
amount
value minus the Yandex.Checkout commission. If you're a partner  using an OAuth token for request authentication, make a request to the store for a right  to get information about commissions on payments.
Nested parameters
 
value
string, required
Amount in the selected currency, in the form of a string with a dot separator, for example,
10.00
. The number of digits after the dot depends on the selected currency.
 
currency
string, required
Currency code in the ISO-4217 format. It should match the currency of your subaccount (
recipient.gateway_id
) if you separate payment flows, or the currency of the account (shopId in the Merchant Profile) if you don't.
 
description
string, optional
Description of the transaction (maximum 128 characters) displayed in your Yandex.Checkout Merchant Profile, and shown to the user during checkout. For example, "Payment for order No. 72 for user@yandex.ru".
 
recipient
object, required
Payment recipient.
Nested parameters
 
account_id
string, required
Store's ID in Yandex.Checkout.
 
gateway_id
string, required
Subaccount's ID. Used for separating payment flows within one account.
 
payment_method
object, optional
Payment method 
used for this payment.
Nested parameters
Payment methods
Alfa-Click
 
type
string, required
Value:
alfabank
.
Payment method code.
 
id
string, required
Payment method ID.
 
saved
boolean, required
Saving payment methods allows conducting automatic recurring payments .
 
title
string, optional
Payment method name.
 
login
string, optional
User's login in Alfa-Click (linked phone number or the additional login).
 
captured_at
string, optional
Time of payment capture, based on UTC and specified in the ISO 8601 format.
 
created_at
string, required
Time of order creation, based on UTC and specified in the ISO 8601 format. Example:
2017-11-03T11:52:31.827Z
 
expires_at
string, optional
The period during which you can cancel or capture a payment for free. The payment with the
waiting_for_capture
status will be automatically canceled at the specified time. Based on UTC and specified in the ISO 8601 format. Example:
2017-11-03T11:52:31.827Z
 
confirmation
object, optional
Selected payment confirmation scenario. For payments requiring confirmation from the user. More about confirmation scenarios 
Nested parameters
Confirmation scenarios
Embedded
 
type
string, required
Value:
embedded
.
Confirmation scenario code.
 
confirmation_token
string, required
Token for the Yandex.Checkout widget  initialization.
 
test
boolean, required
The attribute of a test transaction.
 
refunded_amount
object, optional
The amount refunded to the user. Specified if the payment has successful refunds.
Nested parameters
 
value
string, required
Amount in the selected currency, in the form of a string with a dot separator, for example,
10.00
. The number of digits after the dot depends on the selected currency.
 
currency
string, required
Currency code in the ISO-4217 format. It should match the currency of your subaccount (
recipient.gateway_id
) if you separate payment flows, or the currency of the account (shopId in the Merchant Profile) if you don't.
 
paid
boolean, required
The attribute of a paid order.
 
refundable
boolean, required
Availability of the option to make a refund via API.
 
receipt_registration
string, optional
Delivery status of receipt data to online sales register (
pending
,
succeeded
, or
canceled
). For those who use the Yandex.Checkout .
 
metadata
object, optional
Any additional data you might require for processing payments (for example, order number), specified as a "key-value" pair and returned in response from Yandex.Checkout. Limitations: no more than 16 keys, no more than 32 characters in the key's title, no more than 512 characters in the key's value.
 
cancellation_details
object, optional
Commentary to the
canceled
status: who and why canceled the payment. More about canceled payments 
Nested parameters
 
party
string, required
The participant of the payment process that made the decision to cancel the payment. Possible values are
yandex_checkout
,
payment_network
, and
merchant
. More about initiators of payment cancelation 
 
reason
string, required
Reason behind the cancelation. The list and descriptions of possible values 
 
authorization_details
object, optional
Payment authorization details.
Nested parameters
 
rrn
string, optional
Retrieval Reference Number is a unique identifier of a transaction in the issuer's system. Used for payments via bank card.
 
auth_code
string, optional
Bank card's authorization code. Provided by the issuer to confirm authorization.
 
transfers
array, optional
Information about money distribution: the amounts of transfers and the stores to be transferred to. Specified if you use the Yandex.Checkout solution for marketplaces .
Nested parameters
 
account_id
string, required
ID of the store in favor of which you're accepting the receipt. Provided by Yandex.Checkout, displayed in the Sellers section of your Merchant Profile (shopId column).
 
amount
object, required
Amount to be transferred to the store.
Nested parameters
 
value
string, required
Amount in the selected currency, in the form of a string with a dot separator, for example,
10.00
. The number of digits after the dot depends on the selected currency.
 
currency
string, required
Currency code in the ISO-4217 format. It should match the currency of your subaccount (
recipient.gateway_id
) if you separate payment flows, or the currency of the account (shopId in the Merchant Profile) if you don't.
 
status
string, required
Status of the money distribution between stores. Possible values:
pending
,
waiting_for_capture
,
succeeded
,
canceled
.
 
platform_fee_amount
object, optional
Commission for sold products or services charged in your favor.
Nested parameters
 
value
string, required
Amount in the selected currency, in the form of a string with a dot separator, for example,
10.00
. The number of digits after the dot depends on the selected currency.
 
currency
string, required
Currency code in the ISO-4217 format. It should match the currency of your subaccount (
recipient.gateway_id
) if you separate payment flows, or the currency of the account (shopId in the Merchant Profile) if you don't.
Example of Payment object
{
  "id": "22e12f66-000f-5000-8000-18db351245c7",
  "status": "waiting_for_capture",
  "paid": true,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "created_at": "2018-07-18T10:51:18.139Z",
  "description": "Order No. 72",
  "expires_at": "2018-07-25T10:52:00.233Z",
  "metadata": {},
  "payment_method": {
    "type": "bank_card",
    "id": "22e12f66-000f-5000-8000-18db351245c7",
    "saved": false,
    "card": {
      "first6": "555555",
      "last4": "4444",
      "expiry_month": "07",
      "expiry_year": "2022",
      "card_type": "MasterCard",
      "issuer_country": "RU",
      "issuer_name": "Sberbank"
    },
    "title": "Bank card *4444"
  },
  "recipient": {
    "account_id": "100001",
    "gateway_id": "1000001"
  },
  "refundable": false,
  "test": false
  "income_amount": {
        "value": "1.97",
        "currency": "RUB"
  }
}
 
Create a payment
To accept a payment, you need to create a payment object,
Payment
. It contains all the necessary payment information (amount, currency, and status). Payments have a linear life cycle, going from one status to the next sequentially.
The response to the request will contain the payment object with the current status.
Request parameter descriptions
Request parameters
Description
 
amount
object, required
Payment amount. Sometimes Yandex.Checkout's partners charge additional commission from the users that is not included in this amount.
Nested parameters
 
value
string, required
Amount in the selected currency, in the form of a string with a dot separator, for example,
10.00
. The number of digits after the dot depends on the selected currency.
 
currency
string, required
Currency code in the ISO-4217 format. It should match the currency of your subaccount (
recipient.gateway_id
) if you separate payment flows, or the currency of the account (shopId in the Merchant Profile) if you don't.
 
description
string, optional
Description of the transaction (maximum 128 characters) displayed in your Yandex.Checkout Merchant Profile, and shown to the user during checkout. For example, "Payment for order No. 72 for user@yandex.ru".
 
receipt
object, optional
Data for creating a receipt in the online sales register (for compliance with 54-FZ ). Specify this parameter if you send the data for creating the receipt using one of these scenarios: Payment and receipt at the same time  or Payment after receipt .
Nested parameters
 
customer
object, optional
User details. You should specify at least the basic contact information: email address (
customer.email
) or phone number (
customer.phone
).
Nested parameters
 
full_name
string, optional
Name of the organization for companies, full name for sole proprietors and individuals. If the individual doesn't have a Tax Identification Number (INN), specify their passport information in this parameter. Maximum 256 characters.
Online sales register hat support this parameter: Orange Data, ATOL Online.
 
inn
string, optional
User's Tax Identification Number (INN) (10 or 12 digits).
 
email
string, optional
User's email address.
 
phone
string, optional
User's phone number. Specified in the ITU-T E.164, format, for example,
79000000000
.
 
items
array, required
List of products in an order (maximum 100 items).
Nested parameters
 
description
string, required
Product name (maximum 128 characters).
 
quantity
string, required
Product quantity. Maximum possible value depends on the model of your online sales register.
 
amount
object, required
Product price.
Nested parameters
 
value
string, required
Amount in the selected currency, in the form of a string with a dot separator, for example,
10.00
. The number of digits after the dot depends on the selected currency.
 
currency
string, required
Currency code in the ISO-4217 format. It should match the currency of your subaccount (
recipient.gateway_id
) if you separate payment flows, or the currency of the account (shopId in the Merchant Profile) if you don't.
 
vat_code
number, required
VAT rate. Possible value is a number from 1 to 6. More about VAT rates codes 
 
payment_subject
string, optional
Payment subject attribute. List of possible values 
 
payment_mode
string, optional
Payment method attribute. List of possible values 
 
product_code
string, optional
Product code is a unique number assigned to a unit of product during marking process.
Format: hexadecimal number with spaces. Maximum length is 32 bytes. Example:
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
.
Required parameter for marked products.
 
country_of_origin_code
string, optional
Country of origin code according to the Russian classifier of world countries (OK (MK (ISO 3166) 004-97) 025-2001). Example:
RU
.
Online sales register hat support this parameter: Orange Data, Kit Invest.
 
customs_declaration_number
string, optional
Customs declaration number (1 to 32 characters).
Online sales register hat support this parameter: Orange Data, Kit Invest.
 
excise
string, optional
Amount of excise tax on products including kopeks. Decimal number with 2 digits after the period.
Online sales register hat support this parameter: Orange Data, Kit Invest.
 
tax_system_code
number, optional
Store's tax system. The parameter is only required if you use several tax systems. Otherwise, the parameter is not specified. List of possible values 
 
phone
string, optional
User's phone number. Specified in the ITU-T E.164, format, for example,
79000000000
.
 
email
string, optional
User's email address.
 
recipient
object, optional
Payment recipient. Required for separating payment flows within one account or making payments to other accounts.
Nested parameters
 
gateway_id
string, required
Subaccount's ID. Used for separating payment flows within one account.
 
payment_token
string, optional
One-time payment token generated with the web or mobile SDK .
 
payment_method_id
string, optional
 
payment_method_data
object, optional
Data for making payments using a certain method  (
payment_method
). You can send the request without this object. If you do so, the user will be able to select the payment method on the Yandex.Checkout's side.
Nested parameters
Payment methods
Alfa-Click
 
type
string, required
Value:
alfabank
.
Payment method code.
 
login
string, optional
User's login in Alfa-Click. Mandatory for the External  scenario.
 
confirmation
object, optional
Information required to initiate the selected payment confirmation scenario by the user. More about confirmation scenarios 
Nested parameters
Confirmation scenarios
Embedded
 
type
string, required
Value:
embedded
.
Confirmation scenario code.
 
locale
string, optional
Language of the interface, emails, and text messages that will be displayed or sent to the user. Formatted in accordance with ISO/IEC 15897. Possible values:
ru_RU
,
en_US
,
de_DE
. Case sensitive.
 
save_payment_method
boolean, optional
Saving payment data (can be used for direct debits ). The
true
value initiates the creation of a reusable
payment_method
.
 
capture
boolean, optional
Automatic acceptance 
of an incoming payment.
 
client_ip
string, optional
User’s IPv4 or IPv6 address. If not specified, the TCP connection’s IP address is used.
 
metadata
object, optional
Any additional data you might require for processing payments (for example, order number), specified as a "key-value" pair and returned in response from Yandex.Checkout. Limitations: no more than 16 keys, no more than 32 characters in the key's title, no more than 512 characters in the key's value.
 
airline
object, optional
Object containing the data for selling airline tickets , used only for bank card payments.
Nested parameters
 
ticket_number
string, optional
Unique ticket number. If you already know the ticket number during payment creation,
ticket_number
is a required parameter. If you don't, specify
booking_reference
instead of
ticket_number
.
 
booking_reference
string, optional
Booking reference number, required if
ticket_number
is not specified.
 
passengers
array, optional
List of passengers.
Nested parameters
 
first_name
string, required
Passenger's first name.
 
last_name
string, required
Passenger's last name.
 
legs
array, optional
List of flight legs.
Nested parameters
 
departure_airport
string, required
Code of the departure airport according to IATA, for example, LED.
 
destination_airport
string, required
Code of the arrival airport according to IATA, for example, AMS.
 
departure_date
string, required
Departure date in the YYYY-MM-DD ISO 8601:2004 format.
 
carrier_code
string, optional
Airline code according to IATA.
 
transfers
array, optional
Information about money distribution: the amounts of transfers and the stores to be transferred to. Specified if you use the Yandex.Checkout solution for marketplaces .
Nested parameters
 
account_id
string, required
ID of the store in favor of which you're accepting the receipt. Provided by Yandex.Checkout, displayed in the Sellers section of your Merchant Profile (shopId column).
 
amount
object, required
Amount to be transferred to the store.
Nested parameters
 
value
string, required
Amount in the selected currency, in the form of a string with a dot separator, for example,
10.00
. The number of digits after the dot depends on the selected currency.
 
currency
string, required
Currency code in the ISO-4217 format. It should match the currency of your subaccount (
recipient.gateway_id
) if you separate payment flows, or the currency of the account (shopId in the Merchant Profile) if you don't.
 
platform_fee_amount
object, optional
Commission for sold products or services charged in your favor.
Nested parameters
 
value
string, required
Amount in the selected currency, in the form of a string with a dot separator, for example,
10.00
. The number of digits after the dot depends on the selected currency.
 
currency
string, required
Currency code in the ISO-4217 format. It should match the currency of your subaccount (
recipient.gateway_id
) if you separate payment flows, or the currency of the account (shopId in the Merchant Profile) if you don't.
cURL
PHP
Python
Request example
curl https://payment.yandex.net/api/v3/payments \
  -X POST \
  -u <Shop ID>:<Secret Key> \
  -H 'Idempotence-Key: <Idempotence Key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {
          "value": "2.00",
          "currency": "RUB"
        },
        "payment_method_data": {
          "type": "bank_card"
        },
        "confirmation": {
          "type": "redirect",
          "return_url": "https://www.merchant-website.com/return_url"
        },
        "description": "Order No. 72"
      }'
Request body example
{
  "id": "22e12f66-000f-5000-8000-18db351245c7",
  "status": "pending",
  "paid": false,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "confirmation": {
    "type": "redirect",
    "return_url": "https://www.merchant-website.com/return_url",
    "confirmation_url": "https://money.yandex.ru/payments/external/confirmation?orderId=22e12f66-000f-5000-8000-18db351245c7"
  },
  "created_at": "2018-07-18T10:51:18.139Z",
  "description": "Order No. 72",
  "metadata": {
    
  },
  "payment_method": {
    "type": "bank_card",
    "id": "22e12f66-000f-5000-8000-18db351245c7",
    "saved": false
  },
  "recipient": {
    "account_id": "100001",
    "gateway_id": "1000001"
  },
  "refundable": false,
  "test": false
}
 
List payments
The request allows you to receive the list of payments filtered by specified criteria.
The response will contain the list of payments with applied parameters of the request. The list includes the information about the payments created within the last 3 years. The list will be sorted by payment creation time in descending order.
If the number of results exceeds the value of 
limit
, the list will be provided in fragments. In this case, the response to the request will include a fragment of the list and the
next_cursor
parameter with a cursor to the next fragment.
More about working with lists 
Request parameter descriptions
Request parameters
Description
 
created_at.gte
string, optional
Filter by creation date: time must be greater than the specified value or equal ("from a certain moment inclusive"). Specified in the ISO 8601 format. Example:
created_at.gte=2018-07-18T10:51:18.139Z
 
created_at.gt
string, optional
Filter by creation date: time must be greater than the specified value ("from a certain moment exclusive"). Specified in the ISO 8601 format. Example:
created_at.gt=2018-07-18T10:51:18.139Z
 
created_at.lte
string, optional
Filter by creation date: time must be less than the specified value or equal ("until a certain moment inclusive"). Specified in the ISO 8601 format. Example:
created_at.lte=2018-07-18T10:51:18.139Z
 
created_at.lt
string, optional
Filter by creation date: time must be less than the specified value ("until a certain moment exclusive"). Specified in the ISO 8601 format. Example:
created_at.lt=2018-07-18T10:51:18.139Z
 
captured_at.gte
string, optional
Filter by time of payment capture: time must be greater than the specified value or equal ("from a certain moment inclusive"). Specified in the ISO 8601 format. Example:
captured_at.gte=2018-07-18T10:51:18.139Z
 
captured_at.gt
string, optional
Filter by time of payment capture: time must be greater than the specified value ("from a certain moment exclusive"). Specified in the ISO 8601 format. Example:
captured_at.gt=2018-07-18T10:51:18.139Z
 
captured_at.lte
string, optional
Filter by time of payment capture: time must be less than the specified value or equal ("until a certain moment inclusive"). Specified in the ISO 8601 format. Example:
captured_at.lte=2018-07-18T10:51:18.139Z
 
captured_at.lt
string, optional
Filter by time of payment capture: time must be less than the specified value ("until a certain moment exclusive") Specified in the ISO 8601 format. Example:
captured_at.lt=2018-07-18T10:51:18.139Z
 
payment_method
string, optional
Filter by payment method  code. Example:
payment_method=bank_card
 
status
string, optional
Filter by payment status . Example:
status=succeeded
 
limit
number, optional
Size of the output of request results: number of objects sent in response. Possible values: 1 to 100. Example:
limit=50

Default value:
10
 
cursor
string, optional
Cursor to the next fragment in the list. Example:
cursor=37a5c87d-3984-51e8-a7f3-8de646d39ec15

Use the value of the
next_cursor
parameter received in response to the previous request as the cursor. Used if the size of the list is greater than the output size (
limit
) and the output end hasn't been reached. Example of usage 
cURL
PHP
Python
Request example
curl https://payment.yandex.net/api/v3/payments \
  -u <Shop ID>:<Secret key>
Request body example
{
  "type": "list",
  "items": [
    {
      "id": "22e12f66-000f-5000-8000-18db351245c7",
      "status": "waiting_for_capture",
      "paid": true,
      "amount": {
        "value": "2.00",
        "currency": "RUB"
      },
      "created_at": "2018-07-18T10:51:18.139Z",
      "description": "Order No. 72",
      "expires_at": "2018-07-25T10:52:00.233Z",
      "metadata": {
        
      },
      "payment_method": {
        "type": "bank_card",
        "id": "22e12f66-000f-5000-8000-18db351245c7",
        "saved": false,
        "card": {
          "first6": "555555",
          "last4": "4444",
          "expiry_month": "07",
          "expiry_year": "2022",
          "card_type": "MasterCard",
          "issuer_country": "RU",
          "issuer_name": "Sberbank"
        },
        "title": "Bank card *4444"
      },
      "recipient": {
        "account_id": "100001",
        "gateway_id": "1000001"
      },
      "refundable": false,
      "test": false
    }
  ],
  "next_cursor": "37a5c87d-3984-51e8-a7f3-8de646d39ec15"
}
 
Get payment information
This request allows you to get the information about the current payment status by its unique ID.
The response to the request will contain the payment object with the current status.
cURL
PHP
Python
Request example
curl https://payment.yandex.net/api/v3/payments/{payment_id} \
  -u <Shop ID>:<Secret Key>
Request body example
{
  "id": "22e12f66-000f-5000-8000-18db351245c7",
  "status": "waiting_for_capture",
  "paid": true,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "created_at": "2018-07-18T10:51:18.139Z",
  "description": "Order No. 72",
  "expires_at": "2018-07-25T10:52:00.233Z",
  "metadata": {
    
  },
  "payment_method": {
    "type": "bank_card",
    "id": "22e12f66-000f-5000-8000-18db351245c7",
    "saved": false,
    "card": {
      "first6": "555555",
      "last4": "4444",
      "expiry_month": "07",
      "expiry_year": "2022",
      "card_type": "MasterCard",
      "issuer_country": "RU",
      "issuer_name": "Sberbank"
    },
    "title": "Bank card *4444"
  },
  "recipient": {
    "account_id": "100001",
    "gateway_id": "1000001"
  },
  "refundable": false,
  "test": false
}
 
Capture a payment
Confirm you’re ready to accept the payment. Once the payment is captured, the status will change to
succeeded
. After that, you can provide the customer with the product or service.
You can only capture payments with the
waiting_for_capture
status, and only for a certain amount of time (depending on the payment method). If you do not capture the payment within the allotted time, the status will change to
canceled
, and the money will be returned to the user.
The response to the request will contain the payment object with the current status.
Request parameter descriptions
Request parameters
Description
 
amount
object, optional
Total amount charged to the user. For payments made via bank card or from a Yandex.Money wallet, you can specify a part of the initial amount, so the remainder will be returned to the user.
Nested parameters
 
value
string, required
Amount in the selected currency, in the form of a string with a dot separator, for example,
10.00
. The number of digits after the dot depends on the selected currency.
 
currency
string, required
Currency code in the ISO-4217 format. It should match the currency of your subaccount (
recipient.gateway_id
) if you separate payment flows, or the currency of the account (shopId in the Merchant Profile) if you don't.
 
receipt
object, optional
Data for creating a receipt in the online sales register (for compliance with 54-FZ ). Specify this parameter if you send the data for creating the receipt using one of these scenarios: Payment and receipt at the same time  or Payment after receipt .
Nested parameters
 
customer
object, optional
User details. You should specify at least the basic contact information: email address (
customer.email
) or phone number (
customer.phone
).
Nested parameters
 
full_name
string, optional
Name of the organization for companies, full name for sole proprietors and individuals. If the individual doesn't have a Tax Identification Number (INN), specify their passport information in this parameter. Maximum 256 characters.
Online sales register hat support this parameter: Orange Data, ATOL Online.
 
inn
string, optional
User's Tax Identification Number (INN) (10 or 12 digits).
 
email
string, optional
User's email address.
 
phone
string, optional
User's phone number. Specified in the ITU-T E.164, format, for example,
79000000000
.
 
items
array, required
List of products in an order (maximum 100 items).
Nested parameters
 
description
string, required
Product name (maximum 128 characters).
 
quantity
string, required
Product quantity. Maximum possible value depends on the model of your online sales register.
 
amount
object, required
Product price.
Nested parameters
 
value
string, required
Amount in the selected currency, in the form of a string with a dot separator, for example,
10.00
. The number of digits after the dot depends on the selected currency.
 
currency
string, required
Currency code in the ISO-4217 format. It should match the currency of your subaccount (
recipient.gateway_id
) if you separate payment flows, or the currency of the account (shopId in the Merchant Profile) if you don't.
 
vat_code
number, required
VAT rate. Possible value is a number from 1 to 6. More about VAT rates codes 
 
payment_subject
string, optional
Payment subject attribute. List of possible values 
 
payment_mode
string, optional
Payment method attribute. List of possible values 
 
product_code
string, optional
Product code is a unique number assigned to a unit of product during marking process.
Format: hexadecimal number with spaces. Maximum length is 32 bytes. Example:
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
.
Required parameter for marked products.
 
country_of_origin_code
string, optional
Country of origin code according to the Russian classifier of world countries (OK (MK (ISO 3166) 004-97) 025-2001). Example:
RU
.
Online sales register hat support this parameter: Orange Data, Kit Invest.
 
customs_declaration_number
string, optional
Customs declaration number (1 to 32 characters).
Online sales register hat support this parameter: Orange Data, Kit Invest.
 
excise
string, optional
Amount of excise tax on products including kopeks. Decimal number with 2 digits after the period.
Online sales register hat support this parameter: Orange Data, Kit Invest.
 
tax_system_code
number, optional
Store's tax system. The parameter is only required if you use several tax systems. Otherwise, the parameter is not specified. List of possible values 
 
phone
string, optional
User's phone number. Specified in the ITU-T E.164, format, for example,
79000000000
.
 
email
string, optional
User's email address.
 
airline
object, optional
Object containing the data for selling airline tickets , used only for bank card payments.
Nested parameters
 
ticket_number
string, optional
Unique ticket number. If you already know the ticket number during payment creation,
ticket_number
is a required parameter. If you don't, specify
booking_reference
instead of
ticket_number
.
 
booking_reference
string, optional
Booking reference number, required if
ticket_number
is not specified.
 
passengers
array, optional
List of passengers.
Nested parameters
 
first_name
string, required
Passenger's first name.
 
last_name
string, required
Passenger's last name.
 
legs
array, optional
List of flight legs.
Nested parameters
 
departure_airport
string, required
Code of the departure airport according to IATA, for example, LED.
 
destination_airport
string, required
Code of the arrival airport according to IATA, for example, AMS.
 
departure_date
string, required
Departure date in the YYYY-MM-DD ISO 8601:2004 format.
 
carrier_code
string, optional
Airline code according to IATA.
 
transfers
array, optional
Information about money distribution: the amounts of transfers and the stores to be transferred to. Specified for partially capturing a payment if you use the Yandex.Checkout solution for marketplaces .
Nested parameters
 
account_id
string, required
ID of the store in favor of which you're accepting the receipt. Provided by Yandex.Checkout, displayed in the Sellers section of your Merchant Profile (shopId column).
 
amount
object, required
Amount to be transferred to the store.
Nested parameters
 
value
string, required
Amount in the selected currency, in the form of a string with a dot separator, for example,
10.00
. The number of digits after the dot depends on the selected currency.
 
currency
string, required
Currency code in the ISO-4217 format. It should match the currency of your subaccount (
recipient.gateway_id
) if you separate payment flows, or the currency of the account (shopId in the Merchant Profile) if you don't.
 
platform_fee_amount
object, optional
Commission for sold products or services charged in your favor.
Nested parameters
 
value
string, required
Amount in the selected currency, in the form of a string with a dot separator, for example,
10.00
. The number of digits after the dot depends on the selected currency.
 
currency
string, required
Currency code in the ISO-4217 format. It should match the currency of your subaccount (
recipient.gateway_id
) if you separate payment flows, or the currency of the account (shopId in the Merchant Profile) if you don't.
cURL
PHP
Python
Request example
curl https://payment.yandex.net/api/v3/payments/{payment_id}/capture \
  -X POST \
  -u <Shop ID>:<Secret Key> \
  -H 'Idempotence-Key: <Idempotence Key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {
          "value": "2.00",
          "currency": "RUB"
        }
      }'
Request body example
{
  "id": "22e12f66-000f-5000-8000-18db351245c7",
  "status": "succeeded",
  "paid": true,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "captured_at": "2018-07-18T11:17:33.483Z",
  "created_at": "2018-07-18T10:51:18.139Z",
  "description": "Order No. 72",
  "metadata": {
    
  },
  "payment_method": {
    "type": "bank_card",
    "id": "22e12f66-000f-5000-8000-18db351245c7",
    "saved": false,
    "card": {
      "first6": "555555",
      "last4": "4444",
      "expiry_month": "07",
      "expiry_year": "2022",
      "card_type": "MasterCard",
      "issuer_country": "RU",
      "issuer_name": "Sberbank"
    },
    "title": "Bank card *4444"
  },
  "recipient": {
    "account_id": "100001",
    "gateway_id": "1000001"
  },
  "refundable": true,
  "refunded_amount": {
    "value": "0.00",
    "currency": "RUB"
  },
  "test": false
}
 
Cancel a payment
Cancel payments with the
waiting_for_capture
status. Payment cancelation means you are not ready to dispatch a product or to provide a service to the user. Once you cancel the payment, we will start returning the money to the payer’s account. If the payment was made from a bank card or a Yandex.Money wallet, the money will be refunded instantly. If the payment was made using other payment methods, the process can take up to several days.
The response to the request will contain the payment object with the current status.
cURL
PHP
Python
Request example
curl https://payment.yandex.net/api/v3/payments/{payment_id}/cancel \
  -X POST \
  -u <Shop ID>:<Secret Key> \
  -H 'Idempotence-Key: <Idempotence Key>' \
  -H 'Content-Type: application/json' \
  -d '{ }'
Request body example
{
  "id": "22e12f66-000f-5000-8000-18db351245c7",
  "status": "canceled",
  "paid": false,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "created_at": "2018-07-18T10:51:18.139Z",
  "description": "Order No. 72",
  "metadata": {
    
  },
  "payment_method": {
    "type": "bank_card",
    "id": "22e12f66-000f-5000-8000-18db351245c7",
    "saved": false,
    "card": {
      "first6": "555555",
      "last4": "4444",
      "expiry_month": "07",
      "expiry_year": "2022",
      "card_type": "MasterCard",
      "issuer_country": "RU",
      "issuer_name": "Sberbank"
    },
    "title": "Bank card *4444"
  },
  "recipient": {
    "account_id": "100001",
    "gateway_id": "1000001"
  },
  "refundable": false,
  "test": false
}
 
Refunds
The API allows you to make full or partial refunds. The refund procedure depends on the payment method (
payment_method
) used for the initial payment. If the payment was sent from a bank card, the funds will be returned to the card used for making the payment. How to make refunds 
Some payment methods (for example, cash payments) do not support refunds. Payment methods that support refunds 
cURL
PHP
Python
 
Refund object
The
Refund
object contains all currently relevant information about the refund of a successful payment. The object is sent in response to any refund-related requests.
Parameter descriptions
Parameters
Description
 
id
string, required
Refund's ID in Yandex.Checkout.
 
payment_id
string, required
Payment ID in Yandex.Checkout.
 
status
string, required
Refund status. Possible values:
canceled
,
succeeded
.
 
created_at
string, required
Time to refund creation, based on UTC and specified in the ISO 8601 format, for example,
2017-11-03T11:52:31.827Z
 
amount
object, required
Amount refunded to the user.
Nested parameters
 
value
string, required
Amount in the selected currency, in the form of a string with a dot separator, for example,
10.00
. The number of digits after the dot depends on the selected currency.
 
currency
string, required
Currency code in the ISO-4217 format. It should match the currency of your subaccount (
recipient.gateway_id
) if you separate payment flows, or the currency of the account (shopId in the Merchant Profile) if you don't.
 
description
string, optional
Reason behind the refund.
 
sources
array, optional
Information about money held for refunds: the amount to be held and the stores getting the refunds. Specified if you use the Yandex.Checkout solution for marketplaces .
Nested parameters
 
account_id
string, required
ID of the store in favor of which you're accepting the receipt. Provided by Yandex.Checkout, displayed in the Sellers section of your Merchant Profile (shopId column).
 
amount
object, required
Refund amount.
Nested parameters
 
value
string, required
Amount in the selected currency, in the form of a string with a dot separator, for example,
10.00
. The number of digits after the dot depends on the selected currency.
 
currency
string, required
Currency code in the ISO-4217 format. It should match the currency of your subaccount (
recipient.gateway_id
) if you separate payment flows, or the currency of the account (shopId in the Merchant Profile) if you don't.
 
platform_fee_amount
object, optional
Commission that you charged during payment.
Nested parameters
 
value
string, required
Amount in the selected currency, in the form of a string with a dot separator, for example,
10.00
. The number of digits after the dot depends on the selected currency.
 
currency
string, required
Currency code in the ISO-4217 format. It should match the currency of your subaccount (
recipient.gateway_id
) if you separate payment flows, or the currency of the account (shopId in the Merchant Profile) if you don't.
Example of Refund object
{
  "id": "216749f7-0016-50be-b000-078d43a63ae4",
  "status": "succeeded",
  "amount": {
    "value": "1",
    "currency": "RUB"
  },
  "created_at": "2017-10-04T19:27:51.407Z",
  "payment_id": "216749da-000f-50be-b000-096747fad91e"
}
 
Create a refund
Create a refund for a specified amount on a successfully completed payment. A payment can be refunded within three years of its creation. The commission charged by Yandex.Checkout for carrying out the initial transaction is non-refundable.
The response to the request will contain the refund object with the current status.
Request parameter descriptions
Request parameters
Description
 
payment_id
string, required
Payment ID in Yandex.Checkout.
 
amount
object, required
Amount to be refunded to the user.
Nested parameters
 
value
string, required
Amount in the selected currency, in the form of a string with a dot separator, for example,
10.00
. The number of digits after the dot depends on the selected currency.
 
currency
string, required
Currency code in the ISO-4217 format. It should match the currency of your subaccount (
recipient.gateway_id
) if you separate payment flows, or the currency of the account (shopId in the Merchant Profile) if you don't.
 
description
string, optional
Commentary to the refund, reason behind returning the funds to the user.
 
receipt
object, optional
Data for creating a receipt in the online sales register (for compliance with 54-FZ ). Specify this parameter if you send the data for creating the receipt using one of these scenarios: Payment and receipt at the same time  or Payment after receipt .
Nested parameters
 
customer
object, optional
User details. You should specify at least the basic contact information: email address (
customer.email
) or phone number (
customer.phone
).
Nested parameters
 
full_name
string, optional
Name of the organization for companies, full name for sole proprietors and individuals. If the individual doesn't have a Tax Identification Number (INN), specify their passport information in this parameter. Maximum 256 characters.
Online sales register hat support this parameter: Orange Data, ATOL Online.
 
inn
string, optional
User's Tax Identification Number (INN) (10 or 12 digits).
 
email
string, optional
User's email address.
 
phone
string, optional
User's phone number. Specified in the ITU-T E.164, format, for example,
79000000000
.
 
items
array, required
List of products in an order (maximum 100 items).
Nested parameters
 
description
string, required
Product name (maximum 128 characters).
 
quantity
string, required
Product quantity. Maximum possible value depends on the model of your online sales register.
 
amount
object, required
Product price.
Nested parameters
 
value
string, required
Amount in the selected currency, in the form of a string with a dot separator, for example,
10.00
. The number of digits after the dot depends on the selected currency.
 
currency
string, required
Currency code in the ISO-4217 format. It should match the currency of your subaccount (
recipient.gateway_id
) if you separate payment flows, or the currency of the account (shopId in the Merchant Profile) if you don't.
 
vat_code
number, required
VAT rate. Possible value is a number from 1 to 6. More about VAT rates codes 
 
payment_subject
string, optional
Payment subject attribute. List of possible values 
 
payment_mode
string, optional
Payment method attribute. List of possible values 
 
product_code
string, optional
Product code is a unique number assigned to a unit of product during marking process.
Format: hexadecimal number with spaces. Maximum length is 32 bytes. Example:
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
.
Required parameter for marked products.
 
country_of_origin_code
string, optional
Country of origin code according to the Russian classifier of world countries (OK (MK (ISO 3166) 004-97) 025-2001). Example:
RU
.
Online sales register hat support this parameter: Orange Data, Kit Invest.
 
customs_declaration_number
string, optional
Customs declaration number (1 to 32 characters).
Online sales register hat support this parameter: Orange Data, Kit Invest.
 
excise
string, optional
Amount of excise tax on products including kopeks. Decimal number with 2 digits after the period.
Online sales register hat support this parameter: Orange Data, Kit Invest.
 
tax_system_code
number, optional
Store's tax system. The parameter is only required if you use several tax systems. Otherwise, the parameter is not specified. List of possible values 
 
phone
string, optional
User's phone number. Specified in the ITU-T E.164, format, for example,
79000000000
.
 
email
string, optional
User's email address.
 
sources
array, optional
Information about money held for refunds: the amount to be held and the stores getting the refunds. Specified if you use the Yandex.Checkout solution for marketplaces . Right now, you can specify the information of only one store in this parameter.
Nested parameters
 
account_id
string, required
ID of the store in favor of which you're accepting the receipt. Provided by Yandex.Checkout, displayed in the Sellers section of your Merchant Profile (shopId column).
 
amount
object, required
Refund amount.
Nested parameters
 
value
string, required
Amount in the selected currency, in the form of a string with a dot separator, for example,
10.00
. The number of digits after the dot depends on the selected currency.
 
currency
string, required
Currency code in the ISO-4217 format. It should match the currency of your subaccount (
recipient.gateway_id
) if you separate payment flows, or the currency of the account (shopId in the Merchant Profile) if you don't.
 
platform_fee_amount
object, optional
Commission that you charged during payment.
Nested parameters
 
value
string, required
Amount in the selected currency, in the form of a string with a dot separator, for example,
10.00
. The number of digits after the dot depends on the selected currency.
 
currency
string, required
Currency code in the ISO-4217 format. It should match the currency of your subaccount (
recipient.gateway_id
) if you separate payment flows, or the currency of the account (shopId in the Merchant Profile) if you don't.
cURL
PHP
Python
Request example
curl https://payment.yandex.net/api/v3/refunds \
  -X POST \
  -u <Shop ID>:<Secret Key> \
  -H 'Idempotence-Key: <Idempotence Key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {
          "value": "2.00",
          "currency": "RUB"
        },
        "payment_id": "215d8da0-000f-50be-b000-0003308c89be"
      }'
Request body example
{
  "id": "216749f7-0016-50be-b000-078d43a63ae4",
  "status": "succeeded",
  "amount": {
    "value": "1",
    "currency": "RUB"
  },
  "created_at": "2017-10-04T19:27:51.407Z",
  "payment_id": "216749da-000f-50be-b000-096747fad91e"
}
 
List refunds
The request allows you to receive the list of refunds filtered by specified criteria.
The response will contain the list of refunds with applied parameters of the request. The list includes the information about the refunds created within the last 3 years. The list will be sorted by refund creation time in descending order.
If the number of results exceeds the value of 
limit
, the list will be provided in fragments. In this case, the response to the request will include a fragment of the list and the
next_cursor
parameter with a cursor to the next fragment.
More about working with lists 
Request parameter descriptions
Request parameters
Description
 
created_at.gte
string, optional
Filter by creation date: time must be greater than the specified value or equal ("from a certain moment inclusive"). Specified in the ISO 8601 format. Example:
created_at.gte=2018-07-18T10:51:18.139Z
 
created_at.gt
string, optional
Filter by creation date: time must be greater than the specified value ("from a certain moment exclusive"). Specified in the ISO 8601 format. Example:
created_at.gt=2018-07-18T10:51:18.139Z
 
created_at.lte
string, optional
Filter by creation date: time must be less than the specified value or equal ("until a certain moment inclusive"). Specified in the ISO 8601 format. Example:
created_at.lte=2018-07-18T10:51:18.139Z
 
created_at.lt
string, optional
Filter by creation date: time must be less than the specified value ("until a certain moment exclusive"). Specified in the ISO 8601 format. Example:
created_at.lt=2018-07-18T10:51:18.139Z
 
payment_id
string, optional
Filter by payment ID (get all refunds for the payment). Example:
payment_id=1da5c87d-0984-50e8-a7f3-8de646dd9ec9
 
status
string, optional
Filter by refund status. Possible values:
pending
,
succeeded
,
canceled
. Example:
status=succeeded
 
limit
number, optional
Size of the output of request results: number of objects sent in response. Possible values: 1 to 100. Example:
limit=50

Default value:
10
 
cursor
string, optional
Cursor to the next fragment in the list. Example:
cursor=37a5c87d-3984-51e8-a7f3-8de646d39ec15

Use the value of the
next_cursor
parameter received in response to the previous request as the cursor. Used if the size of the list is greater than the output size (
limit
) and the output end hasn't been reached. Example of usage 
cURL
PHP
Python
Request example
curl https://payment.yandex.net/api/v3/refunds \
  -u <Shop ID>:<Secret key>
Request body example
{
  "type": "list",
  "items": [
    {
      "id": "216749f7-0016-50be-b000-078d43a63ae4",
      "status": "succeeded",
      "amount": {
        "value": "1",
        "currency": "RUB"
      },
      "created_at": "2017-10-04T19:27:51.407Z",
      "payment_id": "216749da-000f-50be-b000-096747fad91e"
    }
  ],
  "next_cursor": "416746f8-0016-50be-b000-078d43a4578"
}
 
Get refund information
This request allows you to get the information about the current refund status by its unique ID.
The response to the request will contain the refund object with the current status.
cURL
PHP
Python
Request example
curl https://payment.yandex.net/api/v3/refunds/{refund_id} \
  -u <Shop ID>:<Secret Key>
Request body example
{
  "id": "216749f7-0016-50be-b000-078d43a63ae4",
  "status": "succeeded",
  "amount": {
    "value": "1",
    "currency": "RUB"
  },
  "created_at": "2017-10-04T19:27:51.407Z",
  "payment_id": "216749da-000f-50be-b000-096747fad91e"
}
 
Receipts
The API allows you to receive information about the receipts that were created with the data sent via Yandex.Checkout.
cURL
PHP
Python
 
Receipt object
The
Receipt
object contains the relevant information about the receipt created for a payment or refund.
Parameter descriptions
Parameters
Description
 
id
string, required
Receipt's ID in Yandex.Checkout.
 
type
string, required
Type of receipt in the online sales register: payment (
payment
) or payment refund (
refund
).
 
payment_id
string, optional
ID of the payment that the receipt was created for.
 
refund_id
string, optional
ID of the refund that the receipt was created for. Not included in the payment receipt.
 
status
string, required
Delivery status of receipt data to online sales register (
pending
,
succeeded
, or
canceled
).
 
fiscal_document_number
string, optional
Fiscal document number.
 
fiscal_storage_number
string, optional
Number of fiscal storage drive in online sales register.
 
fiscal_attribute
string, optional
Fiscal attribute of the receipt. Created by the fiscal storage drive from the data sent for receipt registration.
 
registered_at
string, optional
Date and time of receipt creation in the fiscal storage drive, specified in the ISO 8601 format.
 
fiscal_provider_id
string, optional
Receipt's ID in online sales register. For successful receipt registration.
 
tax_system_code
number, optional
Store's taxation system. List of possible values 
 
items
array, required
List of products in the receipt (maximum 100 items).
Nested parameters
 
description
string, required
Product name (maximum 128 characters).
 
quantity
number, required
Product quantity. Maximum possible value depends on the model of your online sales register. Format: decimal number, with the fractional part of three or more characters (number depends on
quantity
in the request). Fractional part separated by the decimal point. Example:
5.000
 
amount
object, required
Product price.
Nested parameters
 
value
string, required
Amount in the selected currency, in the form of a string with a dot separator, for example,
10.00
. The number of digits after the dot depends on the selected currency.
 
currency
string, required
Currency code in the ISO-4217 format. It should match the currency of your subaccount (
recipient.gateway_id
) if you separate payment flows, or the currency of the account (shopId in the Merchant Profile) if you don't.
 
vat_code
number, required
VAT rate. Possible value is a number from 1 to 6. More about VAT rates codes 
 
payment_subject
string, optional
Payment subject attribute. List of possible values 
 
payment_mode
string, optional
Payment method attribute. List of possible values 
 
supplier
object, optional
Information about the supplier of product or service. You can specify this parameter if you send the data for creating the receipt using the Receipt after payment  scenario.
Nested parameters
 
name
string, optional
Supplier name. The parameter is provided for by the format of fiscal documents (FFD) and is considered mandatory for versions 1.1 and later.
 
phone
string, optional
Supplier's phone number. Specified in the ITU-T E.164 format, for example,
79000000000
. The parameter is provided for by the format of fiscal documents (FFD) and is considered mandatory for versions 1.1 and later.
 
inn
string, optional
Provider's INN/TIN (10 or 12 digits). The parameter is provided for by the format of fiscal documents (FFD) and is considered mandatory for versions 1.05 and later.
 
agent_type
string, optional
Type of agent selling goods or services. The parameter is provided for by the format of fiscal documents (FFD) and is considered mandatory for versions 1.1 and later. List of posible values . You can send it if your online sales register is updated to FFD 1.1 and if you send the data for creating the receipt using the Receipt after payment  scenario
 
settlements
array, optional
List of completed settlements.
Nested parameters
 
type
string, required
Type of settlement. List of possible values 
 
amount
object, required
Settlement amount.
Nested parameters
 
value
string, required
Amount in the selected currency, in the form of a string with a dot separator, for example,
10.00
. The number of digits after the dot depends on the selected currency.
 
currency
string, required
Currency code in the ISO-4217 format. It should match the currency of your subaccount (
recipient.gateway_id
) if you separate payment flows, or the currency of the account (shopId in the Merchant Profile) if you don't.
 
on_behalf_of
string, optional
ID of the store on behalf of which you're sending the receipt. Provided by Yandex.Checkout. The parameter is required if you use the Yandex.Checkout solution for marketplaces .
Example of Receipt object
{
  "id": "rt-1da5c87d-0984-50e8-a7f3-8de646dd9ec9",
  "type": "payment",
  "payment_id": "215d8da0-000f-50be-b000-0003308c89be",
  "status": "succeeded",
  "fiscal_document_number": "3986",
  "fiscal_storage_number": "9288000100115785",
  "fiscal_attribute": "2617603921",
  "registered_at": "2019-05-13T17:56:00.000+03:00",
  "fiscal_provider_id": "fd9e9404-eaca-4000-8ec9-dc228ead2345",
  "tax_system_code": 1,
  "items": [
    {
      "description": "Capybara",
      "quantity": 5.000,
      "amount": {
        "value": "2500.50",
        "currency": "RUB"
      },
      "vat_code": 2,
      "payment_mode": "full_payment",
      "payment_subject": "commodity"
    }
  ]
}
 
Create a receipt
The request allows sending data for generating a transaction creation receipt  to the online sales register.
If you send the data for creating the receipt using the Receipt after payment  scenario, the request should also contain data for creating a payment receipt and a refund receipt.
Existing scenarios for sending a receipt 
Request parameter descriptions
Request parameters
Description
 
type
string, required
Type of receipt in online sales register. Possible value:
payment
(incoming payment),
refund
(payment refund).
 
payment_id
string, optional
Payment ID in Yandex.Checkout for displaying the receipt information in Merchant Profile, doesn’t affect the payment. The parameter is required for creating a payment receipt  (type of receipt:
payment
, payment status:
waiting_for_capture
or 
succeeded
) and for creating a refund receipt  for cancelled or partially captured payments (type of receipt:
refund
, payment status:
canceled
or 
succeeded
).
 
refund_id
string, optional
Refund ID in Yandex.Checkout for displaying the receipt information in Merchant Profile. The parameter is required for creating a refund receipt  (type of receipt: 
refund
, payment status: 
succeeded
).
 
customer
object, required
User details. You should specify at least the basic contact information: email address (
customer.email
) or phone number (
customer.phone
).
Nested parameters
 
full_name
string, optional
Name of the organization for companies, full name for sole proprietors and individuals. If the individual doesn't have a Tax Identification Number (INN), specify their passport information in this parameter. Maximum 256 characters.
Online sales register hat support this parameter: Orange Data, ATOL Online.
 
inn
string, optional
User's Tax Identification Number (INN) (10 or 12 digits).
 
email
string, optional
User's email address.
 
phone
string, optional
User's phone number. Specified in the ITU-T E.164, format, for example,
79000000000
.
 
items
array, required
List of products in the receipt (maximum 100 items).
Nested parameters
 
description
string, required
Product name (maximum 128 characters).
 
quantity
string, required
Product quantity. Maximum possible value depends on the model of your online sales register.
 
amount
object, required
Product price.
Nested parameters
 
value
string, required
Amount in the selected currency, in the form of a string with a dot separator, for example,
10.00
. The number of digits after the dot depends on the selected currency.
 
currency
string, required
Currency code in the ISO-4217 format. It should match the currency of your subaccount (
recipient.gateway_id
) if you separate payment flows, or the currency of the account (shopId in the Merchant Profile) if you don't.
 
vat_code
number, required
VAT rate. Possible value is a number from 1 to 6. More about VAT rates codes 
 
payment_subject
string, optional
Payment subject attribute. List of possible values 
 
payment_mode
string, optional
Payment method attribute. List of possible values 
 
product_code
string, optional
Product code is a unique number assigned to a unit of product during marking process.
Format: hexadecimal number with spaces. Maximum length is 32 bytes. Example:
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
.
Required parameter for marked products.
 
country_of_origin_code
string, optional
Country of origin code according to the Russian classifier of world countries (OK (MK (ISO 3166) 004-97) 025-2001). Example:
RU
.
Online sales register hat support this parameter: Orange Data, Kit Invest.
 
customs_declaration_number
string, optional
Customs declaration number (1 to 32 characters).
Online sales register hat support this parameter: Orange Data, Kit Invest.
 
excise
string, optional
Amount of excise tax on products including kopeks. Decimal number with 2 digits after the period.
Online sales register hat support this parameter: Orange Data, Kit Invest.
 
supplier
object, optional
Information about the supplier of product or service. You can specify this parameter if you send the data for creating the receipt using the Receipt after payment  scenario.
Nested parameters
 
name
string, optional
Supplier name. The parameter is provided for by the format of fiscal documents (FFD) and is considered mandatory for versions 1.1 and later.
 
phone
string, optional
Supplier's phone number. Specified in the ITU-T E.164 format, for example,
79000000000
. The parameter is provided for by the format of fiscal documents (FFD) and is considered mandatory for versions 1.1 and later.
 
inn
string, optional
Provider's INN/TIN (10 or 12 digits). The parameter is provided for by the format of fiscal documents (FFD) and is considered mandatory for versions 1.05 and later.
 
agent_type
string, optional
Type of agent selling goods or services. The parameter is provided for by the format of fiscal documents (FFD) and is considered mandatory for versions 1.1 and later. List of posible values . You can send it if your online sales register is updated to FFD 1.1 and if you send the data for creating the receipt using the Receipt after payment  scenario
 
tax_system_code
number, optional
Store's tax system. The parameter is only required if you use several tax systems. Otherwise, the parameter is not specified. List of possible values 
 
send
boolean, required
Creation of receipt in the online sales register immediately after receipt object creation. You can only set
true
value at this time.
 
settlements
array, required
List of completed settlements.
Nested parameters
 
type
string, required
Type of settlement. List of possible values 
 
amount
object, required
Settlement amount.
Nested parameters
 
value
string, required
Amount in the selected currency, in the form of a string with a dot separator, for example,
10.00
. The number of digits after the dot depends on the selected currency.
 
currency
string, required
Currency code in the ISO-4217 format. It should match the currency of your subaccount (
recipient.gateway_id
) if you separate payment flows, or the currency of the account (shopId in the Merchant Profile) if you don't.
 
on_behalf_of
string, optional
ID of the store on behalf of which you're sending the receipt. Provided by Yandex.Checkout, displayed in the Sellers section of your Merchant Profile (shopId column). Specified if you use the Yandex.Checkout solution for marketplaces .
cURL
PHP
Python
Request example
curl https://payment.yandex.net/api/v3/receipts \
  -X POST \
  -u <Shop ID>:<Secret key> \
  -H 'Idempotence-Key: <Idempotence Key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "customer" : {
          "full_name" : "Ivanov Ivan Ivanovich",
          "email" : "email@email.ru",
          "phone" : "79211234567",
          "inn" : "6321341814"
        },
        "payment_id": "24b94598-000f-5000-9000-1b68e7b15f3f",
        "type": "payment",
        "send": "true",
        "items": [
          {
            "description": "Product name 1",
            "quantity": 1.000,
            "amount": {
              "value": "14000.00",
              "currency": "RUB"
            },
            "vat_code": "2",
            "payment_mode": "full_payment",
            "payment_subject": "commodity",
            "country_of_origin_code": "CN",
          },
          {
            "description": "Product name 2",
            "quantity": 1.000,
            "amount": {
              "value": "1000.00",
              "currency": "RUB"
            },
            "vat_code": "2",
            "payment_mode": "full_payment",
            "payment_subject": "commodity",
            "country_of_origin_code": "CN",
          },
        ],
        "settlements": [
          {
            "type": "prepayment",
            "amount": {
              "value": "8000.00",
              "currency": "RUB"
            },
          },
          {
            "type": "prepayment",
            "amount": {
              "value": "7000.00",
              "currency": "RUB"
            }
          }
        ]
      }'
Request body example
{
  "id": "rt_1da5c87d-0984-50e8-a7f3-8de646dd9ec9",
  "type": "payment",
  "payment_id": "215d8da0-000f-50be-b000-0003308c89be",
  "status": "pending",
  "items": [
    {
      "description": "Product name 1",
      "quantity": 1.000,
      "amount": {
        "value": "14000.00",
        "currency": "RUB"
      },
      "vat_code": "2",
      "payment_mode": "full_payment",
      "payment_subject": "commodity",
      "country_of_origin_code": "CN"
    },
    {
      "description": "Product name 2",
      "quantity": 1.000,
      "amount": {
        "value": "1000.00",
        "currency": "RUB"
      },
      "vat_code": "2",
      "payment_mode": "full_payment",
      "payment_subject": "commodity",
      "country_of_origin_code": "CN"
    }
  ],
  "settlements": [
    {
      "type": "prepayment",
      "amount": {
        "value": "8000.00",
        "currency": "RUB"
      }
    },
    {
      "type": "prepayment",
      "amount": {
        "value": "7000.00",
        "currency": "RUB"
      }
    }
  ],
  "tax_system_code": 1
}
 
List receipts
The request allows you to receive the list of receipts filtered by specified criteria. You can request receipts for a certain payment, a certain refund, or all receipts for a store.
The response will contain the list of receipts with applied parameters of the request. The list includes the information about the receipts created within the last 3 years. The list will be sorted by receipt creation time in descending order.
If the number of results exceeds the value of 
limit
, the list will be provided in fragments. In this case, the response to the request will include a fragment of the list and the
next_cursor
parameter with a cursor to the next fragment.
More about working with lists 
Request parameter descriptions
Request parameters
Description
 
created_at.gte
string, optional
Filter by creation date: time must be greater than the specified value or equal ("from a certain moment inclusive"). Specified in the ISO 8601 format. Example:
created_at.gte=2018-07-18T10:51:18.139Z
 
created_at.gt
string, optional
Filter by creation date: time must be greater than the specified value ("from a certain moment exclusive"). Specified in the ISO 8601 format. Example:
created_at.gt=2018-07-18T10:51:18.139Z
 
created_at.lte
string, optional
Filter by creation date: time must be less than the specified value or equal ("until a certain moment inclusive"). Specified in the ISO 8601 format. Example:
created_at.lte=2018-07-18T10:51:18.139Z
 
created_at.lt
string, optional
Filter by creation date: time must be less than the specified value ("until a certain moment exclusive"). Specified in the ISO 8601 format. Example:
created_at.lt=2018-07-18T10:51:18.139Z
 
status
string, optional
Filter by receipt status. Possible values:
pending
,
succeeded
,
canceled
. Example:
status=succeeded
 
payment_id
string, optional
Filter by payment ID (get all receipts for the specified payment). Example:
payment_id=1da5c87d-0984-50e8-a7f3-8de646dd9ec9
The request can only contain either payment ID or refund ID.
 
refund_id
string, optional
Filter by refund ID (get all receipts for the specified refund). Example:
refund_id=1da5c87d-0984-50e8-a7f3-8de646dd9ec9
The request can only contain either payment ID or refund ID.
 
limit
number, optional
Size of the output of request results: number of objects sent in response. Possible values: 1 to 100. Example:
limit=50

Default value:
10
 
cursor
string, optional
Cursor to the next fragment in the list. Example:
cursor=37a5c87d-3984-51e8-a7f3-8de646d39ec15

Use the value of the
next_cursor
parameter received in response to the previous request as the cursor. Used if the size of the list is greater than the output size (
limit
) and the output end hasn't been reached. Example of usage 
cURL
PHP
Python
Request example
curl https://payment.yandex.net/api/v3/receipts \
  -u <Shop ID>:<Secret Key>
Request body example
{
  "type": "list",
  "items": [
    {
      "id": "rt_1da5c87d-0984-50e8-a7f3-8de646dd9ec9",
      "type": "payment",
      "payment_id": "215d8da0-000f-50be-b000-0003308c89be",
      "status": "succeeded",
      "fiscal_document_number": "3986",
      "fiscal_storage_number": "9288000100115785",
      "fiscal_attribute": "2617603921",
      "registered_at": "2019-05-13T17:56:00.000+03:00",
      "fiscal_provider_id": "fd9e9404-eaca-4000-8ec9-dc228ead2345",
      "items": [
        {
          "description": "Capybara",
          "quantity": 5.000,
          "amount": {
            "value": "2500.50",
            "currency": "RUB"
          },
          "vat_code": 2,
          "payment_mode": "full_payment",
          "payment_subject": "commodity"
        }
      ],
      "tax_system_code": 1
    },
    {
      "id": "rt_2da5c87d-0384-50e8-a7f3-8d5646dd9e10",
      "type": "payment",
      "payment_id": "215d8da0-000f-50be-b000-0003308c89be",
      "status": "pending",
      "items": [
        {
          "description": "Capybara",
          "quantity": 5.000,
          "amount": {
            "value": "1500.30",
            "currency": "RUB"
          },
          "vat_code": 2,
          "payment_mode": "full_payment",
          "payment_subject": "commodity"
        }
      ],
      "tax_system_code": 1
    },
    {
      "id": "rt_37a5c87d-3984-51e8-a7f3-8de646d39ec15",
      "type": "refund",
      "refund_id": "234d8da0-000f-50be-b000-0003308c89be",
      "status": "pending",
      "items": [
        {
          "description": "Capybara",
          "quantity": 5.000,
          "amount": {
            "value": "2500.50",
            "currency": "RUB"
          },
          "vat_code": 2,
          "payment_mode": "full_payment",
          "payment_subject": "commodity"
        }
      ],
      "tax_system_code": 1
    }
  ],
  "next_cursor": "rt_67a4g56e-8487-56d4-a7f3-7yu646s78ec48"
}
 
Get receipt information
This request allows you to get the information about the current receipt status by its unique ID.
The response to the request will contain the receipt object with the current status.
cURL
PHP
Python
Request example
curl https://payment.yandex.net/api/v3/receipts/{receipt_id} \
  -u <Shop ID>:<Secret key>
Request body example
{
  "id": "rt-2da5c87d-0384-50e8-a7f3-8d5646dd9e10",
  "type": "payment",
  "status": "succeeded",
  "payment_id": "225d8da0-000f-50be-b000-0003308c89be",
  "fiscal_document_number": "3997",
  "fiscal_storage_number": "9288000100115786",
  "fiscal_attribute": "2617603922",
  "registered_at": "2019-09-18T10:06:42.985Z",
  "fiscal_provider_id": "fd9e9404-eaca-4000-8ec9-dc228ead2346",
  "items": [
    {
      "quantity": 5,
      "amount": {
        "value": "1500.30",
        "currency": "RUB"
      },
      "vat_code": 2,
      "description": "Capybara",
      "payment_mode": "full_payment",
      "payment_subject": "commodity"
    }
  ],
  "tax_system_code": 1,
  "settlements": [
    {
      "type": "cashless",
      "amount": {
        "value": "45.67",
        "currency": "RUB"
      }
    }
  ]
}
 
Webhooks
Authentication by OAuth token only. Available as part of the partnership program 
Webhook is a mechanism that automatically notifies your system on the events related to created objects. For example, Yandex.Checkout can notify you whenever the status of the payment object created in your app changes to
waiting_for_capture
.
The API allows you to configure webhook (create, delete, view the list of active notifications) for a sent OAuth token.
More about the Yandex.Checkout API notifications
cURL
PHP
Python
 
Webhook object
The
Webhook
object contains information about an event  subscription.
Parameter descriptions
Parameters
Description
 
id
string, required
Webhook ID.
 
event
string, required
Event 
that Yandex.Checkout sends notifications for.
 
url
string, required
URL for sending Yandex.Checkout's notifications.
Example of Webhook object
{
  "id": "e44e8088-bd73-43b1-959a-954f3a7d0c54",
  "event": "payment.succeeded",
  "url": "https://www.merchant-website.com/notification_url"
}
 
Create a webhook
This request allows you to subscribe to notifications about an event  (for example, change of payment status to
succeeded
).
The response to the request will contain the created webhook object.
If you want to receive notifications about several events, you will need to create a different webhook for each of them. Each OAuth token requires its own webhook set.
Request parameter descriptions
Request parameters
Description
 
event
string, required
Event 
that Yandex.Checkout sends notifications for.
 
url
string, required
URL for sending Yandex.Checkout's notifications.
cURL
PHP
Python
Request example
curl https://payment.yandex.net/api/v3/webhooks \
  -X POST \
  -H 'Authorization: Bearer <oauth_token>' \
  -H 'Idempotence-Key: <Idempotence Key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "event": "payment.succeeded",
        "url": "https://www.merchant-website.com/notification_url"
      }'
Request body example
{
  "id": "e44e8088-bd73-43b1-959a-954f3a7d0c54",
  "event": "payment.succeeded",
  "url": "https://www.merchant-website.com/notification_url"
}
 
List created webhooks
This request allows you to check the webhooks available for an OAuth token.
The response to the request will contain an up-to-date list of webhook objects.
cURL
PHP
Python
Request example
curl https://payment.yandex.net/api/v3/webhooks \
  -H 'Authorization: Bearer <oauth_token>'
Request body example
{
  "type": "list",
  "items": [
    {
      "id": "e44e8088-bd73-43b1-959a-954f3a7d0c54",
      "event": "payment.succeeded",
      "url": "https://www.merchant-website.com/notification_url"
    },
    {
      "id": "8d30d343-3441-4af8-9e48-633b8e5e8c21",
      "event": "payment.canceled",
      "url": "https://www.merchant-website.com/notification_url"
    }
  ]
}
 
Delete webhook
This request allows you to unsubscribe from the events about an OAuth token. To delete a webhook, specify its identifier in the request.
The response to the request will contain an empty body.
cURL
PHP
Python
Request example
curl https://payment.yandex.net/api/v3/webhooks/{webhook_id} \
  -X DELETE \
  -H 'Authorization: Bearer <oauth_token>' \
  -H 'Content-Type: application/json'
 
Store
Authentication by OAuth token only. Available as part of the partnership program 
The API allows you to receive the information about the store that the OAuth token was issued for.
cURL
PHP
Python
 
Store object
The store object (
Me
) contains relevant information about the configuration of the store that the OAuth token was issued for. It's sent in response to the store information request.
Parameter descriptions
Parameters
Description
 
account_id
string, required
Store's ID in Yandex.Checkout.
 
test
boolean, required
This is the Demo store .
 
fiscalization_enabled
boolean, required
Sending receipts 
to online sales register enabled in store's settings.
 
payment_methods
array, required
List of payment methods  available to a store.
Example of Me object
{
  "account_id": "123",
  "test": false,
  "fiscalization_enabled": true,
  "payment_methods": [
    "bank_card",
    "yandex_money"
  ]
}
 
Get store information
This request allows you to get the information about the store for an OAuth token.
The response to the request will contain the store object.
cURL
PHP
Python
Request example
curl https://payment.yandex.net/api/v3/me \
  -H 'Authorization: Bearer <oauth_token>'
Request body example
{
  "account_id": "123",
  "test": false,
  "fiscalization_enabled": true,
  "payment_methods": [
    "bank_card",
    "yandex_money"
  ]
}