Money,
moved through
your checkout.
Two REST endpoints, three callbacks, a sandbox you can sign up to today. Drop a Pay-with-iPay button into your checkout and let us handle login, MFA, and confirmation.
Drop this onto your checkout.
We'll do the rest.
Style it like the rest of your checkout — height, radius, and font are yours. We just handle what happens after the tap.
How a payment actually moves.
Five steps, three callbacks. The buyer never leaves the iPay flow once they tap the button — until you welcome them back to your success page.
- 01Merchant
Show the Pay-with-iPay button at checkout
Render the button on your checkout page. When the buyer taps it, your backend takes over.
- 02Merchant
Create the order from your backend
Call
POST /orderwithamount,referenceId,descriptionand three callback URLs. iPay returns apaymentUrl. - 03iPay
Redirect the buyer to the payment page
Send the buyer's browser to paymentUrl. iPay handles login, MFA, and the payment confirmation step.
- 04Merchant
Receive the success callback
On success, iPay redirects to your
successCallbackUrl. Strongly recommended: also callGET /order/.../statusfrom your backend before fulfilling the order. - 05Buyer
Or — handle cancel / failure
If the buyer cancels, iPay redirects to your
cancelCallbackUrl. On failure (insufficient balance, blocked account, limits crossed), iPay redirects tofailureCallbackUrl.
Belt-and-braces tip — even though the success callback fires from iPay, treat it as a hint. Verify with Check order status from your backend before you mark the order paid.
Sandbox first. Production when ready.
The sandbox is a full clone of production. Same endpoints, same response shapes — only the money is fake. Build, test, certify, then flip the base URL.
Behaves exactly like production — except no real money moves. Sign up for a sandbox business account just like the main site.
Live merchant gateway. Same endpoints, same shape — real money, real members, real transactions.
All API specs apply to both environments unless noted.
One header. One bearer token.
Every REST call carries an Authorization header with your API key. To get one (sandbox or production), get in touch.
Authorization: Bearer <API_KEY>
Note the single space between Bearer and your key. Treat the key like a password — never ship it to a browser.
POST /order
Open an order from your backend. Include the amount, your reference id, a description for the buyer, and the three callback URLs. Get back a paymentUrl to redirect the buyer to.
POST {baseurl}/order
Authorization: Bearer <API_KEY>
Content-Type: application/json
{
"amount": 120,
"referenceId": "abcd1234",
"description": "Buy x, y, z from XYZ.com",
"successCallbackUrl": "https://xyz.com/success/reference/abcd1234",
"failureCallbackUrl": "https://xyz.com/failure/reference/abcd1234",
"cancelCallbackUrl": "https://xyz.com/cancel/reference/abcd1234"
}200 OK
{
"message": "Order placed successfully",
"orderId": "IPAY-12345678",
"paymentUrl": "app.ipay.com.bd/pay/IPAY-12345678",
"referenceId": "abcd1234"
}401 { "message": "Invalid API key" }
409 { "message": "Reference Id 'abcd1234' has already been used" }Request fields
amountnumberrequiredTotal payable in BDT. Up to two decimal places — 100, 100.2, 100.23 are all OK; 100.234 is not.
referenceIdstringrequiredYour unique order id. Used later to query status. Max 50 chars. Must be unique per order, per merchant.
descriptionstringrequiredShown to the iPay member on the payment page so they know what they're paying for. Max 255 chars.
successCallbackUrlstringrequiredWe redirect the buyer's browser here after a successful payment. Max 512 chars.
failureCallbackUrlstringrequiredWe redirect here if the payment fails — insufficient balance, blocked account, limits crossed.
cancelCallbackUrlstringrequiredWe redirect here if the member cancels at the gateway. Max 512 chars.
Response fields
messagestringStatus summary.
orderIdstringUnique iPay-generated id. Use it later in Check status. Max 25 chars.
paymentUrlstringSend the buyer's browser here to complete the payment.
referenceIdstringEchoed back from the request.
GET /order/{id}/status
Query an order's current state — by your reference id, or by our order id. Use this from your backend to verify success before fulfilment, and to reconcile after the fact.
# By reference id (yours)
GET {baseurl}/order/referenceId/{referenceId}/status
Authorization: Bearer <API_KEY>
# Or by order id (ours)
GET {baseurl}/order/{orderId}/status
Authorization: Bearer <API_KEY>200 OK
{
"statusCode": 200,
"status": "Successfully paid",
"orderId": "IPAY-1234",
"referenceId": "abcd1234",
"transactionId": "23I2-12345678",
"transactionTime": "18 Sep 2017 12:33:39.749 BDT"
}Response fields
statusCodenumberSee status codes.
statusstringHuman-readable label for the same state.
orderIdstringiPay-generated order id.
referenceIdstringYour reference id.
transactionIdstringSet on success. Both buyer and merchant see this id in their iPay history. null otherwise.
transactionTimestringSet on success — timestamp of the transaction. null otherwise.
The six states of an order.
What a status means, and whether the order is still payable. Use the numeric statusCode in code; the human-readable label when rendering to your operations team.
Created by merchant. No member action yet — still payable.
Paid by an iPay member. Not payable anymore.
Member tapped Cancel at the gateway. Not payable.
Member tried to pay and failed — insufficient balance, blocked account, limits crossed. Not payable.
No action within 15 minutes of creation. Not payable.
Internal technical issue at the gateway. Contact iPay.
Build it in sandbox.
Ship it to production.
Tell us about your shop and we'll send you a sandbox account, an API key, and a person to talk to when something surprises you.