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

{
  "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"
}

{
  "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",
  "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": 400,
  "message": "Order has expired",
  "status": "error",
  "data": {
    "order_id": 42,
    "client_txn_id": "payin-001",
    "bank_txn_id": "A1B2C3D4E5",
    "paid_amount": 500,
    "requested_amount": 500,
    "status": "expired",
    "api_user_fee": 15.00,
    "created_at": "2026-08-04T10:00:00.000Z",
    "updated_at": "2026-08-04T10:10:00.000Z"
  }
}

{
  "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",
    "amount": 1000,
    "mobile_no": "01712345678",
    "status": "failed",
    "agent_user_id": null,
    "fail_reason": "Insufficient balance (including charges)"
  }
}

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

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

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

{
  "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": 400,
  "message": "Order cannot be failed in its current status: success",
  "status": "error"
}

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

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

{
  "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"
}

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

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

{
  "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"
  }
}