Quick start

You will need an API key for an active shop - see the Authentication section for how to get one.

Step 1. Create a payment

A single POST request from your server. The full field reference is in the Create a payment section.

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"
  }'

The response is a payment object with a payment link:

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

Step 2. Send the customer to payUrl

Redirect the customer to the address from the payUrl field (or send the link as a message - a common flow for bots). On the payment page the customer picks SBP or card and pays. The link does not expire until the customer starts the payment; once started, they have 20 minutes to pay.

Step 3. Get the result

When the payment completes, TabPay sends a POST request to your shop's Webhook URL:

{
  "id": "6b9d2c88-4b1a-4f0e-9c37-1f2ab34cd561",
  "orderId": "order-1001",
  "status": "SUCCESS",
  "amountKopecks": 19900,
  "telegramId": null,
  "metadata": null,
  "test": false
}

Verify the signature from the X-Signature header (see the Signature verification section), make sure status is SUCCESS, then deliver the goods. If you cannot set up a webhook, you can poll the status via the API.

Done: you have accepted your first payment. Next, read the sections on webhooks (retries and idempotency) and errors (what to do on network failures).