Checkout API

The Checkout API enables merchants to create secure payment links that customers can use to pay directly from their BLOX wallet. It works like a payment gateway — you generate a link, send it to your customer, and receive funds when they complete the payment.

Endpoints

Create Checkout

Generate a new payment link for your customer

Checkout Status

Query checkout status and transaction details

Webhooks

Receive real-time payment status notifications

How It Works


1. Create Checkout → 2. Send Link to Customer → 3. Customer Pays → 4. Receive Webhook

Flow Diagram


┌─────────────────┐         ┌─────────────────┐         ┌─────────────────┐
│  Your Server    │         │    BLOX API     │         │    Customer     │
└────────┬────────┘         └────────┬────────┘         └────────┬────────┘
         │                           │                           │
         │  POST /v1/checkout        │                           │
         │─────────────────────────> │                           │
         │                           │                           │
         │  { checkoutUrl, ... }     │                           │
         │ <─────────────────────────│                           │
         │                           │                           │
         │  Send checkoutUrl         │                           │
         │───────────────────────────────────────────────────────>
         │                           │                           │
         │                           │    Opens checkout link    │
         │                           │ <─────────────────────────│
         │                           │                           │
         │                           │    Signs in + Pays        │
         │                           │ <─────────────────────────│
         │                           │                           │
         │  Webhook: COMPLETED       │                           │
         │ <─────────────────────────│                           │
         │                           │                           │
         │                           │    Redirects to your site │
         │                           │ ─────────────────────────>│
         │                           │                           │

Quick Example

Create a Checkout


curl -X POST "https://api.blox.my/v1/checkout" \
  -H "blox-api-key: $BLOX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Content-Digest: sha-256=:$CONTENT_DIGEST:" \
  -H "Signature-Input: sig1=(@method @path content-digest content-type);created=$TIMESTAMP;keyid=\"$KEY_ID\";alg=\"ed25519\"" \
  -H "Signature: sig1=:$SIGNATURE:" \
  -d '{
    "addressTo": "0x742d35Cc6634C0532925a3b844Bc9e7595f8bD21",
    "amount": 15000,
    "tokenId": "550e8400-e29b-41d4-a716-446655440000",
    "redirectUrl": "https://yoursite.com/order/123/complete",
    "webhookUrl": "https://yoursite.com/webhooks/blox",
    "title": "Order #123"
  }'

Response:


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

Check Checkout Status


curl "https://api.blox.my/v1/checkout/8f14e45f-ceea-467f-a830-5e3e3c7e2b8a" \
  -H "blox-api-key: $BLOX_API_KEY"

Status Lifecycle

Checkouts progress through these statuses:


CREATED ──────► PENDING ──────► PROCESSING ──────► COMPLETED
    │               │                │
    │               │                ├──────────► FAILED
    │               │                │
    └───────────────┴────────────────┴──────────► CANCELLED

Status	Description
`CREATED`	Checkout link generated, awaiting customer
`PENDING`	Customer selected their wallet, ready to pay
`PROCESSING`	Payment initiated, waiting for confirmation
`COMPLETED`	Payment successful, funds transferred
`FAILED`	Payment failed (insufficient balance, network error)
`CANCELLED`	Customer or timeout cancelled the checkout

Note: Checkout links expire after 20 minutes. If the customer doesn’t complete payment within this window, the checkout is automatically cancelled.

Key Details

Property	Value
Amount Range	10.00 – 1,000,000.00 MYR
Amount Format	Cents (e.g., `15000` = 150.00 MYR)
Expiration	20 minutes from creation
Supported Tokens	MYRC (and other active tokens)
Supported Networks	Ethereum, Arbitrum, Solana

Authentication

All BLOX APIs use RFC 9421 HTTP Message Signatures for state-changing requests.

Request Type	Authentication Required
`POST /v1/checkout`	API Key + RFC 9421 Signature
`GET /v1/checkout`	API Key only
`GET /v1/checkout/:id`	API Key only

Learn about Request Signatures →

Prerequisites

Before using the Checkout API, ensure you have:

Business Account — Complete KYB verification
Checkout Feature — Enabled for your account (contact support)
API Key — Generated with a public/private key pair
Wallet Address — Ethereum or Solana address to receive funds
Token ID — The token you want to receive (e.g., MYRC)

Error Handling

Error	Description
`Checkout feature not enabled`	Contact support to enable checkout
`Token not available`	Invalid or inactive token ID
`Invalid signature`	Signature verification failed

View all error codes →