Onramp API Reference

All Onramp 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. Create requests require the API key, an HTTP message signature, and an Idempotency-Key UUID v4 persisted before the first request.

Every error uses { "code": "…", "message": "…", "requestId": "…" }. Branch on code, never message; see Onramp Errors for retry guidance.

Create checkout

Creates a checkout link of the type you name. The link expires after 20 minutes, and the endpoint is limited to 120 requests per minute per account.

Header

Body — every type

Additional fields by type

feeMode is DEDUCT_FROM_AMOUNT or CHARGE_TO_PREFUND. Sending it on a BLOX_ACCOUNT checkout is a 400, not an ignored field — that product has no MYR leg to charge against, and dropping it silently is how you end up believing a fee applies.

FPX_HOSTED does not take buyerName, bank, or bankType: the customer supplies them on the BLOX page, which is also when the FPX bill is created.

EVM addresses use 0x plus 40 hexadecimal characters; Solana addresses use Base58.

Response — 200

{
  "checkoutId": "8f14e45f-ceea-467f-a830-5e3e3c7e2b8a",
  "checkoutUrl": "https://checkout.blox.my/8f14e45f-ceea-467f-a830-5e3e3c7e2b8a?s=checkout_signature",
  "expiresAt": "2026-02-03T15:20:00.000Z"
}

Use the complete checkoutUrl, including its query string. Unpaid checkouts become FAILED after expiry. A 202 response means the original request for that key is still processing; sign a fresh request and retry with the same key.

Idempotency rules

• Persist one UUID v4 before sending a logical checkout.
• Retry 202 or 429 with the same key.
• Retry a rejected 400 or 422 with a new key after correcting the request.
• After a timeout or 5xx, reconcile by your unique title before retrying with the same key.
• Reusing a key with a different body returns 422 VALIDATION_FAILED.

See Onramp Errors for the complete code and retry table.

{
  "code": "INVALID_REQUEST",
  "message": "Missing idempotency key",
  "requestId": "9f21ab04-6c3e-4d90-b1a7-8e5f2c0d4416"
}

{
  "code": "VALIDATION_FAILED",
  "message": "title: Title is required",
  "requestId": "9f21ab04-6c3e-4d90-b1a7-8e5f2c0d4416"
}

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

{
  "code": "FEATURE_DISABLED",
  "message": "Merchant checkout feature not enabled: checkout_with_blox_account",
  "requestId": "9f21ab04-6c3e-4d90-b1a7-8e5f2c0d4416"
}

{
  "code": "ACCOUNT_TERMINATED",
  "message": "Your account has been terminated. Please contact support.",
  "requestId": "9f21ab04-6c3e-4d90-b1a7-8e5f2c0d4416"
}

{
  "code": "ACCOUNT_FROZEN",
  "message": "Your account has been frozen. Please contact support.",
  "requestId": "9f21ab04-6c3e-4d90-b1a7-8e5f2c0d4416"
}

{
  "code": "ACCOUNT_PENDING_VERIFICATION",
  "message": "Your account is pending verification. This action is not allowed for this account at this time.",
  "requestId": "9f21ab04-6c3e-4d90-b1a7-8e5f2c0d4416"
}

{
  "code": "ACCOUNT_SUSPENDED",
  "message": "Your account is suspended. Deposits are not allowed for this account.",
  "requestId": "9f21ab04-6c3e-4d90-b1a7-8e5f2c0d4416"
}

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

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

List checkout banks

Response — 200

{
  "banks": [
    {
      "code": "MBBEMYKL",
      "name": "Maybank",
      "displayName": "Maybank",
      "logoUrl": "https://…",
      "type": "01",
      "active": true
    }
  ]
}

Response is cached (~1 hour).

{
  "code": "INVALID_REQUEST",
  "message": "Failed to get banks",
  "requestId": "9f21ab04-6c3e-4d90-b1a7-8e5f2c0d4416"
}

Create checkout — direct FPX

The same POST /v1/checkout endpoint, with "type": "FPX_DIRECT" and a bank selected from GET /v1/checkout/banks. Shown separately because it is the only type that carries bank fields.

For "type": "FPX_HOSTED", send the body from Create checkout plus feeMode and omit buyerName, bank, and bankType — the customer supplies those on the BLOX page, which is also when the FPX bill is created.

Body

feeMode is required on both FPX types, and is decided per checkout rather than per account:

• DEDUCT_FROM_AMOUNT — your on-chain settlement is net of the fee.
• CHARGE_TO_PREFUND — settlement is gross; the fee comes out of your checkout prefund balance instead. It is reserved the moment the link is created, not when the buyer pays, and if the balance cannot cover it the create call returns 400 INSUFFICIENT_BALANCE and no link exists.

It is not defaulted because it decides what reaches your address. If your account has no fee configured, the mode has no effect but is still required.

Response — 200

{
  "checkoutId": "8f14e45f-ceea-467f-a830-5e3e3c7e2b8a",
  "checkoutUrl": "https://checkout.blox.my/fpx/8f14e45f-ceea-467f-a830-5e3e3c7e2b8a?s=checkout_signature",
  "expiresAt": "2026-02-03T15:20:00.000Z"
}

Use the complete checkoutUrl, including its query string. The link expires after 20 minutes. A 202 response means the original request for that key is still processing; sign a fresh request and retry with the same key.

The buyer details supplied on create (buyerName, bank, bankType) are not echoed by reads; store them against checkoutId. Handle Checkout webhook events and use GET /v1/checkout/{id} for reconciliation.

Idempotency rules

• Persist one UUID v4 before sending a logical checkout.
• Retry 202 or 429 with the same key.
• Retry a rejected 400 or 422 with a new key after correcting the request.
• After a timeout or 5xx, reconcile by your unique title before retrying with the same key.
• Reusing a key with a different body returns 422 VALIDATION_FAILED.

See Onramp Errors for the complete code and retry table.

{
  "code": "INVALID_REQUEST",
  "message": "Missing idempotency key",
  "requestId": "9f21ab04-6c3e-4d90-b1a7-8e5f2c0d4416"
}

{
  "code": "VALIDATION_FAILED",
  "message": "buyerName: Buyer name is required",
  "requestId": "9f21ab04-6c3e-4d90-b1a7-8e5f2c0d4416"
}

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

{
  "code": "FEATURE_DISABLED",
  "message": "Merchant checkout feature not enabled: checkout_direct",
  "requestId": "9f21ab04-6c3e-4d90-b1a7-8e5f2c0d4416"
}

{
  "code": "ACCOUNT_TERMINATED",
  "message": "Your account has been terminated. Please contact support.",
  "requestId": "9f21ab04-6c3e-4d90-b1a7-8e5f2c0d4416"
}

{
  "code": "ACCOUNT_FROZEN",
  "message": "Your account has been frozen. Please contact support.",
  "requestId": "9f21ab04-6c3e-4d90-b1a7-8e5f2c0d4416"
}

{
  "code": "ACCOUNT_PENDING_VERIFICATION",
  "message": "Your account is pending verification. This action is not allowed for this account at this time.",
  "requestId": "9f21ab04-6c3e-4d90-b1a7-8e5f2c0d4416"
}

{
  "code": "ACCOUNT_SUSPENDED",
  "message": "Your account is suspended. Deposits are not allowed for this account.",
  "requestId": "9f21ab04-6c3e-4d90-b1a7-8e5f2c0d4416"
}

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

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

Get checkout

Returns a checkout by checkoutId. Use webhooks for status changes; use this endpoint for reconciliation or missed webhook recovery.

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

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

List checkouts

Query all checkouts for your account with pagination and filtering.

Query parameters

Status filter values

Request example

Response — 200

Each row has the checkout object shape.

{
  "data": [
    {
      "checkoutId": "8f14e45f-ceea-467f-a830-5e3e3c7e2b8a",
      "status": "COMPLETED",
      "amount": "15000",
      "fee": "0",
      "netAmount": "15000",
      "addressTo": "0x742d35Cc...",
      "tokenId": "550e8400-...",
      "token": { "id": "550e8400-...", "name": "MYRC", "symbol": "MYRC" },
      "title": "Order #123",
      "description": null,
      "redirectUrl": "https://yoursite.com/success",
      "txHash": "0xabc123def456...",
      "paidAt": "2026-02-03T15:05:30.000Z",
      "expiresAt": "2026-02-03T15:20:00.000Z",
      "createdAt": "2026-02-03T15:00:00.000Z",
      "updatedAt": "2026-02-03T15:05:30.000Z"
    }
  ],
  "hasMore": true,
  "nextCursor": "8f14e45f-ceea-467f-a830-5e3e3c7e2b8a"
}

Response fields

The list is cursor paginated — iterate until hasMore is false. There is no total.

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

Shared response schema

Checkout object

See Fees for how feeMode, fee, and netAmount interact.

Reconcile checkout status

Use checkout webhooks as the primary signal. Read a checkout to reconcile a missed event or confirm a CANCELLED or REJECTED outcome, because those statuses do not emit checkout.updated.

If polling is required:

• Poll every 5 seconds while a checkout is PROCESSING.
• Stop at COMPLETED, FAILED, CANCELLED, or REJECTED.

The canonical status transitions and expiration rules are in Onramp lifecycle.