Skip to main content

Payments via T-Pay

This scenario describes how to receive payments via T-Pay. The payer authentication is performed through logging into the T-Bank app. Customers 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
  • with a URL to the T-Bank application, which works for payments made from a mobile device

To accept payments with a QR code, generate and display the QR code on your side.

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

You can make payments with automatic payment session confirmation.

Payment scenario​

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

  1. Create a separate session using the session/create method, or create a session with the payment using the session/init/payment method and 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": 670000,
            "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 customer to the T-Bank mobile application.

    You decide whether to receive webhooks. If they are disabled, you will need to manually send a session/status request each time to determine the next step and the operation result.

    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_3813080",
          "status": "in_progress",
          "created_at": "2025-09-05T07:49:12.513214Z",
          "updated_at": "2025-09-05T07:49:24.628403Z",
          "acquiring_payments": [{
            "id": "pm_2769436",
            "status": "pending",
            "created_at": "2025-09-05T07:49:12.605322Z",
            "customer": {
              "reference": "vtor_rec"
            },
            "payment_details": {
              "type": "internet_banking",
              "internet_banking": {
                "type": "tpay"
              }
            },
            "amount_details": {
              "amount": 1000700,
              "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 customer by the link passed within the redirect.url parameter to the T-Bank mobile application. Wait until the customer approves or cancels the payment.

  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).

    Skip this step if you do not have delayed capture payments enabled. In this case, the hold and capture will be made automatically.

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

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": {
          "platform_details": {
            "recurrent": true,
            "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": 33123,
            "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": 900000,
          "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.





Ask AI