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

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