YooMoney API
Guides
Old versions of the API
Help
Sign up for YooMoney
Payment process
In the course of a payment process, the user takes the following actions:
  1. selects the payment method;
  2. enters details for paying with the selected method;
  3. confirms the payment if necessary (for example, completes authentication via 3-D Secure or responds to a text message).
YooMoney provides for several payment scenarios that differ depending on where the user selects the payment method and enters the payment details. In some cases, the user will need to confirm that they want to pay with the selected method. This will require you to implement certain confirmation scenario.
Each payment can be processed in two stages. Usually if the user makes a payment, YooMoney instantly debits the money and transfers it to your account. If you are using two-step payments, you can adjust when to debit the money and complete the payment.
 
Payment creation
Payment  is the primary YooMoney API entity used for payment acceptance.
To create a payment, include the following in the request :
YooMoney can accept payments in two stages, but you can use a simpler payment process (capture parameter with the true value). Immediately after the payment, the process will be completed, and the payment status will change to succeeded.
You can also specify additional information such as the order’s number in your system. YooMoney will return them without changes. This information must be sent in the metadata object as a “key-value” set.
Example of request for payment creation
cURL
PHP
Python
curl https://api.yookassa.ru/v3/payments \
  -X POST \
  -u <Shop ID>:<Secret Key> \
  -H 'Idempotence-Key: <Idempotence Key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {
          "value": "100.00",
          "currency": "RUB"
        },
        "capture": true,
        "confirmation": {
          "type": "redirect",
          "return_url": "https://www.example.com/return_url"
        },
        "description": "Order No. 37",
        "metadata": {
          "order_id": "37"
        }
      }'
The created payment  object will be returned in response.
Example of a created payment object
JSON
{
  "id": "2419a771-000f-5000-9000-1edaf29243f2",
  "status": "pending",
  "paid": false,
  "amount": {
    "value": "100.00",
    "currency": "RUB"
  },
  "confirmation": {
    "type": "redirect",
    "confirmation_url": "https://yoomoney.ru/api-pages/v2/payment-confirm/epl?orderId=2419a771-000f-5000-9000-1edaf29243f2"
  },
  "created_at": "2019-03-12T11:10:41.802Z",
  "description": "Order No. 37",
  "metadata": {
    "order_id": "37"
  },
  "recipient": {
    "account_id": "100500",
    "gateway_id": "100700"
  },
  "refundable": false,
  "test": false
}
User confirmation
For most payment methods, a user’s response confirming they’re ready to make the payment is required. The user will need to take additional action, for example, complete 3-D Secure identification when paying via bank card, confirm the payment at a partner’s payment service, or pay an invoice in Internet banking.
If the user confirmation is required, the status of the created payment  will be pending. It will change to other statuses (succeeded or waiting_for_capture) only after the user confirms they’re ready to make the payment.
If the confirmation is not required, payment status will immediately change to succeeded or waiting_for_capture (if you process payments in two stages).
If the user decides not to make the payment or something goes wrong (for example, not enough funds on the account), the payment will be canceled, and the status will change to canceled.
Confirmation scenarios
YooMoney supports several confirmation scenarios: Redirect, External, QR code, Embeded and Mobile application.
Redirect confirmation scenario: the user takes action on the YooMoney’s page or its partner’s page (for example, enters bank card details or completes identification process via 3-D Secure). You must redirect the user to confirmation_url received in the payment . If the payment is successful (or if something goes wrong), YooMoney will return the user to return_url that you’ll send in the payment creation  request.
External confirmation scenario: to continue, the user takes action in an external system (for example, responds to a text message). All you need to do is let them know how to proceed.
QR confirmation scenario: to confirm the payment, the user scans a QR code. You will need to generate the QR code using any available tools and display it on the payment page.
Embedded confirmation scenario: actions required for payment confirmation will depend on the payment method selected by the user in the YooMoney Checkout Widget. YooMoney will receive the confirmation from the user: all you need to do is embed the widget to your page.
The Mobile application confirmation scenario: to confirm a payment, the user needs to complete an action in a mobile app (for example, in an online banking app). You need to redirect the user to the confirmation_url received in the payment . After the payment is made successfully (or if something goes wrong), YooMoney will redirect the user back to the return_url that you send in your request for creating the payment . This payment confirmation scenario only works on mobile devices (via mobile app or mobile web version).
One payment method can support several confirmation scenarios. The specifics of confirmation scenarios for different methods are provided in the Payment methods section.
Two-stage payments
You can process payments in two stages:
  1. Holding (preauthorization): the user makes the payment, and the funds are put on hold, for example, on their bank card or in e-wallet (depending on the selected payment method).
  2. Capture: funds on hold are debited by your request.
To create a two-stage payment, specify the capture parameter with the false value in the payment creation  request.
Example of request for a two-stage payment creation
cURL
PHP
Python
curl https://api.yookassa.ru/v3/payments \
  -X POST \
  -u <Shop ID>:<Secret Key> \
  -H 'Idempotence-Key: <Idempotence Key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {
          "value": "100.00",
          "currency": "RUB"
        },
        "capture": false,
        "confirmation": {
          "type": "redirect",
          "return_url": "https://www.example.com/return_url"
        },
        "description": "Order No. 37",
        "metadata": {
          "order_id": "37"
        }
      }'
Holding
Once the funds are authorized, the payment status will change to waiting_for_capture. Now you need to make a decision: capture the payment or cancel it. If you don’t respond within a certain period, the payment status will change to canceled, and the funds will be automatically returned to user.
Depending on payment method, you will have 6 hours or 7 days to capture the payment. The exact time allotted for capture is specified in the expires_at parameter. If you don’t do anything with the payment within that period, YooMoney will cancel the payment with the expired_on_capture reason. More about reasons behind payment cancellation
Capture
Use the capture  method to capture the payment. By default, the entire payment amount will be captured. To make a partial capture, specify the required amount in the amount object of the request. If the capture amount is smaller than the payment amount, the difference will be automatically returned to user.
Example of request for a full capture
cURL
PHP
Python
curl https://api.yookassa.ru/v3/payments/{payment_id}/capture \
  -X POST \
  -u <Shop ID>:<Secret Key> \
  -H 'Idempotence-Key: <Idempotence Key>' \
  -H 'Content-Type: application/json'
Example of request for a partial capture
cURL
PHP
Python
curl https://api.yookassa.ru/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"
          }
        }'
Payment cancellation
If you want to decline the payment, you cancel it using the cancel  method. The payment status will be changed to canceled, and the funds will be returned to the user. In this case, YooMoney won’t charge a commission for processing the payment.
You can only cancel payments with the waiting_for_capture status. If the status changed to succeeded, you can create a refund.
Example of request for payment cancellation
cURL
PHP
Python
curl https://api.yookassa.ru/v3/payments/{payment_id}/cancel \
  -X POST \
  -u <Shop ID>:<Secret Key> \
  -H 'Idempotence-Key: <Idempotence Key>' \
  -H 'Content-Type: application/json' \
  -d '{

      }'
Payment lifecycle
Payment’s lifecycle depends on your store’s settings and the attributes you send in the request for payment creation . Each step of a payment’s lifecycle has a corresponding payment  status.
Payment statuses
pending — payment is created, waiting for user’s response. If you use the solution for 54-FZ from YooMoney and the Payment after receipt scenario, the payment can have pending status until the online sales register reports that a receipt has been generated successfully or unsuccessfully. The pending status can change to succeeded, waiting_for_capture (for two-stage payments), or canceled (if something goes wrong).
waiting_for_capture — payment is made, funds are authorized and waiting for capture. This status can change to succeeded (if you capture the funds) or canceled (if you cancel the payment or something goes wrong).
succeeded — payment is successfully completed, the funds will be transferred to your current account (in accordance with your YooMoney contract). This status is final and unchangeable.
canceled — payment is canceled. You will see this status if you initiated payment cancellation, or the payment confirmation period has expired, or the payment was declined by YooMoney or the payment service. This status is final and unchangeable.
Depending on your process, some statuses may be omitted, but their sequence is always unchangeable.
To check the payment status, send periodic requests for payment information , or wait for a notification from YooMoney.
See also