Accept a payment

A payment is taken through the gateway's hosted checkout — your app never sees card data. You create an intent, send the customer to the returned URL, and react to the confirmed result from a verified webhook.

All amounts are integer minor units (paisa): 150000 means 1,500.00 BDT. The mode (TEST or LIVE) is derived from the API credential that authenticated the request — never from the request body.

The flow

curl -X POST http://localhost:8080/api/v1/payments \
  -H "X-Api-Key: oi_test_8f3c1a9b2d4e" \
  -H "X-Api-Secret: sk_test_2b7e9f0a4c6d8e1f" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9f1c2e44-7a3b-4c2e-9b21-0c6d5a8e1f44" \
  -d '{
    "amountMinor": 150000,
    "currency": "BDT",
    "customerReference": "cust_4821",
    "customerEmail": "[email protected]",
    "customerName": "Rumana Karim",
    "productName": "Pro plan (annual)",
    "successUrl": "legacycouch://payment-return",
    "metadata": { "orderId": "ord_99812", "cartRef": "cart_5567" }
  }'

{
  "id": 4821,
  "reference": "PAY-7K2QF8M3ND",
  "status": "PENDING",
  "applicationId": 42,
  "mode": "TEST",
  "amountMinor": 150000,
  "currency": "BDT",
  "gateway": "SSLCOMMERZ",
  "checkoutUrl": "http://localhost:3000/checkout/PAY-7K2QF8M3ND",
  "redirectUrl": "https://sandbox.sslcommerz.com/gwprocess/v4/gw.php?Q=pay&SESSIONKEY=AB12CD34",
  "metadata": { "orderId": "ord_99812", "cartRef": "cart_5567" },
  "createdAt": "2026-06-30T12:00:00",
  "updatedAt": "2026-06-30T12:00:01"
}

Create payment request

POST /api/v1/payments — requires the app API-key headers. The app_id and mode come from the credential, never from the body.

Return URLs & deep links

successUrl / failUrl / cancelUrl are where the service-hosted return page hops the customer's browser after the gateway flow completes — typically a deep link back into a native app (e.g. legacycouch://payment-return). Custom URL schemes are allowed on purpose, so there is no generic URL-format constraint.

Each non-null URL is checked against the app's return-URL allow-list — deny-by-default. An out-of-allow-list value is rejected with 400, so an attacker-influenceable redirect target can never leave the app's declared prefixes.

• Per-field resolution: the per-payment value wins; if omitted, the app's configured default for that terminal state is used; if neither is set, the field is null.
• The gateway is always handed the service's own hosted return pages — your URLs only drive the final hop after the result is shown.

# Rejected: successUrl outside the app's allow-list → 400
curl -X POST http://localhost:8080/api/v1/payments \
  -H "X-Api-Key: oi_test_8f3c1a9b2d4e" -H "X-Api-Secret: sk_test_2b7e9f0a4c6d8e1f" \
  -H "Content-Type: application/json" \
  -d '{ "amountMinor": 150000, "customerReference": "cust_4821",
        "successUrl": "https://evil.example.com/return" }'

{
  "data": null,
  "meta": {
    "success": false,
    "message": "successUrl is not permitted by this app's return-URL allow-list",
    "errorCode": "VALIDATION_ERROR",
    "timestamp": "2026-06-30T12:00:00Z"
  },
  "pagination": null
}

Metadata passthrough

metadata is an optional JSON object stored as-is and echoed back unchanged on the settlement webhook; it is never interpreted or merged. Use it for your own order ids, cart references, etc. It is bounded (size / depth / key-count, object-root only, tunable via app.metadata.*).

When metadata is omitted on a payment raised for an invoice (invoiceId set), the invoice's stored metadata is inherited. When present, your value is used as-is — the two are never merged. A standalone payment with no metadata carries none.

Amount rules

amountMinor is an integer count of minor units (paisa) — never floating point. Beyond the shape check (> 0), the use case enforces the app's configurable minAmountMinor / maxAmountMinor bounds (PAY-12). An amount below the minimum or above the maximum is rejected with 400. Currency is BDT-only in v1; any other code is a 400.

# Rejected: non-BDT currency → 400
curl -X POST http://localhost:8080/api/v1/payments \
  -H "X-Api-Key: oi_test_8f3c1a9b2d4e" -H "X-Api-Secret: sk_test_2b7e9f0a4c6d8e1f" \
  -H "Content-Type: application/json" \
  -d '{ "amountMinor": 150000, "currency": "USD", "customerReference": "cust_4821" }'

{
  "data": null,
  "meta": {
    "success": false,
    "message": "Unsupported currency 'USD'; only BDT is supported",
    "errorCode": "VALIDATION_ERROR",
    "timestamp": "2026-06-30T12:00:00Z"
  },
  "pagination": null
}

Payment response (PaymentDto)

Returned from create (201), the status lookup, and the by-reference list. Null fields are omitted from the JSON.

Payment lifecycle

Terminal below means the payment will never change status again — you can release the order, close the cart, or record the loss and never revisit it. Every status in the table is terminal except CREATED, PENDING and EXPIRED.

EXPIRED is not the end of the story

We close the checkout on our side when the deadline passes, but the gateway's own session can outlive it — we have no way to cancel a session at SSLCOMMERZ. A customer who was already on the gateway's payment page when the deadline passed can still complete the payment, and that money is real. When the confirmation reaches us we revive the payment to SUCCEEDED and send payment.succeeded, after having already sent payment.expired.

So payment.expired means "stop waiting for this one", not "this can never succeed". Two consequences for your integration:

• Anything you do on payment.expired must be reversible, or deferred. Releasing a held cart is fine; refusing to ever fulfil this payment_id again is not.
• A payment.succeeded for a payment you already saw expire is not a replay to discard.

For one payment_id you can legitimately receive both, in either order — webhook delivery is unordered. Rank the statuses rather than trusting arrival order:

data.previous_status on the succeeded event distinguishes the two cases without keeping state: "pending" is an ordinary settlement, "expired" is a revival. Full detail in Late settlement after expiry.

Reading status

curl http://localhost:8080/api/v1/payments/4821 \
  -H "X-Api-Key: oi_test_8f3c1a9b2d4e" -H "X-Api-Secret: sk_test_2b7e9f0a4c6d8e1f"

{
  "data": {
    "id": 4821,
    "reference": "PAY-7K2QF8M3ND",
    "status": "SUCCEEDED",
    "applicationId": 42,
    "mode": "TEST",
    "amountMinor": 150000,
    "currency": "BDT",
    "gateway": "SSLCOMMERZ",
    "gatewayTxnId": "SSLZ-2026063000412",
    "checkoutUrl": "http://localhost:3000/checkout/PAY-7K2QF8M3ND",
    "metadata": { "orderId": "ord_99812", "cartRef": "cart_5567" },
    "createdAt": "2026-06-30T12:00:00",
    "updatedAt": "2026-06-30T12:04:18"
  },
  "meta": { "success": true, "message": null, "errorCode": null, "timestamp": "2026-06-30T12:05:00Z" },
  "pagination": null
}

curl "http://localhost:8080/api/v1/payments?customerReference=cust_4821" \
  -H "X-Api-Key: oi_test_8f3c1a9b2d4e" -H "X-Api-Secret: sk_test_2b7e9f0a4c6d8e1f"

{
  "data": [
    { "id": 4821, "reference": "PAY-7K2QF8M3ND", "status": "SUCCEEDED", "amountMinor": 150000, "currency": "BDT", "mode": "TEST", "createdAt": "2026-06-30T12:00:00" },
    { "id": 4733, "reference": "PAY-3D9H2KQ7BW", "status": "EXPIRED", "amountMinor": 50000, "currency": "BDT", "mode": "TEST", "createdAt": "2026-06-29T09:14:02" }
  ],
  "meta": { "success": true, "message": null, "errorCode": null, "timestamp": "2026-06-30T12:05:00Z" },
  "pagination": null
}

Receipts

GET /payments/{id}/receipt returns the receipt payload for a settled payment. A receipt exists only for a SUCCEEDED payment — a lookup against any other state (or a cross-app id) is a 404. There is no "receipts enabled" toggle; settlement is the only gate.

curl http://localhost:8080/api/v1/payments/4821/receipt \
  -H "X-Api-Key: oi_test_8f3c1a9b2d4e" -H "X-Api-Secret: sk_test_2b7e9f0a4c6d8e1f"

{
  "data": {
    "paymentId": 4821,
    "reference": "PAY-7K2QF8M3ND",
    "status": "SUCCEEDED",
    "amountMinor": 150000,
    "amountDisplay": "1,500.00",
    "currency": "BDT",
    "customerReference": "cust_4821",
    "customerEmail": "[email protected]",
    "appName": "Legacy Couch Store",
    "gateway": "SSLCOMMERZ",
    "paidAt": "2026-06-30T12:04:18"
  },
  "meta": { "success": true, "message": null, "errorCode": null, "timestamp": "2026-06-30T12:05:00Z" },
  "pagination": null
}

A receipt request for a still-PENDING (or non-existent) payment:

{
  "data": null,
  "meta": {
    "success": false,
    "message": "Receipt not found with id: 4821",
    "errorCode": "RESOURCE_NOT_FOUND",
    "timestamp": "2026-06-30T12:05:00Z"
  },
  "pagination": null
}

Receipt payload (ReceiptDto)

Hosted checkout context (advanced)

The service-hosted checkout page reads GET /checkout/{reference} — an unauthenticated, reference-keyed endpoint (the opaque reference is the bearer). It carries no PII and no app-internal data — only what a paying customer is entitled to see. You normally don't call this directly; the hosted checkout page does. An unknown reference is a 404.

curl http://localhost:8080/api/v1/checkout/PAY-7K2QF8M3ND

Checkout context payload (CheckoutContextDto)

Error reference

All errors use the standard envelope with data: null and a machine-readable meta.errorCode. See Responses & errors.

Related