Idempotency keys
Retry any request safely — duplicates are never created.
Developers
One API for every local rail
Create deposits, send payouts and reconcile settlement across 12 markets with a single, consistent REST API. Predictable semantics, signed webhooks and a full sandbox help your team ship faster.
POST /v1/payouts Idempotency-Key: wd-55120 { "merchant_order_id": "wd-55120", "amount": "12500000", "currency": "VND", "method": "bank_transfer", "beneficiary": { "bank_code": "VCB", "account_number": "0000123456", "account_name": "NGUYEN VAN A" } } # 201 Created { "id": "po_3Lm8Rv2", "status": "processing" }
Illustrative example. Exact endpoints and fields are in the API reference shared during onboarding.
Quickstart
Your first deposit in four steps
Everything happens in the sandbox first, so you can test every path before real money moves.
- 1
Get your keys
Create an app in the merchant console to receive sandbox API credentials and a webhook secret.
- 2
Create a deposit
Send the amount, currency, method and your own order reference. An idempotency key makes every retry safe.
- 3
Send the trader to pay
Redirect to the hosted cashier URL, or show the QR code and bank details in your own interface.
- 4
Handle the webhook
Verify the signature, then credit the trader’s account once the status is
succeeded.
curl -X POST "$IBITPAY_API/v1/payins" \ -H "Authorization: Bearer $IBITPAY_SECRET_KEY" \ -H "Idempotency-Key: dep-102938" \ -H "Content-Type: application/json" \ -d '{ "merchant_order_id": "dep-102938", "amount": "35000.00", "currency": "THB", "method": "promptpay_qr", "customer": { "account": "MT5-88012291" }, "notify_url": "https://broker.example/webhooks/ibitpay" }'
const res = await fetch(`${process.env.IBITPAY_API}/v1/payins`, { method: "POST", headers: { "Authorization": `Bearer ${process.env.IBITPAY_SECRET_KEY}`, "Idempotency-Key": order.id, "Content-Type": "application/json", }, body: JSON.stringify({ merchant_order_id: order.id, amount: "35000.00", currency: "THB", method: "promptpay_qr", customer: { account: "MT5-88012291" }, notify_url: "https://broker.example/webhooks/ibitpay", }), }); const payin = await res.json(); // Redirect the trader to payin.cashier_url
import os, requests resp = requests.post( f"{os.environ['IBITPAY_API']}/v1/payins", headers={ "Authorization": f"Bearer {os.environ['IBITPAY_SECRET_KEY']}", "Idempotency-Key": order_id, }, json={ "merchant_order_id": order_id, "amount": "35000.00", "currency": "THB", "method": "promptpay_qr", "customer": {"account": "MT5-88012291"}, "notify_url": "https://broker.example/webhooks/ibitpay", }, timeout=15, ) payin = resp.json() # redirect the trader to payin["cashier_url"]
$ch = curl_init(getenv('IBITPAY_API') . '/v1/payins'); curl_setopt_array($ch, [ CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('IBITPAY_SECRET_KEY'), 'Idempotency-Key: ' . $orderId, 'Content-Type: application/json', ], CURLOPT_POSTFIELDS => json_encode([ 'merchant_order_id' => $orderId, 'amount' => '35000.00', 'currency' => 'THB', 'method' => 'promptpay_qr', 'customer' => ['account' => 'MT5-88012291'], 'notify_url' => 'https://broker.example/webhooks/ibitpay', ]), ]); $payin = json_decode(curl_exec($ch), true);
Illustrative example. Exact endpoints and fields are in the API reference shared during onboarding.
Webhooks
Know the moment money moves
Every status change triggers a signed webhook to your endpoint. Failed deliveries are retried automatically, and the order status API is always there for reconciliation.
payin.pendingpayin.succeededpayin.failedpayin.expiredpayout.processingpayout.succeededpayout.failedsettlement.completed
- Signed with your webhook secret
- Automatic retries with back-off
- Order status API for reconciliation
import crypto from "node:crypto"; // Check the X-Signature header before trusting an event export function verifyWebhook(rawBody, header, secret) { const { t, v1 } = Object.fromEntries( header.split(",").map((part) => part.split("=")) ); const expected = crypto .createHmac("sha256", secret) .update(`${t}.${rawBody}`) .digest("hex"); return v1?.length === expected.length && crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected)); }
Illustrative example. Exact endpoints and fields are in the API reference shared during onboarding.
Order lifecycle
Clear states, no surprises
Pay-ins and payouts move through a small set of well-defined states. Each one is timestamped and visible in the console.
Pay-in
created
pending
succeeded
failed
expired
Payout
submitted
processing
succeeded
failed
Built for reliability
The details your engineers care about
Signed messages
Every request and webhook is signed and verifiable on both sides.
Explicit error codes
Machine-readable codes with clear, actionable messages.
Full sandbox
Simulate success, failure and expiry for every method before going live.
Postman collection
Explore every endpoint before you write a line of code.
Reconciliation exports
Order, fee and settlement data in the formats finance teams expect.
Integration options
Choose how deep you go
Hosted cashier
Redirect traders to a localised, mobile-first payment page. The quickest way to go live.
- Local languages and currencies
- QR codes and bank app deep links
Embedded checkout
Embed the cashier inside your client portal so traders never leave your brand experience.
- Matches your portal’s flow
- Same webhooks and reporting
Direct API
Build your own interface and call the API server-to-server for full control over every step.
- Your UI, your rules
- Pay-ins, payouts and balances
Start building
Ready to build?
Request sandbox credentials and our integration team will help you plan your launch.