Faster Payments System (FPS) — Payment acceptance via the YooMoney API

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 via FPS on YooMoney’s ready-made page
Payment with manual redirection to the FPS participant’s app

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:

User selects FPS as the payment method.
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.
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.
User confirms the payment in the FPS participant's app.
User returns to your website or app where they see the payment status.

Processing payments during which the payment method is saved

For those who use recurring payments (autopayments)

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.

Each bank and payment service independently sets the timeline of implementing autopayments, and it's not public information.

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

In order to complete integration, add a button that will redirect users to payment to your website. 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 back to your website, request payment results from YooMoney and display them.

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.

You can set any other parameters in the request, except for payment_method_id, payment_token, airline.

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",
    "payer_bank_details": {
      "bic": "044525444",
      "bank_id": "100000000022"
    }
  },
  "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

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;
set the qr type in the confirmation object and, if necessary, the return_url parameter with the address of the page that will be open to the user when they've completed the payment;
in the capture parameter, set the true value so the payment status will automatically change to succeeded after the payment.

You can set any other parameters in the request, except for payment_method_id, payment_token, airline.

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",
          "return_url": "https://www.example.com/return_url"
        },
        "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",
    "payer_bank_details": {
      "bic": "044525444",
      "bank_id": "100000000022"
    }
  },
  "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!