Format of interaction with the YooMoney API

Specifics

YooMoney for Business is a universal solution for processing online payments and payouts. 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, make payouts, 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).

API endpoint: https://api.yookassa.ru/v3/

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 must include your store or gateway’s YooMoney ID as the username and your secret key as the password.

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).

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 YooMoney Merchant Profile. If you don't have access to Merchant Profile, ask the store's owner to add you as a user with the Developer role. How to add a user of the YooMoney Merchant Profile

For those who accept payments

Those who accept payments and use such features as Split payments and Safe deal must specify store's ID and secret key in the request:

The ID is specified in the Settings — Store section (the shopId field).
You need to generate the secret key and activate it with the text message password in the Integration — API keys section. After that, you will need to download the key and store it in a safe place. Learn more about how to issue, reissue, or delete a secret key

For those who make payouts

Those who make payouts must specify gateway's ID and secret key in the requests:

The ID is specified in the Payouts settings section (the agentId field).
You need to generate the secret key and activate it with the text message password in the Integration — API keys section. After that, you will need to download the key and store it in a safe place. Learn more about how to issue, reissue, or delete a secret key

OAuth

Only for those who use the API for partners.

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-токен>"

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.

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

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”). 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.