Skip to content
LogoLogo

Sandbox Testing

Use sandbox to verify checkout creation, customer redirect, status handling, and webhook reconciliation before using production credentials.

Base URL

https://api.sandbox.blox.my

Sandbox and production use different credentials and token IDs. Resolve tokenId from GET /v1/wallet/networks in each environment rather than hard-coding it.

Before testing

Prepare:

  • A sandbox API key with Onramp enabled
  • Each checkout type you plan to test enabled separately — holding one never grants another
  • A funded checkout prefund balance if you are testing CHARGE_TO_PREFUND
  • A registered signer public key and the matching private key
  • A destination EVM or Solana address you control
  • A CHECKOUT webhook endpoint under Devtools → Webhooks

Blox-account checkout test

  1. Resolve an MYRC tokenId whose network matches addressTo.
  2. Send POST /v1/checkout with "type": "BLOX_ACCOUNT" and a persisted Idempotency-Key.
  3. Store checkoutId and open the complete checkoutUrl, including its query string.
  4. Sign in with a sandbox Blox account and complete payment.
  5. Expect the checkout to progress through CREATED, PENDING, and PROCESSING to COMPLETED.
  6. Confirm checkout.updated, then reconcile with GET /v1/checkout/{id}.

For BLOX_ACCOUNT, fee is "0" and netAmount equals amount. Sending feeMode should return 400.

Hosted FPX checkout test

  1. Send POST /v1/checkout with "type": "FPX_HOSTED" and feeMode, and no bank fields.
  2. Confirm the checkout is CREATED — no FPX bill exists yet, which is the difference from direct.
  3. Open the returned checkoutUrl; the BLOX page should render a bank picker.
  4. Pick a bank and submit; the checkout should move to PENDING and hand off to the sandbox FPX session.
  5. Verify the same status and webhook flow as above.

Direct FPX checkout test

  1. Fetch GET /v1/checkout/banks.
  2. Select an active bank and pass its code and type as bank and bankType.
  3. Send POST /v1/checkout with "type": "FPX_DIRECT", buyerName, and feeMode.
  4. Confirm the checkout is already PENDING — the bill was created with the link.
  5. Open the returned checkoutUrl and complete the sandbox FPX session.

Test both fee modes on either FPX type if BLOX has configured a checkout fee on your sandbox account:

  • DEDUCT_FROM_AMOUNT: confirm netAmount is the amount settled after the fee.
  • CHARGE_TO_PREFUND: confirm your checkout prefund drops by the fee at creation, netAmount stays the full amount, and letting the link expire returns the fee to the prefund.
  • CHARGE_TO_PREFUND with an empty prefund: confirm the create call returns 400 INSUFFICIENT_BALANCE and that no checkout was created.

Expiration and cancellation

  • Leave a checkout unpaid for 20 minutes; it should become FAILED and emit checkout.updated.
  • Cancel from the checkout page; it should become CANCELLED without a webhook, so confirm it through the read endpoint.
  • Always stop fulfillment unless the authoritative checkout status is COMPLETED.

Production switch

Before going live:

  1. Change the base URL to https://api.blox.my and use production credentials.
  2. Resolve the production tokenId again.
  3. Register the production webhook URL and secret.
  4. Confirm access for each checkout type you use, plus fees and limits, with BLOX.
  5. Fund the production checkout prefund if you use CHARGE_TO_PREFUND.