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.
Description of parameters
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.
 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, required
Payment method 
used for this payment.
Nested parameters
Payment methods
Alfa-Click
 type
string, required
Value is
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 is
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.
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
}
 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.
Description of request parameters
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 ).
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). If the individual doesn't have an INN, specify their passport information in the
full_name
parameter.
Online sales register hat support this parameter: Orange Data, ATOL Online.
 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 is
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 is
embedded
.
Confirmation scenario code.
 locale
string, optional
Language of the interface, emails, and text messages that will be displayed and sent to the user. Formatted in accordance with ISO/IEC 15897. Possible values:
ru_RU
,
en_US
.
 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.
cURL
PHP
Python
Example of request
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"
      }'
Example of response body
{
  "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
}
 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
Example of request
curl https://payment.yandex.net/api/v3/payments/{payment_id} \
  -u <Shop ID>:<Secret Key>
Example of response body
{
  "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.
Description of request parameters
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 ).
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). If the individual doesn't have an INN, specify their passport information in the
full_name
parameter.
Online sales register hat support this parameter: Orange Data, ATOL Online.
 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.
cURL
PHP
Python
Example of request
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"
        }
      }'
Example of response body
{
  "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
Example of request
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 '{ }'
Example of response body
{
  "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.
Description of parameters
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.
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 object,
Refund
. Return a successfully completed payment by the payment’s unique ID and amount. Only payments with the
succeeded
status can be refunded. There is no commission for carrying out the refund. 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.
Description of request parameters
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 ).
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). If the individual doesn't have an INN, specify their passport information in the
full_name
parameter.
Online sales register hat support this parameter: Orange Data, ATOL Online.
 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.
cURL
PHP
Python
Example of request
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"
      }'
Example of response body
{
  "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"
}
 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
Example of request
curl https://payment.yandex.net/api/v3/refunds/{refund_id} \
  -u <Shop ID>:<Secret Key>
Example of response body
{
  "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.
Description of parameters
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. Not included in the refund receipt.
 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
string, required
Product quantity. Maximum possible value depends on the model of your online sales regsiter.
 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 
 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.
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": "Сapybara",
      "quantity": 5,
      "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.
Description of request parameters
Request parameters
Description
 type
string, required
Type of receipt in online sales register. Possible value:
payment
(incoming payment).
 payment_id
string, optional
Payment ID in Yandex.Checkout for displaying the receipt information in Merchant Profile, doesn't affect the payment. Required only you set the
payment
value in the
type
parameter (payment receipt).
 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). If the individual doesn't have an INN, specify their passport information in the
full_name
parameter.
Online sales register hat support this parameter: Orange Data, ATOL Online.
 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.
 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.
cURL
PHP
Python
Example of request
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.00",
            "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.00",
            "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"
            },
          }
        ]
      }'
Example of response body
{
  "id": "rt_1da5c87d-0984-50e8-a7f3-8de646dd9ec9",
  "type": "payment",
  "payment_id": "215d8da0-000f-50be-b000-0003308c89be",
  "status": "pending",
  "items": [
    {
      "description": "Huawei phone",
      "quantity": "1.00",
      "amount": {
        "value": "14000.00",
        "currency": "RUB"
      },
      "vat_code": "2",
      "payment_mode": "full_payment",
      "payment_subject": "commodity",
      "country_of_origin_code": "CN"
    },
    {
      "description": "Huawei phone charger",
      "quantity": "1.00",
      "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
This request allows you to check the receipts created for a payment or refund as well as their status.
The request must contain either the Payment ID or Refund ID.
The response to the request will contain the list of receipts.
Description of request parameters
Request parameters
Description
 payment_id
string, optional
ID of the payment that the receipts are requested for.
Required parameter if
refund_id
is not specified.
 refund_id
string, optional
ID of the refund that the receipts are requested for.
Required parameter if
payment_id
is not specified.
cURL
PHP
Python
Example of request
curl https://payment.yandex.net/api/v3/receipts?payment_id=<payment_id> \
  -u <Shop ID>:<Secret Key>
Example of response body
{
  "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": "Сapybara",
          "quantity": 5,
          "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": "225d8da0-000f-50be-b000-0003308c89be",
      "status": "pending",
      "items": [
        {
          "description": "Сapybara",
          "quantity": 5,
          "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": "Сapybara",
          "quantity": 5,
          "amount": {
            "value": "2500.50",
            "currency": "RUB"
          },
          "vat_code": 2,
          "payment_mode": "full_payment",
          "payment_subject": "commodity"
        }
      ],
      "tax_system_code": 1
    }
  ]
}
 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
Example of request
curl https://payment.yandex.net/api/v3/receipts/{receipt_id} \
  -u <Shop ID>:<Secret key>
Example of response body
{
  "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": "Сapybara",
      "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.
Description of parameters
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.
Description of request parameters
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
Example of request
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"
      }'
Example of response body
{
  "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
Example of request
curl https://payment.yandex.net/api/v3/webhooks \
  -H 'Authorization: Bearer <oauth_token>'
Example of response body
{
  "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
Example of request
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.
Description of parameters
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.
Example of Me object
{
  "account_id": "123",
  "test": false,
  "fiscalization_enabled": true
}
 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
Example of request
curl https://payment.yandex.net/api/v3/me \
  -H 'Authorization: Bearer <oauth_token>'
Example of response body
{
  "account_id": "123",
  "test": false,
  "fiscalization_enabled": true
}