T-Pay — Payment acceptance via the YooMoney API

T-Pay

Specifics

Payment method type in the API: tinkoff_bank
Confirmation scenario: Redirect
Payment term: 1 hour
Holding: 7 days, full and partial payment capture is available
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 (you can raise the limit by contacting the manager)

Integration scenarios

Ready-made solutions:

Manual integration: Payments with confirmation in the T-Bank app

Payments with confirmation in the T-Bank 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 T-Bank 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 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.

How to process a payment

Step 1. When a user selects T-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.

You can specify any other parameter in the request except for payment_method_id, payment_token, airline.

Example of a request

cURL
PHP
Python
  curl https://api.yookassa.ru/v3/payments \
    -X POST \
    -u <Store 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://yoomoney.ru/checkout/payments/v2/contract/tinkoff-pay?orderId=23ce833e-000f-5000-8000-172b6722debf"
  },
  "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,
    "card": {
         "first6": "555555",
         "last4": "4444",
         "expiry_year": "2022",
         "expiry_month": "07",
         "card_type": "MasterCard"
     }
  },
  "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": {},
  "authorization_details": {
     "rrn": "10000000000",
     "auth_code": "000000",
     "three_d_secure": {
       "applied": false
     }
  }
}

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.