Skip to main content

Payments via T-Pay

Important!

Starting September 1, 2026, T-Bank will disable T-Pay payments via QR code in the desktop browser (as required by Federal Law No. 248-FZ dated July 23, 2025, on the universal payment code).

Until that date, the current QR code scenario remains in effect. Starting September 1, 2026, instead of the payer's QR code, you need to redirect users via a link to the T-Bank web interface for payment.

You can switch to the new scenario right now—there is no need to notify T-Bank or coordinate the transition.

During payments via T-Pay the payer authentication is performed through logging into the T-Bank app. Payers do not have to enter card details to make payments.

You can accept T-Pay payments in two ways:

  • with a QR code, which works for payments made from a desktop browser (generate and display the QR code on your own)
  • with a URL to the T-Bank application, which works for payments made from a mobile device

T-Pay payments are only carried out with funds being held (pre-authorized).

Payment scenario​

The payment scenario depends on the payer's payment channel: mobile device (mobile) or desktop browser (desktop). The payer device properties in the request define the format of the payment link in the action_required webhook.

  1. Create a session separately using the session/create method and then start the payment (session/start/payment), or create a session along with the payment using the session/init/payment method. Pass all the required parameters:

    • Pass the tpay value in the type parameter of the internet_banking object.
    • Pass the mobile value in the type parameter of the platform_details object. Specify one of the acceptable values in the os and browser parameters.
    Request example 
    curl -X POST \
      https://proxy.bank131.ru/api/v1/session/init/payment \
      -H 'Content-Type: application/json' \
      -H 'X-PARTNER-PROJECT: your_project_name' \
      -H 'X-PARTNER-SIGN: signature' \
      -d '{
        "payment_details": {
          "type": "internet_banking",
          "internet_banking": {
            "type": "tpay"
          }
        },
        "amount_details": {
          "amount": 67000,
          "currency": "RUB"
        },
        "customer": {
          "reference": "lucky"
        },
        "payment_options": {
          "platform_details": {
            "type": "mobile",
            "os": "ios",
            "browser": "chrome"
          }
        }
      }'
    Response example 
    {
      "status": "ok",
      "session": {
        "id": "ps_3813062",
        "status": "in_progress",
        "created_at": "2025-09-05T07:14:28.236854Z",
        "updated_at": "2025-09-05T07:14:28.298522Z",
        "acquiring_payments": [{
          "id": "pm_2769418",
          "status": "in_progress",
          "created_at": "2025-09-05T07:14:28.310910Z",
          "customer": {
            "reference": "lucky"
          },
          "payment_details": {
            "type": "internet_banking",
            "internet_banking": {
              "type": "tpay"
            }
          },
          "amount_details": {
            "amount": 67000,
            "currency": "RUB"
          },
          "amounts": {}
        }]
      }
    }

  2. Wait for a ready_to_confirm webhook from Bank 131 when Bank 131 is ready to process the payment and is waiting for your confirmation.

  3. Confirm your payment by sending a session/confirm request, or cancel the payment sending a session/cancel request.

  4. Bank 131 will send you an action_required webhook containing a URL within redirect.url to forward the payer to the T-Bank mobile application.

    Webhook example
    curl -X POST \
      https://partner.ru \
      -H 'content-type: application/json' \
      -H 'X-PARTNER-SIGN: signature' \
      -d '{
        "type": "action_required",
        "session": {
          "id": "ps_3813062",
          "status": "in_progress",
          "created_at": "2025-09-05T07:49:12.513214Z",
          "updated_at": "2025-09-05T07:49:24.628403Z",
          "acquiring_payments": [{
            "id": "pm_2769418",
            "status": "pending",
            "created_at": "2025-09-05T07:49:12.605322Z",
            "customer": {
              "reference": "lucky"
            },
            "payment_details": {
              "type": "internet_banking",
              "internet_banking": {
                "type": "tpay"
              }
            },
            "amount_details": {
              "amount": 67000,
              "currency": "RUB"
            },
            "amounts": {},
            "customer_interaction": {
              "type": "redirect",
              "redirect": {
                "url": "https://o.tbank.ru/tpay/3000000000000021275",
                "base_url": "https://o.tbank.ru/tpay/3000000000000021275",
                "method": "GET",
                "params": {}
              }
            }
          }],
          "actions": {
            "confirm": "2025-09-05T07:49:24.148058Z"
          }
        }
      }'

  5. Forward the payer by the link passed within the redirect.url parameter to the T-Bank mobile application. Wait until the payer approves or cancels the payment.

    After being redirected by the URL, the payer will have 20 minutes to complete the payment. Otherwise, the session terminates within 20 minutes with the canceled status.

  6. Wait for a ready_to_capture webhook and capture the amount that is on hold in full or partially (session/capture), or decline the payment (session/cancel).

  7. Wait for a payment_finished webhook containing the payment result from Bank 131. The succeeded status indicates a successful payment.

Payment via T-Bank's web interface​

Starting September 1, 2026, the payment scenario in the desktop browser is as follows:

  1. Create a session separately using the session/create method and then start the payment (session/start/payment), or create a session along with the payment using the session/init/payment method. Pass all the required parameters:

    • Pass the tpay value in the type parameter of the internet_banking object.
    • Pass the desktop value in the type parameter of the platform_details object. Specify one of the acceptable values in the os and browser parameters.
    Request example 
    curl -X POST \
      https://proxy.bank131.ru/api/v1/session/init/payment \
      -H 'Content-Type: application/json' \
      -H 'X-PARTNER-PROJECT: your_project_name' \
      -H 'X-PARTNER-SIGN: signature' \
      -d '{
        "payment_details": {
          "type": "internet_banking",
          "internet_banking": {
            "type": "tpay"
          }
        },
        "amount_details": {
          "amount": 67000,
          "currency": "RUB"
        },
        "customer": {
          "reference": "lucky"
        },
        "payment_options": {
          "platform_details": {
            "type": "desktop",
            "os": "windows",
            "browser": "chrome"
          }
        }
      }'

  2. Wait for a ready_to_confirm webhook from Bank 131 when Bank 131 is ready to process the payment and is waiting for your confirmation.

  3. Confirm your payment by sending a session/confirm request, or cancel the payment sending a session/cancel request.

  4. Bank 131 will send you an action_required webhook containing a payment link in the redirect.url parameter.

Webhook example
curl -X POST \
  https://partner.ru \
  -H 'content-type: application/json' \
  -H 'X-PARTNER-SIGN: signature' \
  -d '{
    "type": "action_required",
    "session": {
      "id": "ps_3813062",
      "status": "in_progress",
      "created_at": "2025-09-05T07:49:12.513214Z",
      "updated_at": "2025-09-05T07:49:24.628403Z",
      "acquiring_payments": [{
        "id": "pm_2769418",
        "status": "pending",
        "created_at": "2025-09-05T07:49:12.605322Z",
        "customer": {
          "reference": "lucky"
        },
        "payment_details": {
          "type": "internet_banking",
          "internet_banking": {
            "type": "tpay"
          }
        },
        "amount_details": {
          "amount": 67000,
          "currency": "RUB"
        },
        "amounts": {},
        "customer_interaction": {
          "type": "redirect",
          "redirect": {
            "url": "https://www.tinkoff.ru/tpay/3000000000000021275",
            "base_url": "https://www.tinkoff.ru/tpay/3000000000000021275",
            "method": "GET",
            "params": {}
          }
        }
      }],
      "actions": {
        "confirm": "2025-09-05T07:49:24.148058Z"
      }
    }
  }'

  1. Forward the payer by the link from the redirect.url parameter to T-Bank's web interface. Wait until the payer approves or cancels the payment.

    The link cannot be opened in an iframe. Forward the payer directly by the link to T-Bank's web interface.

    After being redirected, the payer will have 20 minutes to complete the payment. Otherwise, the session terminates within 20 minutes with the canceled status.

  2. Wait for a ready_to_capture webhook and capture the amount that is on hold in full or partially (session/capture), or decline the payment (session/cancel).

  3. Wait for a payment_finished webhook containing the payment result from Bank 131. The succeeded status indicates a successful payment.

Sequence diagram​

Show diagrams

Recurring payments​

To perform MIT recurring payments or CIT recurring payments via T-Pay:

  1. Get a token by sending recurrent=true (in the payment_options object) in the request. If the payment is successful, you will get the token in the payment_finished webhook in the recurrent.token parameter.

    Request example 
    curl -X POST \
      https://proxy.bank131.ru/api/v1/session/init/payment \
      -H 'Content-Type: application/json' \
      -H 'X-PARTNER-PROJECT: your_project_name' \
      -H 'X-PARTNER-SIGN: signature' \
      -d '{
        "payment_details": {
          "type": "internet_banking",
          "internet_banking": {
            "type": "tpay"
          }
        },
        "amount_details": {
          "amount": 670000,
          "currency": "RUB"
        },
        "customer": {
          "reference": "lucky"
        },
        "payment_options": {
          "recurrent": true,
          "platform_details": {
            "type": "mobile", 
            "os": "ios", 
            "browser": "chrome" 
          }
        }
      }'
    Response example 
    {
    "status": "ok",
    "session": {
      "id": "ps_3813071",
      "status": "in_progress",
      "created_at": "2025-09-05T07:24:45.996726Z",
      "updated_at": "2025-09-05T07:24:46.081328Z",
      "acquiring_payments": [{
          "id": "pm_2769427",
          "status": "in_progress",
          "created_at": "2025-09-05T07:24:46.108909Z",
          "customer": {
            "reference": "lucky"
          },
          "payment_details": {
            "type": "internet_banking",
            "internet_banking": {
              "type": "tpay"
            }
          },
          "amount_details": {
            "amount": 670000,
            "currency": "RUB"
          },
          "amounts": {},
          "payment_options": {
            "recurrent": true
          }
        }]
      }
    }

  2. Use the token to make recurring payments.

    Examples
    curl -X POST \
      https://proxy.bank131.ru/api/v1/session/init/payment \
      -H 'Content-Type: application/json' \
      -H 'X-PARTNER-PROJECT: your_project_name' \
      -H 'X-PARTNER-SIGN: signature' \
      -d '{
        "payment_details": {
          "type": "recurrent",
          "recurrent": {
            "token": "e9876f32bcd947f79c324cf2da5726304a894f6ae2037de7705fdb3e0a134d39",
            "initiator":"merchant"
          }
        },
        "amount_details": {
          "amount": 670000,
          "currency": "RUB"
        },
        "customer": {
          "reference": "lucky"
        },
        "payment_options": {
          "platform_details": {
            "type": "mobile",
            "os": "android",
            "browser": "chrome"
          }
        }
      }'

How to make a refund​

To make refunds using T-Pay, follow the standard procedure.