Getting started

Onboard an application, get its credentials, and take your first test payment end to end.

This walks you from zero to a confirmed test payment.

Base URL

All endpoints live under the /api/v1 prefix:

Environment	Base URL
Local dev	`http://localhost:8080/api/v1`
Deployed	`https://<your-host>/api/v1`

The examples below use the local base URL.

Get your application registered

Applications are onboarded by an operator in the admin dashboard (Apps → Register). Registration creates your app and two credential pairs — one for TEST and one for LIVE. Each pair is a key + secret:

Key — looks like oi_test_… / oi_live_…. It is the public lookup handle.
Secret — shown once, at creation. Store it somewhere safe; it cannot be retrieved again, only rotated.

The raw secret is displayed exactly once. If you lose it, rotate the credential (the old one keeps working through a grace window) — see Authentication.

Verify your credentials

Call GET /app/me with your key and secret to confirm they resolve and to see which mode they authenticate as:

curl http://localhost:8080/api/v1/app/me \
  -H "X-Api-Key: oi_test_xxx" \
  -H "X-Api-Secret: your-secret"

{
  "data": { "id": 42, "name": "Storefront", "mode": "TEST" },
  "meta": { "success": true, "timestamp": "2026-06-04T10:00:00Z" }
}

The mode is fixed by the credential — your test key always runs as TEST.

Create a payment

Create a payment intent. Amounts are integer minor units (paisa) — 10000 is 100.00 BDT.

curl -X POST http://localhost:8080/api/v1/payments \
  -H "X-Api-Key: oi_test_xxx" \
  -H "X-Api-Secret: your-secret" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0f8b…-unique-per-attempt" \
  -d '{
    "amountMinor": 10000,
    "currency": "BDT",
    "customerReference": "cust_123",
    "customerEmail": "[email protected]",
    "productName": "Pro plan"
  }'

The response carries a reference and a checkoutUrl:

{
  "data": {
    "id": 100,
    "reference": "pay_abc",
    "status": "PENDING",
    "amountMinor": 10000,
    "currency": "BDT",
    "checkoutUrl": "http://localhost:3000/checkout/pay_abc"
  },
  "meta": { "success": true, "timestamp": "2026-06-04T10:00:01Z" }
}

Send the customer to checkout

Redirect the customer's browser to checkoutUrl. They complete payment on the gateway's hosted page — your app never handles card data. In TEST mode this routes to the SSLCOMMERZ sandbox.

React to the confirmed result

When the gateway confirms, the service finalizes the payment and delivers a signed payment.succeeded webhook to your app's configured URL. Treat the webhook (or a GET /payments/{id} poll) as the source of truth — not the browser redirect.

curl http://localhost:8080/api/v1/payments/100 \
  -H "X-Api-Key: oi_test_xxx" -H "X-Api-Secret: your-secret"

Next steps

Accept a payment — the full lifecycle and edge cases.
Webhooks — verify signatures and dedupe events.
Idempotency — make retries safe.
Invoicing and Refunds.