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://payment.yandex.net/api/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.merchant-website.com/return_url"
        },
        "description": "Order No. 1",
        "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://money.yandex.ru/api-pages/v2/payment-confirm/epl?orderId=2419a771-000f-5000-9000-1edaf29243f2"
  },
  "created_at": "2019-03-12T11:10:41.802Z",
  "description": "Order No. 1",
  "metadata": {
    "order_id": "37"
  },
  "recipient": {
    "account_id": "100001",
    "gateway_id": "1000001"
  },
  "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 (for example, for payments via Apple Pay), 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, and Embeded.
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 widget. YooMoney will receive the confirmation from the user: all you need to do is embed the widget to your page.
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://payment.yandex.net/api/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.merchant-website.com/return_url"
        },
        "description": "Order No. 1",
        "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.
 
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.
Partial capture is available only for payments made via bank cards or YooMoney wallets. Other methods allow only for capturing the entire amount.
Example of request for a full capture
cURL
PHP
Python
curl https://payment.yandex.net/api/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://payment.yandex.net/api/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://payment.yandex.net/api/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. This 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
Payment by 54-FZDeclined paymentsNotificationsTesting