Manual integration — Payment acceptance via the YooMoney API

Manual integration

The most flexible method of integration with YooMoney: you manually select the payment methods that will be shown to the user, how to sort them, and how the user will confirm the payment.

Preparation

With manual integration, you control the interaction with the user to the highest degree: YooMoney only takes upon the interaction with the payment systems and services. You will need to manually implement the following steps of the payment process:

payment method selection (if you offer several payment methods);
collection of user's data for payment via the selected method (for some payment methods);
provision of information on how to confirm the payment to the user (for some payment methods);
provision of information on the results of the payment process to the user.

Payment processing

This section describes the general instructions of payment process during manual integration. Links to detailed instructions for integration of each payment method are provided in the Payment methods and integration options section.

Step 1. When the user proceeds to payment, display your payment form to them. Wait until the user selects the payment method in your interface, enters their payment data (for, example, the login in Internet bank), and confirms their readiness to continue the payment process (for example, by clicking the Pay button).

Step 2. Create a payment , include the payment_method_data object with the selected payment method and payment data in the request as well as the confirmation object with the information regarding confirmation scenario, if necessary. You can also specify additional parameters in the request, except for payment_token, payment_method_id.

Example of a request during payment via bank card

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": "bank_card"
        },
        "confirmation": {
          "type": "redirect",
          "return_url": "https://www.example.com/return_url"
        },
        "description": "Order No. 72"
      }'

Step 3. Implement the required confirmation scenario, for example, redirect the user to confirmation_url that will be specified in the returned payment object.

Example of a created payment object

JSON
{
  "id": "22c5d173-000f-5000-9000-1bdf241d4651",
  "status": "pending",
  "paid": false,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "confirmation": {
    "type": "redirect",
    "return_url": "https://www.example.com/return_url",
    "confirmation_url": "https://yoomoney.ru/payments/external/confirmation?orderId=22c5d173-000f-5000-9000-1bdf241d4651"
  },
  "created_at": "2021-04-12T13:59:33.681Z",
  "description": "Order No. 72",
  "metadata": {},
  "payment_method": {
    "type": "bank_card",
    "id": "22c5d173-000f-5000-9000-1bdf241d4651",
    "saved": false
  },
  "recipient": {
    "account_id": "100500",
    "gateway_id": "100700"
  },
  "refundable": false,
  "test": false
}

Step 4. Wait until the successful completion of a payment: wait for the notification from YooMoney or send periodic request for payment information .

Step 5. Provide the user with the payment results.

Step 6. If you process payments in two stages, confirm the debiting of money or cancel the payment. Provide the user with the final result of the payment.

Done!

Payment methods and integration options

Select the options of integrating the payment method most suitable for you depending on the user payment confirmation scenario and whether or not you need to collect the payment data on your side. If it's specified that payment data collection is not required, then in payment_method_data, you will only need to include the payment method code.

Payment method	Integration option	User confirmation scenario	Payment data collection
Autonomous bank card
Bank card `bank_card`	Payment on YooMoney’s ready-made page	Redirect	➖
Bank card `bank_card`	Payment with data entry on your side (PCI DSS)	Redirect	✔️
Payments via contactless payment apps
Mir Pay `bank_card`	No independent integration. Mir Pay will be available for payments made with a bank card on the ready-made YooMoney page combined with other payment methods. Mir Pay can be displayed as a separate button only in the YooMoney widget and with certain settings. Learn more about Mir Pay
E-wallets
YooMoney for Shopping `yoo_money`	Payment with confirmation at the YooMoney website	Redirect	➖
Payments via banking apps
SberPay `sberbank`	Payment with redirection on YooMoney’s ready-made page	Redirect	➖
	Payment with confirmation via push notification or text messages	External	✔️
	Payment with redirection to the bank app (for mobile devices)	Mobile application	➖
	Payment with redirection to the bank app (for desktops)	QR code	➖
Tinkoff Pay `tinkoff_bank`	Payments with confirmation in the Tinkoff app	Redirect	➖
FPS (Faster Payments System) `sbp`	Payment via FPS on YooMoney’s ready-made page	Redirect	➖
FPS (Faster Payments System) `sbp`	Payment with manual redirection to the FPS participant’s app	QR code	➖
Loans and installment plans
Installments `installments`	Payment via the Installments service	Redirect	➖
“Credit purchases“ by SberBank `sber_loan`	Payments on loans or installment plans from SberBank on the ready-made YooMoney page	Redirect	➖
B2B payments
SberBank Business Online `b2b_sberbank`	Payment in SberBank Business Online	Redirect	➖
Other methods
Direct carrier billing `mobile_balance`	Payment via direct carrier billing	External	✔️
Cash `cash`	Payment with a confirmation code	Redirect	✔️ (optional)