Checkout Status

Query the status of a single checkout or list all checkouts for your account.

Get Single Checkout

Retrieve details for a specific checkout by ID.


GET /v1/checkout/:id

Authentication

This endpoint requires API Key only (no signature required for GET requests).

Header	Required	Description
`blox-api-key`	Yes	Your API key

Path Parameters

Parameter	Type	Description
`id`	string (UUID)	The checkout ID

Example Request


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

Response


{
  "id": "8f14e45f-ceea-467f-a830-5e3e3c7e2b8a",
  "version": 1,
  "addressTo": "0x742d35Cc6634C0532925a3b844Bc9e7595f8bD21",
  "amount": "15000",
  "fee": "0",
  "status": "COMPLETED",
  "metadata": {
    "title": "Order #123",
    "description": "Premium subscription - 1 month",
    "redirectUrl": "https://yoursite.com/success",
    "webhookUrl": "https://yoursite.com/webhooks/blox"
  },
  "expiresAt": "2026-02-03T15:20:00.000Z",
  "token": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "MYRC",
    "symbol": "MYRC"
  },
  "tokenWithdrawal": {
    "id": "withdrawal-uuid-here",
    "status": "COMPLETED",
    "transaction": {
      "txHash": "0xabc123def456...",
      "confirmedAt": "2026-02-03T15:05:30.000Z"
    }
  },
  "createdAt": "2026-02-03T15:00:00.000Z",
  "updatedAt": "2026-02-03T15:05:30.000Z"
}

Response Fields

Field	Type	Description
`id`	string	Unique checkout identifier
`addressTo`	string	Merchant’s wallet address
`amount`	string	Payment amount in cents
`fee`	string	Transaction fee in cents
`status`	string	Current checkout status
`metadata`	object	Title, description, URLs
`expiresAt`	string	Checkout expiration timestamp
`token`	object	Token details (id, name, symbol)
`tokenWithdrawal`	object	Transaction details (if payment completed)
`createdAt`	string	Checkout creation timestamp
`updatedAt`	string	Last update timestamp

List All Checkouts

Query all checkouts for your account with pagination and filtering.


GET /v1/checkout

Authentication

This endpoint requires API Key only (no signature required for GET requests).

Query Parameters

Parameter	Type	Required	Description
`skip`	integer	No	Number of records to skip (default: 0)
`take`	integer	No	Number of records to return (default: 20, max: 100)
`status`	string	No	Filter by status
`startDt`	string (ISO 8601)	No	Filter by creation date (from)
`endDt`	string (ISO 8601)	No	Filter by creation date (to)

Status Filter Values

Status	Description
`CREATED`	Checkout created, awaiting customer
`PENDING`	Customer selected wallet, ready to pay
`PROCESSING`	Payment initiated, waiting for confirmation
`COMPLETED`	Payment successful
`FAILED`	Payment failed
`CANCELLED`	Checkout cancelled

Example Request


# Get recent checkouts
curl "https://api.blox.my/v1/checkout?take=10" \
  -H "blox-api-key: $BLOX_API_KEY"
 
# Filter by status
curl "https://api.blox.my/v1/checkout?status=COMPLETED&take=50" \
  -H "blox-api-key: $BLOX_API_KEY"
 
# Filter by date range
curl "https://api.blox.my/v1/checkout?startDt=2026-01-01T00:00:00Z&endDt=2026-01-31T23:59:59Z" \
  -H "blox-api-key: $BLOX_API_KEY"

Response


{
  "data": [
    {
      "id": "8f14e45f-ceea-467f-a830-5e3e3c7e2b8a",
      "addressTo": "0x742d35Cc...",
      "amount": "15000",
      "fee": "0",
      "status": "COMPLETED",
      "metadata": {
        "title": "Order #123",
        "redirectUrl": "https://yoursite.com/success"
      },
      "expiresAt": "2026-02-03T15:20:00.000Z",
      "token": {
        "id": "550e8400-...",
        "name": "MYRC",
        "symbol": "MYRC"
      },
      "tokenWithdrawal": {
        "id": "withdrawal-uuid",
        "status": "COMPLETED"
      },
      "createdAt": "2026-02-03T15:00:00.000Z"
    },
    {
      "id": "another-checkout-id",
      "addressTo": "0x742d35Cc...",
      "amount": "5000",
      "fee": "0",
      "status": "PENDING",
      "metadata": {
        "title": "Order #124",
        "redirectUrl": "https://yoursite.com/success"
      },
      "expiresAt": "2026-02-03T16:00:00.000Z",
      "token": {
        "id": "550e8400-...",
        "name": "MYRC",
        "symbol": "MYRC"
      },
      "tokenWithdrawal": null,
      "createdAt": "2026-02-03T15:40:00.000Z"
    }
  ],
  "total": 42,
  "skip": 0,
  "take": 10
}

Response Fields

Field	Type	Description
`data`	array	List of checkout objects
`total`	integer	Total number of matching checkouts
`skip`	integer	Number of records skipped
`take`	integer	Number of records returned

Status Lifecycle

Checkouts progress through these statuses:


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

Status Descriptions

Status	Description	Next States
`CREATED`	Checkout link generated, customer hasn’t started	PENDING, CANCELLED
`PENDING`	Customer authenticated and selected wallet	PROCESSING, CANCELLED
`PROCESSING`	Payment submitted, waiting for blockchain confirmation	COMPLETED, FAILED
`COMPLETED`	Payment successful, funds transferred to merchant	(Final)
`FAILED`	Payment failed (insufficient balance, network error, etc.)	(Final)
`CANCELLED`	Cancelled by customer, timeout, or merchant	(Final)

Automatic Cancellation

Checkouts are automatically cancelled if:

The customer doesn’t complete payment within 20 minutes
The checkout link expires before the customer starts

Errors

404 Not Found

Checkout doesn’t exist or doesn’t belong to your account:


{
  "error": {
    "code": "not_found",
    "message": "Checkout not found"
  }
}

Code Examples

Node.js


async function getCheckout(apiKey: string, checkoutId: string) {
  const response = await fetch(
    `https://api.blox.my/v1/checkout/${checkoutId}`,
    {
      headers: {
        "blox-api-key": apiKey,
      },
    }
  );
  
  return response.json();
}
 
async function listCheckouts(
  apiKey: string,
  options?: {
    skip?: number;
    take?: number;
    status?: string;
    startDt?: string;
    endDt?: string;
  }
) {
  const params = new URLSearchParams();
  if (options?.skip) params.set("skip", options.skip.toString());
  if (options?.take) params.set("take", options.take.toString());
  if (options?.status) params.set("status", options.status);
  if (options?.startDt) params.set("startDt", options.startDt);
  if (options?.endDt) params.set("endDt", options.endDt);
  
  const response = await fetch(
    `https://api.blox.my/v1/checkout?${params.toString()}`,
    {
      headers: {
        "blox-api-key": apiKey,
      },
    }
  );
  
  return response.json();
}
 
// Usage
const checkout = await getCheckout(apiKey, "8f14e45f-ceea-467f-a830-5e3e3c7e2b8a");
console.log("Status:", checkout.status);
 
const completedCheckouts = await listCheckouts(apiKey, {
  status: "COMPLETED",
  take: 50,
});
console.log("Completed:", completedCheckouts.total);

Python


import requests
 
def get_checkout(api_key: str, checkout_id: str):
    response = requests.get(
        f"https://api.blox.my/v1/checkout/{checkout_id}",
        headers={"blox-api-key": api_key},
    )
    return response.json()
 
def list_checkouts(api_key: str, **kwargs):
    params = {k: v for k, v in kwargs.items() if v is not None}
    response = requests.get(
        "https://api.blox.my/v1/checkout",
        headers={"blox-api-key": api_key},
        params=params,
    )
    return response.json()
 
# Usage
checkout = get_checkout(api_key, "8f14e45f-ceea-467f-a830-5e3e3c7e2b8a")
print("Status:", checkout["status"])
 
completed = list_checkouts(api_key, status="COMPLETED", take=50)
print("Completed:", completed["total"])

Polling vs Webhooks

For real-time status updates, we recommend using webhooks instead of polling.

Approach	Pros	Cons
Polling	Simple to implement	Delayed updates, more API calls
Webhooks	Real-time, efficient	Requires public endpoint

If you must poll, we recommend:

Poll every 5 seconds for PROCESSING checkouts
Stop polling after status is COMPLETED, FAILED, or CANCELLED
Implement exponential backoff for rate limit errors