Payment process — Payment acceptance via the YooMoney API

Payment process

In the course of a payment process, the user takes the following actions:

selects the payment method;
enters details for paying with the selected method;
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 :

authentication information;
Idempotence key (any random value);
payment amount;
information for payment (depends on the selected payment scenario).

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.

User can confirm a payment only within a certain period. If they fail to do that, YooMoney will cancel the payment with the reason of expired_on_confirmation. More about reasons behind payment cancellation

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

If you'd like to use this feature, make sure the payment methods you need support holding. Learn more about payment methods and their features

You can process payments in two stages:

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

Once the payment status changes to waiting_for_capture, you can capture the payment by debiting the amount fully or partially.

Full debit

Available for all payment methods that support holding. More about payment methods and their features

To debit the full amount, send a request for payment capture to YooMoney.

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'

Partial debit

Available for all payment methods: bank cards, YooMoney wallet, SberPay, Mir Pay, T-Pay, Credit purchases by SberBank.

If you work with autopayments, you can debit part of the amount with all payment methods when saving the payment method, and you can do the same with all payment methods except for YooMoney wallet when processing recurring payments.

To debit a part of the amount, send a request for payment capture to YooMoney and specify the amount object with the required amount. If the debit amount is smaller than the payment amount, the rest will be automatically returned to the user.

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, send a request for payment cancellation to YooMoney. 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.