YooMoney API
Guides
Old versions of the API
Help
Sign up for YooMoney
Tinkoff Pay
 
Specifics
  • Payment method type in the API: tinkoff_bank
  • Confirmation scenario: Redirect
  • Payment term: 1 hour
  • Holding: 7 days
  • Code in reports: TB
  • Refund: yes, full and partial
  • Recurring payments: yes
  • Limits: the minimum payment amount is 1 ruble, and the maximum amount is 700,000 rubles
Integration scenarios
Ready-made solutions:
Payments with confirmation in the Tinkoff app
How it works
In this scenario, you implement the payment method selection process on your own. After creating the payment, you redirect the user to the YooMoney page. This page will display a QR code or button for redirecting the user to the Tinkoff app.
On desktop
On mobile
Example of a payment form
To complete the integration, add a button to your website to redirect the user to checkout. When the user clicks on this button, you need to receive a link to the ready-made payment page from YooMoney and redirect the user to it. When the user returns to your website, request the payment results from YooMoney.
How to process a payment
Step 1. When a user selects Tinkoff Pay, create a payment  by sending a request to YooMoney containing the request authentication data, idempotency key, and payment data:
  • in the amount object, specify the amount to be debited from the user; the amount must be within limits;
  • in the payment_method_data object, specify the tinkoff_bank payment method code;
  • in the confirmation object, specify the redirect type and the URL of the page on your side that the user will return to after the payment (in the return_url parameter);
  • in the description parameter, specify the description of the payment that the user will see when paying.
Example of a request
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": "tinkoff_bank"
          },
          "confirmation": {
            "type": "redirect",
            "return_url": "https://www.example.com/return_url"
          },
          "description": "Order No. 72"
        }'
The payment object  in its current status will be returned in response to the request.
Step 2. Redirect the user to the YooMoney page, the URL of which will be provided in confirmation_url. This is a link to the ready-made YooMoney page.
Example of a created payment object
JSON
{
  "id": "23ce833e-000f-5000-8000-172b6722debf",
  "status": "pending",
  "paid": false,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "confirmation": {
    "type": "redirect",
    "confirmation_url": "https://www.tinkoff.ru/payments/invoice/merch/?invoiceGuId=6347da6e-bed7-442b-b4a6-cfc73188469b"
  },
  "created_at": "2019-01-14T11:16:14.441Z",
  "description": "Order No. 72",
  "metadata": {},
  "payment_method": {
    "type": "tinkoff_bank",
    "id": "23ce833e-000f-5000-8000-172b6722debf",
    "saved": false
  },
  "recipient": {
    "account_id": "100500",
    "gateway_id": "100700"
  },
  "refundable": false,
  "test": false
}
Step 3. Wait until the payment is successfully completed: you'll receive a notification from YooMoney. Alternatively, you can send periodic requests for payment information .
Example of a payment with the succeeded status
JSON
{
  "id": "23ce833e-000f-5000-8000-172b6722debf",
  "status": "succeeded",
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "income_amount": {
    "value": "1.93",
    "currency": "RUB"
  },
  "description": "Order No. 72",
  "recipient": {
    "account_id": "100500",
    "gateway_id": "100700"
  },
  "payment_method": {
    "type": "tinkoff_bank",
    "id": "23ce833e-000f-5000-8000-172b6722debf",
    "saved": false
  },
  "captured_at": "2023-09-08T09:30:11.721Z",
  "created_at": "2023-09-08T09:29:48.933Z",
  "test": false,
  "refunded_amount": {
    "value": "0.00",
    "currency": "RUB"
  },
  "paid": true,
  "refundable": true,
  "metadata": {}
}
Step 4. When the user returns to return_url, display the payment result (succeeded or canceled) depending on the payment status.
Done! If you're processing a two-stage payment, capture or cancel the payment. Inform the user of the final payment result.
See also