YooMoney API
Guides
Old versions of the API
Help
Sign up for YooMoney
Faster Payments System
 
Specifics
  • Payment method type in the API: sbp
  • Confirmation scenario: Redirect and QR code
  • Payment term: 1 hour
  • Holding: two-stage payments are unavailable
  • Code in reports: CP
  • Refund: yes, full and partial
  • Refund processing time: on the following day
  • Recurring payments: yes, but there are exceptions
  • Limits: the minimum payment amount is 1 ruble, and the maximum amount is 700,000 rubles (you can raise the limit by contacting the manager)
Integration scenarios
Ready-made solutions:
Manual integration:
Payment process
Payments via FPS require users to confirm the payment in the app of a bank or a payment service that supports this feature. List of banks and payment services supporting payments via FPS (in Russian)
Payments made via FPS can be accepted on a website and in a mobile app:
  1. User selects FPS as the payment method.
  2. User proceeds to checkout: in desktop mode, they scan the QR code with their device and follow the link; in the mobile browser version or mobile app, they tap the button.
  3. If necessary, the user selects their preferred FPS participant (bank or payment service) from the list and gets redirected to the mobile app of the selected FPS participant.
  4. User confirms the payment in the FPS participant's app.
  5. User returns to your website or app where they see the payment status.
Processing payments during which the payment method is saved
Some banks and payment services integrated with the FPS don't support processing autopayments yet.
If you're processing a payment via FPS during which the payment method is saved (specifying the save_payment_method parameter with value true), only those banks and payment services which support autopayments will be displayed on the list of FPS participants. If the user needs a bank or service not present on the list, the payment isn't possible.
Notify the user about it during the payment process and suggest using a different method if necessary.
To find out which banks and payment services support autopayments, go to the FPS website and use the Привязка счета (“link the account”) filter.
Payment via FPS on YooMoney’s ready-made page
How it works
In this scenario, after creating a payment, you redirect the user to the YooMoney’s page where they scan the QR code or selects their bank or payment service.
On desktop
On mobile
Example of a payment form
For integration, add the button to your website that the user will click on to proceed to payment. When the user clicks the button, you will receive the link to the ready-made payment page from YooMoney: redirect the user to it. When the user returns to your website, request the payment results from YooMoney.
Processing a payment
Step 1. Create a payment :
  • in the amount object, specify the amount to be debited from the user; the amount must be within the limits;
  • in the payment_method_data object, set the sbp type;
  • in the confirmation object, set the redirect type and specify the URL of the page on your side that the user will be redirected to after completing the payment (in the return_url parameter);
  • in the capture parameter, set the true value so the payment status will automatically change to succeeded after the payment.
Example of a request body
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": "2.00",
          "currency": "RUB"
        },
        "payment_method_data": {
          "type": "sbp"
        },
        "confirmation": {
          "type": "redirect",
          "return_url": "https://www.example.com/return_url"
        },
        "capture": true,
        "description": "Order No. 72"
      }'
Step 2. Redirect the user to the URL of the YooMoney page specified in confirmation_url. The desktop version of the YooMoney page will display the QR code, and the mobile version will display the list of banks and payment services.
Example of a response body
JSON
{
  "id": "264e0b53-000f-5000-8000-17409ff6554a",
  "status": "pending",
  "paid": false,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "confirmation": {
    "type": "redirect",
    "confirmation_url": "https://yoomoney.ru/checkout/payments/sbp?orderId=272b3eb5-000f-5000-9000-1766dbc50f19"
  },
  "created_at": "2020-05-13T13:35:15.183Z",
  "description": "Order No. 72",
  "metadata": {},
  "payment_method": {
    "type": "sbp",
    "id": "264e0b53-000f-5000-8000-17409ff6554a",
    "saved": false,
    "sbp_operation_id": "1027088AE4CB48CB81287833347A8777"
  },
  "recipient": {
    "account_id": "100500",
    "gateway_id": "100700"
  },
  "refundable": false,
  "test": false
}
Step 3. Wait for the payment to be successfully completed: you will receive a notification from YooMoney, or you can send periodic requests for payment information .
Example of a response body
JSON
{
  "id": "264e0bc0-000f-5000-a000-109b22344b4c",
  "status": "succeeded",
  "paid": true,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "income_amount": {
    "value": "1.97",
    "currency": "RUB"
  },
  "captured_at": "2020-05-13T13:49:16.887Z",
  "created_at": "2020-05-13T13:37:04.389Z",
  "description": "Order No. 72",
  "income_amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "metadata": {},
  "payment_method": {
    "type": "sbp",
    "id": "264e0bc0-000f-5000-a000-109b22344b4c",
    "saved": false,
    "sbp_operation_id": "1027088AE4CB48CB81287833347A8777"
  },
  "recipient": {
    "account_id": "100500",
    "gateway_id": "100700"
  },
  "refundable": true,
  "refunded_amount": {
    "value": "0.00",
    "currency": "RUB"
  },
  "test": false
}
Step 4. After the user returns to return_url, display the results of payment processing (success or failure) depending on the payment status.
Done!
Payment with manual redirection to the FPS participant’s app
How it works
In this scenario, after creating a payment, you manually generate and display the QR code or redirect the user to the FPS participant’s app.
Processing a payment
  • in the amount object, specify the amount to be debited from the user; the amount must be within the limits;
  • in the payment_method_data object, set the sbp type;
  • in the confirmation object, set the the qr type;
  • in the capture parameter, set the true value so the payment status will automatically change to succeeded after the payment.
Example of a request body
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": "2.00",
          "currency": "RUB"
        },
        "payment_method_data": {
          "type": "sbp"
        },
        "confirmation": {
          "type": "qr"
        },
        "capture": true,
        "description": "Order No. 72"
      }'
Step 2. YooMoney will send you a URL in confirmation_data. For the desktop version of the website, generate a QR code using any available tool and display it to the user. For the mobile version or the app, redirect the user to this URL.
Example of a response body
JSON
{
  "id": "264e0b53-000f-5000-8000-17409ff6554a",
  "status": "pending",
  "paid": false,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "confirmation": {
    "type": "qr",
    "confirmation_data": "https://qr.nspk.ru/QR_ID"
  },
  "created_at": "2020-05-13T13:35:15.183Z",
  "description": "Order No. 72",
  "metadata": {},
  "payment_method": {
    "type": "sbp",
    "id": "264e0b53-000f-5000-8000-17409ff6554a",
    "saved": false,
    "sbp_operation_id": "1027088AE4CB48CB81287833347A8777"
  },
  "recipient": {
    "account_id": "100500",
    "gateway_id": "100700"
  },
  "refundable": false,
  "test": false
}
Step 3. Wait for the payment to be successfully completed: you will receive a notification from YooMoney, or you can send periodic requests for payment information .
Example of a response body
JSON
{
  "id": "264e0bc0-000f-5000-a000-109b22344b4c",
  "status": "succeeded",
  "paid": true,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "income_amount": {
    "value": "1.97",
    "currency": "RUB"
  },
  "captured_at": "2020-05-13T13:49:16.887Z",
  "created_at": "2020-05-13T13:37:04.389Z",
  "description": "Order No. 72",
  "income_amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "metadata": {},
  "payment_method": {
    "type": "sbp",
    "id": "264e0bc0-000f-5000-a000-109b22344b4c",
    "saved": false,
    "sbp_operation_id": "1027088AE4CB48CB81287833347A8777"
  },
  "recipient": {
    "account_id": "100500",
    "gateway_id": "100700"
  },
  "refundable": true,
  "refunded_amount": {
    "value": "0.00",
    "currency": "RUB"
  },
  "test": false
}
Step 4. Display the results of payment processing (success or failure) depending on the payment status.
Done!
See also