NAV Navbar
Yandex.Checkout API

Using the API

API endpoint

https://payment.yandex.net/api/v3/

Yandex.Checkout is a universal payment solution for accepting online payments. The Yandex.Checkout API is based on RESTful principles, processing real objects in a predictable, easy to understand manner. Using the API, you can send payment requests, save billing information for recurring payments, make refunds, and more.

The API uses HTTP as the main protocol, which means it is suitable for development in any programming language that can work with HTTP libraries (for example, cURL). Authentication is performed via Basic Auth, so you can make your first request directly from the browser.

The API supports POST and GET requests. POST requests use JSON arguments, GET requests work with query strings. The API always returns a response in JSON format, regardless of the type of request.

Authentication

Example of a request with authentication

curl https://payment.yandex.net/api/v3/payments/{payment_id} \
          -u <Shop ID>:<Secret Key>
<?php
  use YandexCheckout\Client;

  $client = new Client();
  $client->setAuth('Shop ID', 'Secret Key');
?>

from yandex_checkout import Configuration

Configuration.account_id = <Shop ID>
Configuration.secret_key = <Secret Key>

HTTP Basic Auth is used for authenticating requests. The request header should include:

The secret key can be issued (as well as re-issued and deleted upon expiration) in the Settings section of your Yandex.Checkout Merchant Profile.

Idempotence

In the context of API, idempotency is the concept of multiple requests having the same effect as single requests.

This means that, upon receiving a second request with identical parameters, Yandex.Checkout will return a response containing the result of the original request (if the request is executed) or the processing status (if the request is still being executed), helping prevent unwanted repeating of transactions. For example, if during the payment process there were network problems, and the connection was interrupted, you can safely repeat the request for an unlimited number of times.

GET requests are idempotent by default, as they do not result in undesirable consequences.

Example of request with idempotency key

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"
      }'
<?php
  $idempotenceKey = uniqid('', true);
  $response = $client->createRefund(
      array(
          'payment_id' => '215d8da0-000f-50be-b000-0003308c89be',
          'amount' => array(
              'value' => '2.00',
              'currency' => 'RUB',
          ),
      ),
      $idempotenceKey
  );
?>
from yandex_checkout import Refund
import uuid

idempotence_key = str(uuid.uuid4())
refund = Refund.create({
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "payment_id": "215d8da0-000f-50be-b000-0003308c89be"
}, idempotence_key)

To ensure the idempotency of POST requests, the Idempotence-Key header (or idempotence key) is used.

How it works:

The Idempotence-Key header can transfer any value unique to this transaction on your side. We recommend using V4 UUID.

Yandex.Checkout provides idempotency for 24 hours after the first request. Any repeated requests after that period will be processed as new.

Errors

Example of the response body of an error

  {
    "type": "error",
    "id": "ab5a11cd-13cc-4e33-af8b-75a74e18dd09",
    "code": "invalid_request",
    "description": "Idempotence key duplicated",
    "parameter": "Idempotence-Key"
  }

In case an error occurs during the processing of a request, the API will return an error object and a standard HTTP code.

HTTP code Description Error code
200 Request is successful.
400 Invalid request. This status is most commonly associated with rule violations regarding the interaction with the API. invalid_request, not_supported
401 Invalid Yandex.Checkout account ID or secret key (username and password used for authentication). invalid_credentials
403 The secret key is valid, but the transaction cannot be carried out due to lack of rights. forbidden
404 Resource is not found. not_found
429 The limit of requests per unit of time has been exceeded. Try to reduce the intensity of requests (you can use the retry_after field for reference: it indicates the time interval recommended before repeating the request, in milliseconds). too_many_requests
500 Something went wrong on Yandex.Checkout's side. internal_server_error

Tools

You can integrate the Yandex.Checkout API faster using these developer tools.

Official libraries:

Community-developed libraries:

Changelog

20 July 2018

authorization_details object added to the Payment object.

17 July 2018

The option to create a payment with the new google_pay payment method is available.

4 June 2018

cancellation_details object (commentary for a canceled payment) added to the Payment object.

17 April 2018

The option to create a payment with the new installments payment method is available.

10 April 2018

first6 parameter (Bank Identification Number for bank card, the first 6 digits) added to the card object.

4 April 2018

airline object (airline addendum data for selling airline tickets) added to the Payment object.

15 January 2017

test attribute added to the Payment object.

30 November 2017

description parameter added to the Payment object.

22 November 2017

30 October 2017

expires_at parameter added to the Payment object.

15 October 2017

Launch of the Yandex.Checkout API.

Payments

The API allows creating, confirming and canceling payments, as well as receiving payment information. How to make payments

Payment object

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"
    },
    "title": "Bank card *4444"
  },
  "test": false
}

The Payment object contains all currently relevant information about the payment. The object is generated during creation of a payment, and sent as a response to any payment-related requests.

Attributes
id
string
required
Payment ID.
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 users with additional fees not included in the total amount.
value
string
required
The amount in the selected currency. Indicated as 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
Description of the transaction that you will find in your Yandex.Checkout Merchant Profile, and the user will see during checkout. For example, "Payment for order No. 72 for user@yandex.ru".
recipient
object
Payment recipient. Required for separating payment flows within one account or making payments to other accounts.
gateway_id
string
required
Subaccount ID. Used for separating payment flows within one account.
payment_method
object
required
Payment method used for this payment.
string
required
Type of object.
Type of object.
Type of object.
Type of object.
Type of object.
Type of object.
Type of object.
Type of object.
Type of object.
Type of object.
Type of object.
id
string
required
Payment method ID.
saved
boolean
required
Saving payment methods allows conducting automatic recurring payments.
title
string
Payment method name.
login
string
required
User's login in Alfa-Click (linked phone number or the additional login).
id
string
required
Payment method ID.
saved
boolean
required
Saving payment methods allows conducting automatic recurring payments.
title
string
Payment method name.
id
string
required
Payment method ID.
saved
boolean
required
Saving payment methods allows conducting automatic recurring payments.
title
string
Payment method name.
card
object
Bank card details.
first6
string
required
First 6 digits of the card's number (BIN).
last4
string
required
Last 4 digits of the card's number.
expiry_year
string
required
Expiration date, year, YYYY.
expiry_month
string
required
Expiration date, month, MM.
card_type
string
required
Type of bank card. Possible values: MasterCard (for Mastercard and Maestro cards), Visa (for Visa and Visa Electron cards), Mir, UnionPay, JCB, AmericanExpress, DinersClub, and Unknown.
id
string
required
Payment method ID.
saved
boolean
required
Saving payment methods allows conducting automatic recurring payments.
title
string
Payment method name.
id
string
required
Payment method ID.
saved
boolean
required
Saving payment methods allows conducting automatic recurring payments.
title
string
Payment method name.
id
string
required
Payment method ID.
saved
boolean
required
Saving payment methods allows conducting automatic recurring payments.
title
string
Payment method name.
id
string
required
Payment method ID.
saved
boolean
required
Saving payment methods allows conducting automatic recurring payments.
title
string
Payment method name.
id
string
required
Payment method ID.
saved
boolean
required
Saving payment methods allows conducting automatic recurring payments.
title
string
Payment method name.
id
string
required
Payment method ID.
saved
boolean
required
Saving payment methods allows conducting automatic recurring payments.
title
string
Payment method name.
phone
string
The phone number specified during the registration process of the Sberbank Online account, required for confirming payments by text message (external confirmation scenario), indicated in the ITU-T E.164 format, for example, 79000000000.
id
string
required
Payment method ID.
saved
boolean
required
Saving payment methods allows conducting automatic recurring payments.
title
string
Payment method name.
id
string
required
Payment method ID.
saved
boolean
required
Saving payment methods allows conducting automatic recurring payments.
title
string
Payment method name.
account_number
string
The number of the Yandex.Money wallet used for making the payment.
captured_at
string
Time of payment confirmation, based on UTC and indicated in the ISO 8601 format.
created_at
string
required
Time of order creation, based on UTC and indicated in the ISO 8601 format. Example: 2017-11-03T11:52:31.827Z
expires_at
string
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 indicated in the ISO 8601 format. Example: 2017-11-03T11:52:31.827Z
confirmation
object
The selected payment confirmation method. For payments requiring confirmation from the user. More about confirmation scenarios
string
required
The scenario in which we wait for the user to independently confirm the payment in a third-party service, for example, by replying to a text message or using a partner's app.
The scenario in which the user is redirected to the Yandex.Checkout's web page to confirm the payment.
enforce
boolean
A request for making a payment with authentication by 3-D Secure. It works if you accept bank card payments without user's confirmation by default. In other cases, the 3-D Secure authentication will be handled by Yandex.Checkout. If you would like to accept payment without additional confirmation by the user, contact your Yandex.Checkout manager.
return_url
string
The URL that the user will return to after confirming or canceling the payment on the web page.
confirmation_url
string
required
The URL that the user will be redirected to for payment confirmation.
test
boolean
required
The attribute of a test transaction.
refunded_amount
object
The amount refunded to the user. Indicated if the payment has successful refunds.
value
string
required
The amount in the selected currency. Indicated as 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.
receipt_registration
string
The status of the data delivery for the online receipt (pending, succeeded or canceled). Indicated if you use the Yandex.Checkout's solution for operating under Federal Law No. 54-FZ.
metadata
object
Any additional data you might need to work with payments (for example, order number), indicated as a "key-value" pair and returned as a response from Yandex.Checkout. Limitations: no more than 16 keys, no more than 32 symbols in the key's title, no more than 512 symbols in the key's value.
cancellation_details
object
Commentary to the canceled status: who and why canceled the payment. More about canceled payments
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
Payment authorization details.
rrn
string
Retrieval Reference Number is a unique identifier of a transaction in the issuer's system. Used for payments via bank card.
auth_code
string
Bank card's authorization code. Provided by the issuer to confirm authorization.

Create a payment

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"
      }'

<?php
  $idempotenceKey = uniqid('', true);
  $response = $client->createPayment(
      array(
          'amount' => array(
              'value' => '2.00',
              'currency' => 'RUB',
          ),
          'payment_method_data' => array(
              'type' => 'bank_card',
          ),
          'confirmation' => array(
              'type' => 'redirect',
              'return_url' => 'https://www.merchant-website.com/return_url',
          ),
          'description' => 'Order No. 72',
      ),
      $idempotenceKey
  );
?>

from yandex_checkout import Payment
import uuid

idempotence_key = str(uuid.uuid4())
payment = Payment.create({
    "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"
}, idempotence_key)

To accept a payment, you need to create a Payment object. 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.

Response 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
  },
  "test": false
}

Arguments
amount
object
required
Payment amount. Sometimes, Yandex.Checkout's partners charge users with additional fees not included in the total amount.
value
string
required
The amount in the selected currency. Indicated as 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
Description of the transaction that you will find in your Yandex.Checkout Merchant Profile, and the user will see during checkout. For example, "Payment for order No. 72 for user@yandex.ru".
receipt
object
Data for creating online receipt (to comply with 54-FZ). Indicate either the user's phone number (phone) or their email address (email).
items
array
required
List of products in an order.
description
string
required
Product name.
quantity
string
required
Product quantity.
amount
object
required
Product price.
value
string
required
The amount in the selected currency. Indicated as 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 rate codes.
tax_system_code
number
Store's tax system. The parameter is only required if you use several tax systems. Otherwise, the parameter is not indicated. More about tax codes.
phone
string
User's phone number for sending the receipt. Indicated in the ITU-T E.164 format, for example, 79000000000.
email
string
User's email address for sending the receipt.
recipient
object
Payment recipient. Required for separating payment flows within one account or making payments to other accounts.
gateway_id
string
required
Subaccount ID. Used for separating payment flows within one account.
payment_token
string
A one-time payment token generated with the client library (YandexCheckout.js, Mobile SDK).
payment_method_id
string
Saved payment method's ID.
payment_method_data
object
Data required for creating a payment method (payment_method) that the user will pay with. More about payment methods
string
required
Type of object.
Type of the object.
Type of object.
Type of object.
Type of object
Type of object.
Type of object.
Type of object.
Type of object.
Type of object.
Type of object.
login
string
required
User's login in Alfa-Click.
payment_data
string
required
Contents of paymentData field of the PKPaymentToken object (Apple Pay payment token). Indicated in Base64 format.
card
object
Bank card details (required if you collect users' bank card details on your side).
number
string
required
Bank card number.
expiry_year
string
required
Expiration date, year, YYYY.
expiry_month
string
required
Expiration date, month, MM.
csc
string
The CVC2 or CVV2 code printed on the back of the card, 3 or 4 digits.
cardholder
string
Cardholder's name.
phone
string
User's phone number that the text message containing the payment password (for adding money in cash) will be sent to, indicated in the ITU-T E.164 format, for example, 79000000000. You may leave the field empty: the user can fill it out during the payment process on the Yandex.Checkout's side.
payment_method_token
string
required
Payment Token Cryptography for making payments via Google Pay. To issue one, you need to call the PaymentData.getPaymentMethodToken().getToken() method in the app installed on the user's device.
google_transaction_id
string
required
Unique transaction ID provided by Google. To issue one, you need to call the PaymentData.getGoogleTransactionId() method in the app installed on the user's device.
phone
string
required
Mobile phone number used for conducting a payment, indicated in the ITU-T E.164 format, for example, 79000000000.
phone
string
required
The phone number specified during the registration process of the QIWI account, indicated in the ITU-T E.164 format, for example, 79000000000.
phone
string
The phone number specified during the registration process of the Sberbank Online account, required for confirming payments by text message (external confirmation scenario), indicated in the ITU-T E.164 format, for example, 79000000000.
confirmation
object
Information required to initiate the selected payment confirmation scenario by the user. More about confirmation scenarios
string
required
The scenario in which we wait for the user to independently confirm the payment in a third-party service, for example, by replying to a text message or using a partner's app.
The scenario in which the user is redirected to the Yandex.Checkout's web page to confirm the payment.
enforce
boolean
A request for making a payment with authentication by 3-D Secure. It works if you accept bank card payments without user's confirmation by default. In other cases, the 3-D Secure authentication will be handled by Yandex.Checkout. If you would like to accept payment without additional confirmation by the user, contact your Yandex.Checkout manager.
return_url
string
required
The URL that the user will return to after confirming or canceling the payment on the web page.
save_payment_method
boolean
Saving payment data (can be used for automatic recurring payments). The true value initiates the creation of a reusable payment_method.
capture
boolean
Automatic acceptance of incoming payments.
client_ip
string
User’s IPv4 or IPv6 address. If not specified, the TCP connection’s IP address is used.
metadata
object
Any additional data you might need to work with payments (for example, order number), indicated as a "key-value" pair and returned as a response from Yandex.Checkout. Limitations: no more than 16 keys, no more than 32 symbols in the key's title, no more than 512 symbols in the key's value.
airline
object
The object containing the data for selling airline tickets, used only for bank card payments.
booking_reference
string
Booking reference number, required for creating a payment.
ticket_number
string
Unique ticket number, required for capturing the payment.
passengers
array
required
List of passengers (must include at least 1, but no more than 4 passengers).
first_name
string
required
Passenger's first name.
last_name
string
required
Passenger's last name.
legs
array
required
List of flight legs (must include at least 1, but no more than 4 legs).
departure_airport
string
required
Code of the departure airport code according to IATA, for example, LED.
destination_airport
string
required
Code of the arrival airport code according to IATA, for example, LED.
departure_date
string
required
Departure date in the YYYY-MM-DD ISO 8601:2004 format.

Payment information

Request example

curl https://payment.yandex.net/api/v3/payments/{payment_id} \
  -u <Shop ID>:<Secret Key>

<?php
  $paymentId = '215d8da0-000f-50be-b000-0003308c89be';
  $payment = $client->getPaymentInfo($paymentId);
?>

from yandex_checkout import Payment

payment_id = '215d8da0-000f-50be-b000-0003308c89be'
payment = Payment.find_one(payment_id)

Send a request 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.

Response 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"
    },
    "title": "Bank card *4444"
  },
  "test": false
}

Capture a payment

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"
        }
      }'

<?php
  $paymentId = '215d8da0-000f-50be-b000-0003308c89be';
  $idempotenceKey = uniqid('', true);
  $response = $client->capturePayment(
      array(
          'amount' => array(
              'value' => '2.00',
              'currency' => 'RUB',
          ),
      ),
      $paymentId,
      $idempotenceKey
  );
?>

from yandex_checkout import Payment
import uuid

payment_id = '215d8da0-000f-50be-b000-0003308c89be'
idempotence_key = str(uuid.uuid4())
response = Payment.capture(
  payment_id,
  {
    "amount": {
      "value": "2.00",
      "currency": "RUB"
    }
  },
  idempotence_key
)

Confirm you’re ready to accept the payment. Only payments with waiting_for_capture status can be captured. Once the payment is captured, it means the transaction has been successfully carried out — now you can dispatch the product or provide the service to the user. Settlements are made on the day after the capture, once the payment is recorded in the Yandex.Checkout system. If you do not confirm the payment until the time specified in expires_at, it will be canceled by default, and the money will be returned to the user. If the payment is made from a bank card, you will have 7 days to capture it. If the payment is made using any other payment methods, you will have 2 hours to capture it. More about confirming and canceling payments.

The response to the request will contain the Payment object with the current status.

Response 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"
    },
    "title": "Bank card *4444"
  },
  "refunded_amount": {
    "value": "0.00",
    "currency": "RUB"
  },
  "test": false
}

Arguments
amount
object
Total amount charged to the user. You can specify a portion of the initial amount, so the remainder will be returned to the user.
value
string
required
The amount in the selected currency. Indicated as 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
Data for creating online receipt (to comply with 54-FZ). Indicate either the user's phone number (phone) or their email address (email).
items
array
required
List of products in an order.
description
string
required
Product name.
quantity
string
required
Product quantity.
amount
object
required
Product price.
value
string
required
The amount in the selected currency. Indicated as 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 rate codes.
tax_system_code
number
Store's tax system. The parameter is only required if you use several tax systems. Otherwise, the parameter is not indicated. More about tax codes.
phone
string
User's phone number for sending the receipt. Indicated in the ITU-T E.164 format, for example, 79000000000.
email
string
User's email address for sending the receipt.
airline
object
The object containing the data for selling airline tickets, used only for bank card payments.
booking_reference
string
Booking reference number, required for creating a payment.
ticket_number
string
Unique ticket number, required for capturing the payment.
passengers
array
required
List of passengers (must include at least 1, but no more than 4 passengers).
first_name
string
required
Passenger's first name.
last_name
string
required
Passenger's last name.
legs
array
required
List of flight legs (must include at least 1, but no more than 4 legs).
departure_airport
string
required
Code of the departure airport code according to IATA, for example, LED.
destination_airport
string
required
Code of the arrival airport code according to IATA, for example, LED.
departure_date
string
required
Departure date in the YYYY-MM-DD ISO 8601:2004 format.

Cancel a payment

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 '{ }'

<?php
  $paymentId = '215d8da0-000f-50be-b000-0003308c89be';
  $idempotenceKey = uniqid('', true);

  $response = $client->cancelPayment(
      $paymentId,
      $idempotenceKey
  );
?>

from yandex_checkout import Payment
import uuid

payment_id = '215d8da0-000f-50be-b000-0003308c89be'
idempotence_key = str(uuid.uuid4())
response = Payment.cancel(
  payment_id,
  idempotence_key
)

Cancels the payment with the waiting_for_capture status. Canceling a payment means you are not ready to dispatch a product or to provide a service to the user. Once you cancel the payment, we will return the money to the payer’s account. If the payment was made from a bank card, the money will be refunded instantly. If the payment was made using other payment methods, the refund can take up to several days. More about confirming and canceling payments.

The response to the request will contain the Payment object with the current status.

Response 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"
    },
    "title": "Bank card *4444"
  },
  "test": false
}

Refunds

The API allows to make partial or full refunds for completed payments. 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 that very same card. How to make refunds

Some payment methods (for example, cash payments) do not allow for refunds. Payment methods that allow for refunds

Refund object

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"
}

The Refund object contains all currently relevant information about the refund of a successful payment. The object is sent as a response to any refund-related requests.

Attributes
id
string
required
Refund's ID in Yandex.Checkout.
payment_id
string
required
Payment ID.
status
string
required
Refund status. Possible values: canceled, succeeded.
created_at
string
required
Time to refund creation, based on UTC and indicated in the ISO 8601 format, for example, 2017-11-03T11:52:31.827Z
amount
object
required
The amount refunded to the user.
value
string
required
The amount in the selected currency. Indicated as 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_registration
string
The status of the data delivery for the online receipt (pending, succeeded or canceled). Indicated if you use the Yandex.Checkout's solution for operating under Federal Law No. 54-FZ.
description
string
The reason behind the refund.

Making a refund

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"
      }'

<?php
  $idempotenceKey = uniqid('', true);
  $response = $client->createRefund(
      array(
          'payment_id' => '215d8da0-000f-50be-b000-0003308c89be',
          'amount' => array(
              'value' => '2.00',
              'currency' => 'RUB',
          ),
      ),
      $idempotenceKey
  );
?>

from yandex_checkout import Refund

payment = Refund.create({
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "payment_id": "215d8da0-000f-50be-b000-0003308c89be"
})

Create a Refund object. Return a successfully completed payment by the payment’s unique ID. Only payments with the succeeded status can be refunded. There is no fee for carrying out the refund. The fee 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.

Response 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"
}

Arguments
payment_id
string
required
Payment ID.
amount
object
The amount to be refunded to the user.
value
string
required
The amount in the selected currency. Indicated as 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
The commentary to the reason behind the refund.
receipt
object
Data for creating online receipt (to comply with 54-FZ). Indicate either the user's phone number (phone) or their email address (email).
items
array
required
List of products in an order.
description
string
required
Product name.
quantity
string
required
Product quantity.
amount
object
required
Product price.
value
string
required
The amount in the selected currency. Indicated as 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 rate codes.
tax_system_code
number
Store's tax system. The parameter is only required if you use several tax systems. Otherwise, the parameter is not indicated. More about tax codes.
phone
string
User's phone number for sending the receipt. Indicated in the ITU-T E.164 format, for example, 79000000000.
email
string
User's email address for sending the receipt.

Refund information

Request example

curl https://payment.yandex.net/api/v3/refunds/{refund_id} \
  -u <Shop ID>:<Secret Key>

<?php
  $refundId = '7894e5e2-a22e-434b-b6c1-e355ff096d1c';
  $refund = $client->getRefundInfo($refundId);
?>

from yandex_checkout import Refund

refund_id = '7894e5e2-a22e-434b-b6c1-e355ff096d1c'
payment = Refund.find_one(refund_id)

Send a request to can 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.

Response 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"
}