Payments API

Verify TrxID

Matching is always provider + TrxID + amount. Amount-only matching is never used (two ৳500 payments would collide).

Two ways to verify — API key (from your server) or the public endpoint (submitted by the buyer on the checkout page).

Via API key (server-side)

POST/api/v1/payments/:id/verify

Auth: X-Api-Key: YOUR_STORE_API_KEY

Via buyer (checkout page)

POST/api/payments/public/:id/verify

No auth needed — used by the hosted checkout.

request
{
  "trxId": "BKH8X2K1M",
  "provider": "bkash"
}

What happens

  • SMS already in inbox with same TrxID, provider, amount → confirmed (money received)
  • SMS not in yet → verifying — submit again once the SMS arrives (no auto-polling)
  • SMS amount differs → failed + 400
  • TrxID already on another invoice → 400

Two-phase: confirm the order

A matched payment on your store lands in confirmed — the money has arrived, but it is not verified until you confirm you have fulfilled the order. Call the confirm endpoint from your server after creating the order / reserving stock:

POST/api/v1/payments/:id/confirm

Auth: X-Api-Key: YOUR_STORE_API_KEY

  • confirmed → verified (final)
  • Already verified → returns unchanged (idempotent)
  • Not paid yet (pending / verifying) → 400

Subscription and balance top-up payments skip this — they go straight to verified on match.