Introduction
A centralized payment service — hosted checkout, invoicing, refunds, a double-entry ledger, and signed webhooks — that any internal application can integrate against.
OI Payments is a shared payment service. Instead of every application re-implementing gateway integration, reconciliation, and refund handling, an app integrates once against this API and gets:
- Hosted checkout through the SSLCOMMERZ gateway — you never touch card data.
- Invoicing with line items, branded PDFs, payable links, and installments.
- Refunds (full or partial) with an optional approval workflow.
- Signed webhooks so your app reacts to payment, refund, and invoice events.
- A double-entry ledger and settlement reconciliation behind the scenes.
- An admin dashboard with role-based access for operators.
Beyond one-off payments, you also get a Stripe-style catalogue and recurring billing layer — every record still app- and mode-scoped, every amount still in BDT minor units:
- A product & price catalogue — each product carries one or more prices,
billed
ONE_TIMEorRECURRING(monthly, quarterly, yearly). See Products & prices. - Subscriptions with automated, link-paid billing — free trials, coupons, and failed-renewal dunning. Each cycle auto-issues an invoice and a payable link the customer pays through hosted checkout (no off-session card charging). See Subscriptions.
- One-time purchases of a catalogue product — a single invoice and checkout, no subscription created. See One-time purchases.
- Benefits & entitlements so your app can gate features by a stable
lookup_keythat survives repricing or renaming. See Entitlements. - Coupons — percentage or fixed discounts applied to a subscription's cycle invoices. See Coupons.
- Customer lookup — resolve a customer reference and list their payments. See Look up customers.
How integration works
Your app authenticates with an API key + secret, creates a payment, and
redirects the customer to the returned checkoutUrl. The gateway calls back to
the service; the service confirms the payment, posts to the ledger, and delivers
a signed webhook to your app. Money never moves optimistically — your app
reacts to the confirmed state, not the redirect.
Three things to know first
Money is integer minor units
Every amount is an integer count of the currency's smallest unit (paisa for
BDT) — 10000 means 100.00 BDT. Never use floating point for money.
Test and live are fully isolated
Every record carries a mode of TEST or LIVE, derived from the credential
that authenticated the request — never from the request body. A test key can
never touch live data.
Every response uses one envelope
Success or failure, every endpoint returns the same { data, meta, pagination }
shape with a stable, machine-readable errorCode. See
Responses & errors.
Where to go next
Getting started
Onboard an app, get credentials, and make your first payment.
Authentication
API key + secret, credential rotation, and step-up re-auth.
Core concepts
Modes, money, idempotency, app isolation, and the response envelope.
Accept a payment
The end-to-end hosted-checkout flow.
Webhooks
The event catalogue and how to verify signatures.
API reference
Every endpoint, generated from the OpenAPI spec.
Catalogue & recurring billing
Catalogue & subscriptions
How products, prices, subscriptions, benefits, and entitlements fit together.
Products & prices
Build a catalogue of products with one-time and recurring prices.
Subscriptions
Create recurring subscriptions billed against a recurring price.
One-time purchases
Sell a catalogue product through a single invoice and checkout.
Coupons
Percentage or fixed discounts applied to subscription cycles.
Entitlements
Gate features by a stable benefit lookup_key.
Look up customers
Resolve a customer reference and list their payments.
Operate from the admin panel
Admin panel
The session-authenticated operations console and its RBAC model.
Products & benefits
Author products, prices, and the benefit catalogue for any app.
Subscriptions
Search subscriptions and run billing, trial-reminder, and dunning sweeps.
Dashboard analytics
Mode-aware metrics, timeseries, aging, and top breakdowns.