One REST API for pay-ins, payouts and wallet routing

Quick start

1. 1

   Get your key & salt

   Generate the API key and salt in your portal. Both are shown once — store them in your server vault.

2. 2

   Whitelist your server IP

   Only whitelisted IPs may call the API. Add every outbound IP of your backend.

3. 3

   Create an order

   POST a payin or payout with your own client_txn_id. The engine picks the wallet for you.

4. 4

   Receive the webhook

   We push the final result to your webhook URL and sign it. Verify, then update your ledger.

Eight words carry the whole API. Read these once and every endpoint below reads like plain English.

Authentication

Every endpoint is POST with a JSON body and lives under https://xpaybd.com/api/v1. There is no Authorization header — pass your key as the key field in the body. A bad or missing key returns 401 Unauthorized.

POST https://xpaybd.com/api/v1/wallet_balance
Content-Type: application/json

{ "key": "YOUR_API_KEY" }

Channels & limits

Pass the channel you want as bank_id. Amounts outside the per-transaction range below are rejected. Check live headroom with /available_limits before sending large batches — it returns overall and per-gateway capacity.

Both directions follow the same shape: you create an order, the routing engine does the work, and a signed webhook closes the loop. Average round trip is about one second.

Test every endpoint right here with your own API key — no Postman needed. Requests are relayed server-side to https://xpaybd.com/api/v1 and the raw response is shown exactly as your backend will receive it. Your key stays in this browser tab only and is never stored on our servers.

{
  "key": "••••••••",
  "client_txn_id": "payin-001",
  "amount": 500,
  "bank_id": 1,
  "redirect_url": "https://your-site.com/thank-you"
}

// Send a request to see the live response here.

curl -X POST 'https://xpaybd.com/api/v1/create_payin_order' \
  -H 'Content-Type: application/json' \
  -d '{
  "key": "YOUR_API_KEY",
  "client_txn_id": "payin-001",
  "amount": 500,
  "bank_id": 1,
  "redirect_url": "https://your-site.com/thank-you"
}'

Open a collection order. The engine picks a healthy agent wallet and returns the deposit account (plus a hosted checkout link when the bank supports it).

curl -X POST 'https://xpaybd.com/api/v1/create_payin_order' \
  -H 'Content-Type: application/json' \
  -d '{
    "key": "YOUR_API_KEY",
    "client_txn_id": "payin-001",
    "amount": 500,
    "bank_id": 1,
    "redirect_url": "https://your-site.com/thank-you"
  }'

{
  "status_code": 201,
  "message": "Payin order created successfully",
  "status": "success",
  "data": {
    "order_id": 1,
    "client_txn_id": "payin-001",
    "amount": 500,
    "total_amount": 500,
    "bank_name": "Nagad",
    "bank_account": "0171XXXXXXX",
    "checkout_url": "https://checkout.example.com/checkout/payin/...",
    "expired_at": "2026-08-04T17:23:05.992Z",
    "status": "pending"
  }
}

{
  "status_code": 422,
  "message": "amount must be a positive number",
  "status": "error"
}

{
  "status_code": 400,
  "message": "No available bank account found for payin",
  "status": "error"
}

Note — checkout_url is only returned when the target bank has the checkout page enabled. Send the customer there: they pay into the shown account and submit their TrxID. PayIn orders expire after 1 hour by default (see expired_at) and then auto-move to expired.

Submit the customer's bank transaction ID against a pending payin. On a match the order flips to success and wallet settlement runs.

curl -X POST 'https://xpaybd.com/api/v1/update_payin_order' \
  -H 'Content-Type: application/json' \
  -d '{
    "key": "YOUR_API_KEY",
    "client_txn_id": "payin-001",
    "txn_id": "A1B2C3D4E5"
  }'

{
  "status_code": 200,
  "message": "Payin order updated successfully",
  "status": "success",
  "data": {
    "order_id": 42,
    "client_txn_id": "payin-001",
    "bank_txn_id": "A1B2C3D4E5",
    "paid_amount": 500,
    "requested_amount": 500,
    "status": "success",
    "api_user_fee": 15.00,
    "created_at": "2026-08-04T10:00:00.000Z",
    "updated_at": "2026-08-04T10:05:00.000Z"
  }
}

{
  "status_code": 404,
  "message": "Order not found with this client_txn_id",
  "status": "error",
  "data": {}
}

{
  "status_code": 400,
  "message": "Order cannot be updated in its current status: success",
  "status": "error"
}

Note — Only orders in pending status can be updated.

Queue a disbursement. Funds leave a connected agent wallet and land on the customer's mobile number.

curl -X POST 'https://xpaybd.com/api/v1/create_payout_order' \
  -H 'Content-Type: application/json' \
  -d '{
    "key": "YOUR_API_KEY",
    "client_txn_id": "order-001",
    "mobile_no": "01712345678",
    "amount": 1000,
    "bank_id": 1
  }'

{
  "status_code": 201,
  "message": "Payout order created and queued successfully",
  "status": "success",
  "data": {
    "client_txn_id": "order-001",
    "amount": 1000,
    "mobile_no": "01712345678",
    "status": "queue",
    "agent_user_id": 5
  }
}

{
  "status_code": 201,
  "message": "Payout order failed — insufficient balance (need 1010, have 500)",
  "status": "error",
  "data": {
    "client_txn_id": "order-001",
    "status": "failed",
    "agent_user_id": null,
    "fail_reason": "Insufficient balance (including charges)"
  }
}

{
  "status_code": 409,
  "message": "client_txn_id already exists",
  "status": "error"
}

{
  "status_code": 400,
  "message": "Bank is currently not active",
  "status": "error"
}

Note — Charge slabs are applied automatically — your wallet is debited amount + charges. If the balance falls short, the order is created with a failed status instead of being rejected.

Cancel a payout that is still sitting in the queue. Once the dispatcher picks it up it can no longer be failed.

curl -X POST 'https://xpaybd.com/api/v1/fail_payout_order' \
  -H 'Content-Type: application/json' \
  -d '{
    "key": "YOUR_API_KEY",
    "client_txn_id": "order-001"
  }'

{
  "status_code": 200,
  "status": "success",
  "message": "Payout order failed successfully",
  "data": {
    "order_id": 123,
    "client_txn_id": "order-001",
    "status": "failed"
  }
}

{
  "status_code": 400,
  "message": "Order is already processing",
  "status": "error"
}

{
  "status_code": 422,
  "message": "Either client_txn_id or order_id is required",
  "status": "error"
}

Note — Only queued payouts that are not being processed can be failed. A failed order is never dispatched afterwards.

Poll the current state of any order — payin or payout.

curl -X POST 'https://xpaybd.com/api/v1/order_status' \
  -H 'Content-Type: application/json' \
  -d '{
    "key": "YOUR_API_KEY",
    "client_txn_id": "payin-001"
  }'

{
  "status_code": 200,
  "status": "success",
  "data": {
    "order_id": 42,
    "order_type": "payout",
    "client_txn_id": "payout-001",
    "bank_txn_id": "D9Q8UI5",
    "paid_amount": 500,
    "requested_amount": 500,
    "status": "success",
    "reason": null,
    "api_user_fee": 10,
    "created_at": "2026-02-19T09:00:00.000Z",
    "updated_at": "2026-02-19T09:05:00.000Z",
    "sender_acc": "01923043979",
    "receiver_acc": "01712345678"
  }
}

{
  "status_code": 404,
  "message": "Order not found",
  "status": "error"
}

Read the live wallet balance of the authenticated API user.

curl -X POST 'https://xpaybd.com/api/v1/wallet_balance' \
  -H 'Content-Type: application/json' \
  -d '{ "key": "YOUR_API_KEY" }'

{
  "status_code": 200,
  "status": "success",
  "data": { "balance": 1500.00 }
}

{
  "status_code": 401,
  "message": "Unauthorized Access",
  "status": "error"
}

Vault capacity across every active agent wallet — payin headroom, payout balance and limit, plus a per-gateway breakdown. Call it before sizing a batch.

curl -X POST 'https://xpaybd.com/api/v1/available_limits' \
  -H 'Content-Type: application/json' \
  -d '{ "key": "YOUR_API_KEY" }'

{
  "status_code": 200,
  "status": "success",
  "message": "Vault capacity fetched successfully",
  "data": {
    "currency": "BDT",
    "payin": {
      "status": "available",
      "available_capacity": 2500000,
      "minimum_order_amount": 500,
      "maximum_order_amount": 100000
    },
    "payout": {
      "status": "available",
      "available_balance": 1800000,
      "available_limit": 1500000,
      "minimum_order_amount": 500,
      "maximum_order_amount": 100000
    },
    "gateway_capacity": [
      {
        "gateway_type": "bkash_agent",
        "payin_available": 1000000,
        "payout_available_balance": 700000,
        "payout_available_limit": 600000,
        "status": "available"
      }
    ],
    "updated_at": "2026-08-13T23:42:00+06:00"
  }
}

Set your webhook URL in the portal (leave it empty to disable). Every final order state is pushed as JSON with an X-Signature header — HMAC-SHA256 of the raw request payload keyed with your salt. Verify it before you trust the payload, and always respond 200 quickly.

{
  "event": "payin_success",
  "data": {
    "order_id": 1,
    "order_type": "payin",
    "client_txn_id": "payin-001",
    "bank_txn_id": "DXXXXXXXX2",
    "paid_amount": 5000,
    "requested_amount": 5100,
    "reason": null,
    "status": "success",
    "api_user_fee": 101,
    "created_at": "2026-08-03T18:25:24.000Z",
    "updated_at": "2026-08-03T18:25:24.000Z",
    "sender_acc": "01712345678",
    "receiver_acc": "01987262113"
  }
}

// Node.js — verify the X-Signature header on every webhook
import crypto from "node:crypto";

app.post("/webhooks/pay2capital", express.raw({ type: "*/*" }), (req, res) => {
  const raw = req.body;                       // the RAW request payload, not JSON.parse'd
  const expected = crypto
    .createHmac("sha256", process.env.PAY2CAPITAL_SALT)
    .update(raw)
    .digest("hex");

  const received = req.get("X-Signature") ?? "";
  const ok =
    received.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));

  if (!ok) return res.status(401).send("bad signature");

  const event = JSON.parse(raw.toString("utf8"));
  // handle event.event: payin_success | payin_failed | payout_success | payout_failed
  res.sendStatus(200);
});

Order states

Common error codes

Retries are safe: reuse the same client_txn_id and a duplicate returns 409 instead of creating a second order. The same reference becomes reusable again after 24 hours.

Tick every line before you switch real traffic on. These eight points cover every support ticket we normally see in week one.

• Key and salt stored server-side in a vault — never in front-end code.
• All backend outbound IPs whitelisted in the portal.
• client_txn_id is unique per order and stored before you call us.
• Webhook endpoint is public, responds 200 fast, and verifies X-Signature on the raw body.
• Webhook handler is idempotent — the same event may arrive more than once.
• Amounts validated against the channel min/max before you call the API.
• order_status polling wired as a fallback for missed webhooks.
• Errors 401 / 409 / 422 / 400 mapped to your own user-facing messages.