YooMoney API
Guides
Old versions of the API
Help
Sign up for YooMoney
Format of interaction with the YooMoney API
 
Specifics
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, GET, and DELETE requests. POST requests use JSON arguments, GET and DELETE requests use query strings. The API always returns the response in JSON format, regardless of the type of request.
Аuthentication
Authentication details must be specified in the Authorization parameter of the request header.
YooMoney offers two methods of authenticating requests: HTTP Basic Auth (default option) and OAuth (only for those who use the API for partners).
HTTP Basic Auth
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. Если у вас нет доступа к личному кабинету, попросите владельца магазина добавить вас как пользователя с ролью Разработчик. How to add a user of the YooMoney Merchant Profile
Для тех, кто принимает платежи
Тем, кто принимает платежи, в том числе использует Сплитование платежей или Безопасную сделку, в запросах необходимо передавать идентификатор и секретный ключ магазина:
Для тех, кто делает выплаты
Тем, кто проводит выплаты, в запросах необходимо передавать идентификатор и секретный ключ шлюза:
OAuth
If you’re taking part in the YooMoney’s 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-токен>"
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.
To ensure the idempotency of requests, the Idempotence-Key header (or the idempotency key) is used. Any value that is unique to this transaction on your side can be specified in the Idempotence-Key header. The maximum length is 64 characters. We recommend using V4 UUID.
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 idempotency key must be specified for POST and DELETE requests. GET requests are idempotent by default, as they do not result in undesirable consequences.
Request processing
YooMoney processes a request immediately after it’s received, then returns the processing results (“success” or “failure”). The response contains the HTTP response code, standard headers, and if necessary the body of the response in the JSON format. More about the response format
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 or try to cancel the transaction if the request is payment-based .
HTTP 500 does not indicate that your transaction either failed or was successful. That's why when you receive HTTP 500, you need to learn about the result of request processing first and then make any decisions related to this transaction.
See also