API reference

Authentication

Send your API key in the TSPAY-API-KEY header with every request.

API URL: https://www.tsgateway.tshost.shop/api

Create a payment

POST https://www.tsgateway.tshost.shop/api/checkout-v2

curl -X POST https://www.tsgateway.tshost.shop/api/checkout-v2 \
  -H "TSPAY-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "500",
    "currency": "BDT",
    "full_name": "Rahim",
    "email": "rahim@example.com",
    "metadata": {"order_id": "1001"},
    "redirect_url": "https://yoursite.com/success",
    "cancel_url": "https://yoursite.com/cancel",
    "webhook_url": "https://yoursite.com/webhook"
  }'

Response:

{"status": true, "message": "Payment Url", "payment_url": "https://www.tsgateway.tshost.shop/pay.php?id=..."}

Redirect your customer to payment_url.

currency is optional: BDT (default), USD or INR. The customer can pay with any of your gateways; amounts are converted using the site's exchange rates.

Verify a payment

After payment the customer returns to your redirect_url with ?invoice_id=.... Verify it on your server:

curl -X POST https://www.tsgateway.tshost.shop/api/verify-payment \
  -H "TSPAY-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"invoice_id": "INVOICE_ID"}'

{
  "full_name": "Rahim", "email": "rahim@example.com",
  "amount": "500.00", "fee": "0.00", "charged_amount": "500.00",
  "invoice_id": "...", "metadata": {"order_id": "1001"},
  "payment_method": "bkash", "sender_number": "01XXXXXXXXX",
  "transaction_id": "9AB1CD2EF3", "date": "2026-10-13 12:00:00",
  "status": "COMPLETED"
}

Only trust status = COMPLETED.

Telegram bots (no domain, no webhook)

Your bot does not need a website. Create a payment, send the payment_url as a button, and poll for completed payments from a cron job.

Extra fields for checkout-v2: ref (your own user id, returned later) and telegram_chat_id (the customer's chat; we message them in your bot when they pay - set your bot token in Notifications).

curl -X POST https://www.tsgateway.tshost.shop/api/payments \
  -H "TSPAY-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"after_id": 0}'

{"status": true, "last_id": 12, "payments": [ {"event_id": 12, "ref": "123456789", "amount": "500.00", "invoice_id": "...", "status": "COMPLETED"} ]}

Store last_id and send it as after_id next time. Credit each invoice_id only once. You can also pass "ref" or "invoice_id" to filter.

Webhook

If you pass webhook_url, we send a POST with the same JSON as above and the header TSPAY-API-KEY when a payment completes. Compare that header with your API key before accepting it.

Signed webhooks (recommended). Every webhook also carries X-TSPay-Timestamp and X-TSPay-Signature. The signature is sha256= followed by the HMAC SHA-256 of timestamp + "." + raw request body, using your API key as the secret. Reject the request if the signature does not match or the timestamp is more than 5 minutes old.

Security checklist

• Call the API only from your server. Never put the API key in JavaScript, a mobile app or a public repository.
• Do not trust the redirect back to your site. Confirm with verify-payment (status COMPLETED and the right amount) before delivering anything.
• Verify webhook signatures and mark each order as paid only once.
• Webhook and redirect URLs must be public https addresses on port 443 (80, 8080 and 8443 also work). Private and local addresses are blocked.
• Requests are limited to 300 per minute per key. Repeated wrong keys are blocked for a minute.
• If a key leaks, regenerate it in your panel under API Keys.

Crypto networks

These gateways are checked on the blockchain automatically. The customer sends the exact amount shown to your wallet and the invoice completes by itself, usually within a few minutes. The payment_method value in the verify response is the key below.