Create a payment

POST /v1/payments - payment and checkout link

POST/api/v1/payments

Overview

Creates a payment and returns a link to the payment page. The request itself does not charge anything: the charge happens when the customer opens payUrl and picks a payment method.

Authorization - the X-Api-Key header (see Authentication).

Request parameters

orderId

string, required

Order ID in your system, 1 to 64 characters. Unique within a shop: a repeated orderId returns a 409 error, so payments are never duplicated.

amountKopecks

integer, required

Amount in kopecks, integer. Minimum 100 (1 ruble), maximum 10,000,000,000 (100 million rubles).

description

string, optional

Payment description, up to 255 characters. Shown to the customer on the payment page.

string, optional

Customer email, up to 255 characters - the bank may send a confirmation of the operation to it.

telegramId

integer or string, optional

Customer's Telegram ID (for bots): returned in the payment object and in the webhook, so the bot immediately knows who to deliver the goods to. Accepts a number or a string, up to 20 digits.

metadata

object, optional

Arbitrary data from your system (JSON object, up to 4 KB). Not passed to the provider; returned unchanged in the payment object and in the webhook body. Handy for storing a product id, plan or message id - no mapping table of your own needed.

successUrl

string, optional

Where to return the customer after a successful payment, up to 300 characters. Overrides the shop link; if not set, the shop link is used. Supports https, t.me and tg:// - you can bring a bot customer back to the right dialog step.

failUrl

string, optional

Where to return the customer after a failed payment. Same rules as successUrl.

method

string, optional

SBP or CARD - lock the payment method in advance. If not set, the customer chooses. The method must be enabled for your shop, otherwise 409.

Response

201 with the payment object in the CREATED status. Send the customer to payUrl - the link does not expire until payment is started.

If the response did not arrive (network failure), do not blindly create the payment again: first fetch it by your orderId. Creating again with the same orderId is safe - you get a 409 and no duplicate. Error messages in the body are returned in Russian - match errors by statusCode, not by message text.

The orderId stays taken even after canceling the payment: to retry payment for the same order, create a payment with a new orderId (for example, with an attempt suffix).

curl -X POST https://tabpay.org/api/v1/payments \
  -H "X-Api-Key: tp_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "order-1001",
    "amountKopecks": 19900,
    "description": "Monthly subscription"
  }'

Response 201

{
  "id": "6b9d2c88-4b1a-4f0e-9c37-1f2ab34cd561",
  "orderId": "order-1001",
  "status": "CREATED",
  "amountKopecks": 19900,
  "commissionKopecks": 1393,
  "description": "Monthly subscription",
  "method": null,
  "telegramId": null,
  "metadata": { "productId": 42, "tariff": "month" },
  "successUrl": "https://t.me/your_bot?start=paid_order-1001",
  "failUrl": null,
  "payUrl": "https://tabpay.org/pay/6b9d2c88-4b1a-4f0e-9c37-1f2ab34cd561",
  "isTest": false,
  "paidAt": null,
  "createdAt": "2026-07-11T10:20:30.000Z"
}

Response 409

{
  "statusCode": 409,
  "message": "Платёж с таким orderId уже существует",
  "error": "Conflict"
}