Basics of using the API
 
Interaction format
Yandex.Checkout is a universal solution for processing online payments. The Yandex.Checkout API is based on RESTful principles, processing real objects with predictable behavior. 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, making it suitable for development in any programming language that can work with HTTP libraries (cURL and others).
The API supports POST and GET requests. POST requests use JSON arguments, GET requests use query strings. The API always returns the response in JSON format, regardless of the type of request.
 
Аuthentication
HTTP Basic Auth is used for authenticating requests. The request header should include your store’s Yandex.Checkout ID as the username and your secret key as the password (you’ll need to generate and activate it with a text message password).
Example of a request with authentication
cURL
PHP
Python
curl https://payment.yandex.net/api/v3/payments/{payment_id} \
  -u <Shop ID>:<Secret Key>
The secret key can be issued (as well as re-issued and deleted upon expiration) in the Integration — API keys section of your Merchant Profile.
The secret key is responsible for the security of your data. Keep it in a safe place, and do not publish it at third-party resources (for example, as part of a code sample).
 
For partners
If you’re taking part in the Yandex.Checkout partnership program, you’ll need to use OAuth 2.0 for request authentication and authorization.
Obtain the OAuth token in the Yandex.OAuth service and send it with every request.
Example of a request with an OAuth token
cURL
PHP
Python
curl https://payment.yandex.net/api/v3/payments/{payment_id} \
  -H "Authorization: Bearer <OAuth token>"
The Yandex.Checkout OAuth token allows making financial transactions on behalf of the user. The token must only be accessible to your app, so don’t publish it in open sources and don’t save it in the browser’s cookies.
 
Idempotence
In the context of API, idempotence is the concept of multiple requests having the same effect as a single request.
Upon receiving a new request with identical parameters, Yandex.Checkout will respond with results of the original request.
Such behavior helps prevent unwanted repetition of transactions: for example, if during the payment process the Internet connection was interrupted due to network problems, you’ll be able to safely repeat the request for an unlimited number of times.
GET requests are idempotent by default, as they do not result in undesirable consequences.
To ensure the idempotency of POST requests, the 
Idempotence-Key
header (or idempotence key) is used.
Example of request with idempotence key
cURL
PHP
Python
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"
      }'
If you repeat the request with the same data and the same key, the API processes it as a duplicate. If the data in the request is the same, but the idempotence key is different, the request is processed as a new one.
The 
Idempotence-Key
header can transfer any value unique to this transaction on your side. We recommend using V4 UUID.
Yandex.Checkout provides idempotence for 24 hours after the first request. Any repeated requests after that period will be processed as new.
 
HTTP response codes
If a request is processed successfully, the API will return the 200 HTTP code and the response body.
If an error occurs during the processing of a request, the API will return an error object and a standard HTTP code.
HTTP codeError codeDescription
400invalid_request, not_supportedInvalid request. This status is most commonly associated with rule violations regarding the interaction with the API.
401invalid_credentials[Basic Auth] Invalid Yandex.Checkout shop ID or secret key (username and password used for authentication).
[OAuth 2.0] Invalid OAuth token: it has expired, or the user has revoked it via Yandex.Passport. Request the token again.
403forbiddenThe secret key or OAuth token is valid, but the transaction cannot be carried out due to lack of rights.
404not_foundResource is not found.
429too_many_requestsThe limit of requests per unit of time has been exceeded. Try reducing the intensity of requests.
500internal_server_errorTechnical difficulties on the Yandex.Checkout’s side. Processing results unavailable. Repeat the request later using the same idempotence key.
Example of the response body of an error
JSON
{
  "type": "error",
  "id": "ab5a11cd-13cc-4e33-af8b-75a74e18dd09",
  "code": "invalid_request",
  "description": "Idempotence key duplicated",
  "parameter": "Idempotence-Key"
}
 
See also
Declined paymentsTestingNotificationsQuick start