Payout API Reference

This page shows all Payout API endpoints in the order of integration. Use https://api.sandbox.blox.my for tests. Use https://api.blox.my in production.

Read requests must include the blox-api-key header. Write requests must include the API key and an HTTP message signature. Some write requests must also include an Idempotency-Key UUID v4. The section for each endpoint tells you if it is necessary.

All errors use the format { "code": "…", "message": "…", "requestId": "…" }. Use the code value in your error logic. Do not use the message value. The tables under each endpoint show the expected combinations of status and code.

To pay a beneficiary from a deposit of tokens to its trigger address, refer to Onchain Trigger.

Get prefund balance

Returns the prefund balance. This endpoint has no parameters. The limit is 60 requests per minute for each account.

Response — 200

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

The available value does not include inFlight. Do not subtract inFlight from available. If receivable is negative, the payout endpoints return 403 FEATURE_DISABLED until the negative amount is resolved. To get top-up notifications, use the payout.prefund_completed webhook event. Do not poll this endpoint 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. Each item has the bank code that beneficiary and payout requests accept. The limit is 600 requests per minute for each account.

Response — 200

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

Use this bankCode value in all request fields with the name bankCode.

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

Create beneficiary

Registers a beneficiary that you can use for more than one payout. Requests to this endpoint must include an Idempotency-Key UUID v4. The limit is 20 requests per minute for each account.

Identify the beneficiary in one of two ways: a bank account or a DuitNow proxy. Send the fields for one of the two types only. Do not send fields that are not in the table for that type.

A bank account:

A DuitNow proxy: an identifier that the beneficiary registered with PayNet. At payment time, PayNet finds the account for the identifier. PayNet also supplies the bank at that time. Thus, you register a proxy with only the identifier.

Send the identifier as the beneficiary registered it with PayNet. Remove all hyphens, spaces, and punctuation. For PayNet, 900101-01-5432 and 900101015432 are two different proxies. PayNet finds an account only for 900101015432.

DuitNow proxies are not available on all accounts. If your account does not support proxies, a proxy beneficiary gets 400 UNKNOWN_BENEFICIARY. Ask BLOX if your account supports proxies.

BLOX asks the bank if the account exists. If the bank does not recognize the account, the response is 400 INVALID_REQUEST. If BLOX cannot connect to the bank, the response is 503 SERVICE_UNAVAILABLE. In that case, BLOX does not register the beneficiary.

Name check. You can send nameCheck in this request or in the inline beneficiary object of a payout. To check a registered beneficiary, use Verify beneficiary. If you send nameCheck, BLOX compares the name that you send with the name of the account holder:

Sometimes the bank cannot give a result for the name. For example, the bank does not support the name check, or the bank does not return a holder name. In this case, a request with nameCheck fails with 400 NAME_CHECK_UNAVAILABLE. To register the beneficiary without verification, send the request again without nameCheck. Use a new Idempotency-Key.

Example of a bank beneficiary with a name check:

{ "name": "Ada Lovelace", "bankCode": "MBBM", "accountNumber": "1234567890", "nameCheck": "loose" }

Result for each bank response:

BLOX does not return the holder name from the bank. If a name fails at strict but passes at loose, send the request again with a new Idempotency-Key. In that request, send the full name of the beneficiary as it is on the IC, or send nameCheck: "loose".

Result of a 400 response:

• Registration: BLOX does not register the beneficiary.
• Verify beneficiary: bankAccountVerified does not change. You can still pay the beneficiary.
• A payout with an inline beneficiary: BLOX rejects the payout and does not debit the prefund balance.

BLOX removes spaces at the start and end of the name and changes the name to uppercase. If you register the same destination with the same name again, BLOX returns the existing beneficiary. The name comparison is not case-sensitive. BLOX does not ask the bank again, except for a nameCheck at a level that the beneficiary did not pass before. A repeat registration does not count toward the limit of active beneficiaries. The default limit is 10,000.

Response — 200

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

For a DuitNow proxy beneficiary, the response has proxy set, and accountNumber and bank are null:

{
  "id": "0b9d7c21-4e83-4a17-9f52-6c8e1a2d3b40",
  "name": "ADA LOVELACE",
  "accountNumber": null,
  "bank": null,
  "proxy": { "type": "MBNO", "value": "60123456789", "countryCode": null },
  "autoWithdrawalAddress": null,
  "bankAccountVerified": true,
  "bankAccountVerifiedAt": "2026-07-16T09:30:00.000Z",
  "bankAccountNameMatch": "strict",
  "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"
}

{
  "code": "INVALID_REQUEST",
  "message": "Beneficiary rejected by the bank — the account may be invalid, dormant, closed, or blocked",
  "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": "BENEFICIARY_NAME_MISMATCH",
  "message": "Beneficiary name did not match under strict comparison, but would under loose. Use the full name exactly as registered with the bank, or retry with nameCheck \"loose\".",
  "requestId": "9f21ab04-6c3e-4d90-b1a7-8e5f2c0d4416"
}

{
  "code": "BENEFICIARY_NAME_MISMATCH",
  "message": "Beneficiary name does not match the bank's records. Use the name exactly as registered with the bank.",
  "requestId": "9f21ab04-6c3e-4d90-b1a7-8e5f2c0d4416"
}

{
  "code": "NAME_CHECK_UNAVAILABLE",
  "message": "The bank did not return a holder name for this account, so the name cannot be checked. Retry without nameCheck to register the beneficiary unverified.",
  "requestId": "9f21ab04-6c3e-4d90-b1a7-8e5f2c0d4416"
}

{
  "code": "UNKNOWN_BENEFICIARY",
  "message": "Unknown bank code",
  "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_TERMINATED",
  "message": "Account is terminated",
  "requestId": "9f21ab04-6c3e-4d90-b1a7-8e5f2c0d4416"
}

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

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

{
  "code": "SERVICE_UNAVAILABLE",
  "message": "Could not verify the beneficiary with the bank right now. Nothing was submitted — please retry shortly.",
  "requestId": "9f21ab04-6c3e-4d90-b1a7-8e5f2c0d4416"
}

List beneficiaries

Returns the active beneficiaries. The newest beneficiary is first.

Response — 200

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

Each data item is a Beneficiary object. To get the next page, send nextCursor as cursor. Do this until hasMore is false. On the last page, nextCursor is null.

{
  "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. If the ID is unknown, inactive, or belongs to a different account, the response is 404 NOT_FOUND.

Response — 200: Beneficiary object.

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

Delete beneficiary

Deactivates the beneficiary and its trigger address, if it has one. Sign only @method and @path. A Content-Digest is not necessary.

Response — 200

{ "success": true }

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

Verify beneficiary

Checks the holder name of a registered beneficiary again, at the level that you select. The limit is 20 requests per minute for each account.

Returns the Beneficiary object. If the response is BENEFICIARY_NAME_MISMATCH, the verified status of the beneficiary does not change. You can still pay the beneficiary.

Response — 200

The Beneficiary object. The bankAccountVerified, bankAccountVerifiedAt, and bankAccountNameMatch fields show the result of this check.

{
  "code": "VALIDATION_FAILED",
  "message": "nameCheck: Required",
  "requestId": "9f21ab04-6c3e-4d90-b1a7-8e5f2c0d4416"
}

{
  "code": "INVALID_REQUEST",
  "message": "Beneficiary rejected by the bank — the account may be invalid, dormant, closed, or blocked",
  "requestId": "9f21ab04-6c3e-4d90-b1a7-8e5f2c0d4416"
}

{
  "code": "BENEFICIARY_NAME_MISMATCH",
  "message": "Beneficiary name did not match under strict comparison, but would under loose. Use the full name exactly as registered with the bank, or retry with nameCheck \"loose\".",
  "requestId": "9f21ab04-6c3e-4d90-b1a7-8e5f2c0d4416"
}

{
  "code": "BENEFICIARY_NAME_MISMATCH",
  "message": "Beneficiary name does not match the bank's records. Use the name exactly as registered with the bank.",
  "requestId": "9f21ab04-6c3e-4d90-b1a7-8e5f2c0d4416"
}

{
  "code": "NAME_CHECK_UNAVAILABLE",
  "message": "The bank did not return a holder name for this account, so the name cannot be checked. Retry without nameCheck to register the beneficiary unverified.",
  "requestId": "9f21ab04-6c3e-4d90-b1a7-8e5f2c0d4416"
}

{
  "code": "UNAUTHORIZED",
  "message": "API key is required",
  "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_TERMINATED",
  "message": "Account is terminated",
  "requestId": "9f21ab04-6c3e-4d90-b1a7-8e5f2c0d4416"
}

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

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

{
  "code": "SERVICE_UNAVAILABLE",
  "message": "Could not verify the beneficiary with the bank right now. Nothing was submitted — please retry shortly.",
  "requestId": "9f21ab04-6c3e-4d90-b1a7-8e5f2c0d4416"
}

Create payout

Creates a payout and submits it. A separate submit request is not necessary. BLOX debits an accepted payout from available. The response shows the payout with the status INITIATED. The limit is 300 requests per minute for each account.

Header

Body

With DEDUCT_FROM_AMOUNT, the beneficiary gets amount - fee. With CHARGE_TO_PREFUND, the beneficiary gets the full amount. In the two modes, BLOX debits netAmount + fee from the prefund balance. Get the two values from the response.

amount is the gross value before the fee. With DEDUCT_FROM_AMOUNT, netAmount must be RM1.00 or more. The standard minimum fee is RM1.50. Thus, the smallest gross amount that you can send is RM2.50.

The first payout to an inline beneficiary registers that beneficiary. BLOX asks the bank if the account exists, as POST /v1/payouts/beneficiaries does. If you send the same bank, account number, and name again, the payout uses the same beneficiaryId. The name comparison is not case-sensitive.

For a payout to that beneficiaryId, BLOX does not ask the bank again. The exception is a nameCheck at a level that the beneficiary did not pass before. BLOX checks the name only if you send nameCheck. If a check fails, the payout fails (400 INVALID_REQUEST, 400 BENEFICIARY_NAME_MISMATCH, 400 NAME_CHECK_UNAVAILABLE, or 503). BLOX does not debit the prefund balance.

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 tells you that the first request with that key is in progress. Retry with the same key.

Idempotency rules

• Store one UUID v4 for each payout before you send the request.
• If the request times out or returns 429, 500, or 503, retry with the same key.
• If BLOX rejects the request with a different 4xx, correct the request. Then send it with a new key.
• If you use a key again with a different body, the response is 422 CONFLICT.

Refer to Payout Errors for all codes and retry rules.

{
  "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": "INVALID_REQUEST",
  "message": "Beneficiary rejected by the bank — the account may be invalid, dormant, closed, or blocked",
  "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": "BENEFICIARY_NAME_MISMATCH",
  "message": "Beneficiary name does not match the bank's records. Use the name exactly as registered with the bank.",
  "requestId": "9f21ab04-6c3e-4d90-b1a7-8e5f2c0d4416"
}

{
  "code": "NAME_CHECK_UNAVAILABLE",
  "message": "The bank did not return a holder name for this account, so the name cannot be checked. Retry without nameCheck to register the beneficiary unverified.",
  "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": "CONFLICT",
  "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"
}

{
  "code": "SERVICE_UNAVAILABLE",
  "message": "Could not verify the beneficiary with the bank right now. Nothing was submitted — please retry shortly.",
  "requestId": "9f21ab04-6c3e-4d90-b1a7-8e5f2c0d4416"
}

Get payout

Returns the payout with the given payoutId. To get status changes, use webhook events. Use this endpoint for reconciliation, or if you did not receive a webhook event. The limit is 600 requests per minute for each account.

Response — 200: Payout object. If the ID is unknown or belongs to a different account, the response is 404 NOT_FOUND.

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

Shared response schemas

Beneficiary object

Meaning of bankAccountVerified and bankAccountNameMatch together:

After bankAccountVerified changes to true, it stays true. If a later Verify beneficiary request returns 400, the value does not change.

Each beneficiary has bank and accountNumber set, or proxy set. The fields that are not set are null. The response always includes all of these keys. To find the type of beneficiary, check if proxy is null.

Payout object

Each payout has beneficiaryId or bankAccountId set, but not the two. All payouts that you create are STANDARD and have a beneficiary.

The create response always has submittedAt: null. To get the submission time, get the payout later. An INITIATED payout with submittedAt: null is not at the bank yet. An INITIATED payout with a submittedAt value is at the bank and has no final result yet.

Status reason values

Use these keys in your logic. Do not use human-readable messages. The REST response and Webhook Events use the same values.