Basics of using the API
 
Interaction format
YooMoney for Business is a universal solution for processing online payments. The YooMoney 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 YooMoney 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://api.yookassa.ru/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 YooMoney for Business partnership program, you’ll need to use OAuth 2.0 for request authentication and authorization.
Obtain the OAuth token and send it with every request.
Example of a request with an OAuth token
cURL
PHP
Python
curl https://api.yookassa.ru/v3/payments/{payment_id} \
  -H "Authorization: Bearer <OAuth token>"
The YooMoney 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, YooMoney 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://api.yookassa.ru/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.
YooMoney provides idempotence for 24 hours after the first request. Any repeated requests after that period will be processed as new.
 
Request processing
YooMoney processes a request immediately after it’s received, then returns the processing results (“success” or “failure”).
If an exact answer can’t be returned within 30 seconds, for example as a result of the problems on acquiring bank’s side, YooMoney will return the HTTP code 500 and try to cancel the transaction.
To learn the final results of the request processing, repeat the request with the same data and idempotence key. We recommend repeating the request with the interval of one minute until YooMoney responds with the results differing from HTTP code 500.
 
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 YooMoney 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 theirs Merchant Profile. 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 YooMoney’s side. Processing results unavailable. Repeat the request later using the same idempotence key. We recommend repeating the request with the interval of one minute until YooMoney responds with the results of processing.
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