Payout API Reference

All Payout API endpoints in integration order. Use https://api.sandbox.blox.my while testing and https://api.blox.my in production.

Read requests require blox-api-key. Write requests require the API key, an HTTP message signature, and—where shown—an Idempotency-Key UUID v4.

Every error uses { "code": "…", "message": "…", "requestId": "…" }. Branch on code, never message; the tables under each endpoint list the expected status and code combinations.

Get prefund balance

Returns the prefund balance. This endpoint takes no parameters and is limited to 60 requests per minute per account.

Response — 200

{
  "available": "4900000",
  "inFlight": "99000",
  "receivable": "0"
}

available already excludes inFlight; do not subtract it again. A negative receivable suspends payout routes with 403 FEATURE_DISABLED until resolved. Use payout.prefund_completed instead of polling for top-ups.

{
  "code": "UNAUTHORIZED",
  "message": "API key is required",
  "requestId": "9f21ab04-6c3e-4d90-b1a7-8e5f2c0d4416"
}

Get active banks

Returns the banks and e-wallets that can receive payouts, with the bank codes accepted by beneficiary and payout requests. The endpoint is limited to 600 requests per minute per account.

Response — 200

[
  {
    "name": "Maybank",
    "bankCode": "MBBEMYKL"
  },
  {
    "name": "TNG Digital (TouchNGo)",
    "bankCode": "TNGDMYNB"
  }
]

Use bankCode wherever the API asks for bankCode.

{
  "code": "UNAUTHORIZED",
  "message": "API key is required",
  "requestId": "9f21ab04-6c3e-4d90-b1a7-8e5f2c0d4416"
}

Create beneficiary

Registers a reusable beneficiary. This endpoint requires an Idempotency-Key UUID v4 and is limited to 20 requests per minute per account.

The name is trimmed and uppercased. Registration does not deduplicate matching details; search first if the beneficiary may already exist. The default active-beneficiary limit is 1,000.

Response — 200

{
  "id": "7c1a3e88-9d2b-4f61-8a44-1f0b6d3c9a55",
  "name": "ADA LOVELACE",
  "accountNumber": "1234567890",
  "bank": { "code": "MBBM", "name": "Maybank" },
  "autoWithdrawalAddress": null,
  "createdAt": "2026-07-16T09:30:00.000Z",
  "updatedAt": "2026-07-16T09:30:00.000Z"
}

The response uses the shared Beneficiary object.

{
  "code": "VALIDATION_FAILED",
  "message": "name: Beneficiary name can't be less than 2 characters",
  "requestId": "9f21ab04-6c3e-4d90-b1a7-8e5f2c0d4416"
}

List beneficiaries

Returns active beneficiaries, newest first.

Response — 200

{
  "data": [],
  "hasMore": true,
  "nextCursor": "9f21ab04-…"
}

Each data item is a Beneficiary object. Continue with nextCursor until hasMore is false; nextCursor is null on the last page.

{
  "code": "VALIDATION_FAILED",
  "message": "limit: Number must be less than or equal to 100",
  "requestId": "9f21ab04-6c3e-4d90-b1a7-8e5f2c0d4416"
}

Get beneficiary

Returns one active beneficiary. Unknown, inactive, and cross-account IDs return 404 NOT_FOUND.

Response — 200: Beneficiary object.

{
  "code": "UNAUTHORIZED",
  "message": "API key is required",
  "requestId": "9f21ab04-6c3e-4d90-b1a7-8e5f2c0d4416"
}

Delete beneficiary

Soft-deletes the beneficiary and its deposit trigger address, if present. Sign @method and @path only; no Content-Digest is required.

Response — 200

{ "success": true }

{
  "code": "UNAUTHORIZED",
  "message": "API key is required",
  "requestId": "9f21ab04-6c3e-4d90-b1a7-8e5f2c0d4416"
}

Create payout

Creates and immediately submits a payout. The accepted payout is debited from available and returned as INITIATED. This endpoint is limited to 300 requests per minute per account.

Header

Body

DEDUCT_FROM_AMOUNT sends amount - fee; CHARGE_TO_PREFUND sends the full amount. In both cases, the prefund debit is netAmount + fee. Read both values from the response.

amount is the gross value before fees. With DEDUCT_FROM_AMOUNT, netAmount must remain at least RM1.00; under the standard RM1.50 fee floor, the smallest valid gross amount is RM2.50.

Inline beneficiaries are stored on first use and deduplicated by bank, account number, and case-insensitive name. Registered beneficiaries are optional.

Response — 200

{
  "payoutId": "b0e6c2f4-2a1d-4a9e-9f3c-2c9f5a1b7e10",
  "status": "INITIATED",
  "type": "STANDARD",
  "amount": "100000",
  "fee": "1000",
  "netAmount": "99000",
  "beneficiaryId": "7c1a3e88-9d2b-4f61-8a44-1f0b6d3c9a55",
  "bankAccountId": null,
  "idempotencyKey": "6f9619ff-8b86-d011-b42d-00cf4fc964ff",
  "reference": "INV-4471",
  "statusReason": null,
  "createdAt": "2026-07-16T09:30:00.000Z",
  "submittedAt": null
}

The response uses the shared Payout object. A 202 response means the original request for that key is still processing; retry with the same key.

Idempotency rules

• Persist one UUID v4 before sending a logical payout.
• Retry a timeout, 429, 500, or 503 with the same key.
• Retry a rejected 4xx with a new key after correcting the request.
• Reusing a key with a different body returns 422 VALIDATION_FAILED.

See Payout Errors for the complete code and retry table.

{
  "code": "VALIDATION_FAILED",
  "message": "amount: Amount can't be less than 1 MYR",
  "requestId": "9f21ab04-6c3e-4d90-b1a7-8e5f2c0d4416"
}

{
  "code": "INVALID_REQUEST",
  "message": "Idempotency-Key must be a valid UUID v4",
  "requestId": "9f21ab04-6c3e-4d90-b1a7-8e5f2c0d4416"
}

{
  "code": "INSUFFICIENT_BALANCE",
  "message": "Insufficient prefund balance",
  "requestId": "9f21ab04-6c3e-4d90-b1a7-8e5f2c0d4416"
}

{
  "code": "UNKNOWN_BENEFICIARY",
  "message": "Beneficiary not found",
  "requestId": "9f21ab04-6c3e-4d90-b1a7-8e5f2c0d4416"
}

{
  "code": "LIMIT_EXCEEDED",
  "message": "Daily payout limit exceeded",
  "requestId": "9f21ab04-6c3e-4d90-b1a7-8e5f2c0d4416"
}

{
  "code": "UNAUTHORIZED",
  "message": "API key is required",
  "requestId": "9f21ab04-6c3e-4d90-b1a7-8e5f2c0d4416"
}

{
  "code": "LIMIT_EXCEEDED",
  "message": "Active beneficiary limit exceeded",
  "requestId": "9f21ab04-6c3e-4d90-b1a7-8e5f2c0d4416"
}

{
  "code": "FEATURE_DISABLED",
  "message": "Payout is not enabled for this account",
  "requestId": "9f21ab04-6c3e-4d90-b1a7-8e5f2c0d4416"
}

{
  "code": "ACCOUNT_FROZEN",
  "message": "Account is frozen",
  "requestId": "9f21ab04-6c3e-4d90-b1a7-8e5f2c0d4416"
}

{
  "code": "ACCOUNT_PENDING_VERIFICATION",
  "message": "Account is pending verification",
  "requestId": "9f21ab04-6c3e-4d90-b1a7-8e5f2c0d4416"
}

{
  "code": "ACCOUNT_TERMINATED",
  "message": "Account is terminated",
  "requestId": "9f21ab04-6c3e-4d90-b1a7-8e5f2c0d4416"
}

{
  "code": "VALIDATION_FAILED",
  "message": "Idempotency key was already used with a different request body",
  "requestId": "9f21ab04-6c3e-4d90-b1a7-8e5f2c0d4416"
}

{
  "code": "RATE_LIMITED",
  "message": "Too many payout requests. Please try again later.",
  "requestId": "9f21ab04-6c3e-4d90-b1a7-8e5f2c0d4416"
}

{
  "code": "SERVICE_UNAVAILABLE",
  "message": "Payout service is temporarily unavailable. Please try again later.",
  "requestId": "9f21ab04-6c3e-4d90-b1a7-8e5f2c0d4416"
}

Get payout

Returns a payout by payoutId. Use webhooks for status changes; use this endpoint for reconciliation or missed webhook recovery. The endpoint is limited to 600 requests per minute per account.

Response — 200: Payout object. Unknown and cross-account IDs return 404 NOT_FOUND.

{
  "code": "UNAUTHORIZED",
  "message": "API key is required",
  "requestId": "9f21ab04-6c3e-4d90-b1a7-8e5f2c0d4416"
}

Create a deposit trigger address

Gives a beneficiary an on-chain address. Tokens sent to it are paid to that beneficiary automatically, with no POST /v1/payouts from you and without touching your prefund balance. See Pay a beneficiary from a deposit.

The beneficiary must be active. Calling this again returns the same address — a beneficiary has one, for its lifetime — so no Idempotency-Key is needed. Limited to 20 calls per minute. Deleting the beneficiary deactivates its address.

Success response (201)

{
  "address": "0x7c1a3e889d2b4f618a441f0b6d3c9a5588ab01cd",
  "network": "EVM",
  "destination": {
    "type": "BENEFICIARY",
    "id": "7c1a3e88-9d2b-4f61-8a44-1f0b6d3c9a55"
  }
}

The address ignores every deposit until you allow at least one sender. The same value appears as autoWithdrawalAddress on the Beneficiary object.

List allowed senders

Returns the senders allowed to trigger this beneficiary's address, oldest first.

Success response (200)

[
  {
    "id": "3f8c1d02-5b47-4a6e-91cd-77e2b0a4f915",
    "address": "0x9a3f7c21b8e04d6f5a19c2e70b48d3f61a5e9d02",
    "label": "Treasury wallet",
    "active": true,
    "createdAt": "2026-08-07T09:31:05.000Z"
  }
]

Disabled senders are listed too. They count toward the 50-sender limit until you remove them.

404 NOT_FOUND if the beneficiary has no trigger address yet.

Allow a sender

Allows one address to trigger payouts to this beneficiary. Up to 50 per address.

Success response (201)

Returns the created sender in the same shape as List allowed senders.

Disable or re-enable a sender

Turns a sender off without losing it. A disabled sender stops triggering transfers immediately, keeps its label, and stays in the list ready to be turned back on. Use this to pause a wallet you expect to send from again; use remove when you are done with it, which is also what frees its place against the 50-sender limit.

Request body

Success response (200)

Returns the sender in the same shape as List allowed senders.

Remove an allowed sender

Stops accepting deposits from that sender and frees its place against the 50-sender limit. Deposits already on their way are unaffected. Sign @method and @path only; no Content-Digest is required.

Success response (200)

{ "success": true }

404 NOT_FOUND if the sender id is unknown or belongs to a different address.

Get a deposit

Returns a deposit to a beneficiary's trigger address and the transfer it produced. This is the same payload the deposit webhook delivers.

A deposit is readable on the channel that produced it. Deposits paid into your own bank account are read with GET /v1/wallet/deposits/{id}.

Success response (200)

{
  "id": "5e9d0273-8a41-4c62-b0f7-1d3e8c95a460",
  "txHash": "0x5d5355...103ee3",
  "logIndex": 12,
  "chainId": 1,
  "tokenId": "a71c4e08-2f96-4b3d-85ae-6c0f7d21b943",
  "amount": "100000",
  "from": "0x9a3f7c21b8e04d6f5a19c2e70b48d3f61a5e9d02",
  "status": "COMPLETED",
  "confirmations": 24,
  "triggerAddress": "0x7c1a3e889d2b4f618a441f0b6d3c9a5588ab01cd",
  "destination": {
    "type": "BENEFICIARY",
    "id": "7c1a3e88-9d2b-4f61-8a44-1f0b6d3c9a55",
    "name": "ADA LOVELACE"
  },
  "result": {
    "status": "COMPLETED",
    "statusReason": null,
    "withdrawal": {
      "id": "c4a80f13-6d29-4e75-83b1-9f0c2a7e5d68",
      "amount": "100000",
      "status": "COMPLETED",
      "refId": "FW-20260807-0001",
      "reference": "Invoice 4471",
      "createdAt": "2026-08-07T09:31:05.000Z",
      "updatedAt": "2026-08-07T09:34:22.000Z"
    }
  },
  "createdAt": "2026-08-07T09:30:44.000Z",
  "updatedAt": "2026-08-07T09:34:22.000Z"
}

amount and result.withdrawal.amount use different units — the token's smallest unit and sen. Read each from its own field.

A transfer produced this way does not appear in GET /v1/payouts and does not use your prefund balance.

404 NOT_FOUND for an unknown deposit id, one belonging to another account, or one paid into your own bank account.

Deposit status reason values

result.statusReason is null unless result.status is FAILED. These are distinct from the payout status reason values, which describe a payout you created.

Deposits from before this vocabulary settled may still read inactive_beneficiary or missing_beneficiary_bank_details — the older names for inactive_destination and missing_destination_bank_details.

The tokens stay credited to your wallet in every case. Where the cause is yours to fix, fix it and retry the deposit.

Check for a missed deposit

Asks BLOX to look at a transaction it never picked up. Use it when you sent tokens to a beneficiary's address and nothing arrived.

This is the only endpoint that takes a transaction hash. When the transaction turns out to be known already, the response carries the deposit ids — use those with Get a deposit and Retry a deposit. Limited to 30 calls per minute.

Success response (201)

{
  "status": "ALREADY_DETECTED",
  "depositIds": ["5e9d0273-8a41-4c62-b0f7-1d3e8c95a460"]
}

Check status before reading depositIds: an empty array on QUEUED means the deposits do not exist yet, not that none were found. One transaction can pay several beneficiaries. On QUEUED, wait for the webhook rather than calling again.

Retry a deposit

Re-evaluates a deposit that was credited but produced no transfer. Use it after fixing the cause — allowing the sender, reactivating the beneficiary, or waiting for a limit to roll over.

Safe to call more than once. A deposit that already paid out returns its existing transfer, and no second transfer is created. Limited to 60 calls per minute.

No request body. Sign @method and @path only.

Success response (201)

The deposit, in the same shape as Get a deposit, read back after the retry.

Shared response schemas

Beneficiary object

Payout object

Exactly one of beneficiaryId and bankAccountId is ever set. Everything you create is STANDARD, with a beneficiary.

The create response always has submittedAt: null; read the payout later if you need the submission time. INITIATED covers both queued and bank-pending payouts, and submittedAt distinguishes them.

Status reason values

Branch on these stable keys, never on human-readable messages. The REST record and Webhook Events use the same values.