Get Order Status

Fetch the current status of an order by ID. Use this to poll for async completion after a payment is submitted.

GET /v1/order/{orderId}

Get Order Status

cURL

curl --request GET \
  --url https://api.example.com/v1/order/{orderId} \
  --header 'Authorization: <authorization>' \
  --header 'X-Client-ID: <x-client-id>'

200

{
  "requestId": "<string>",
  "orderId": "<string>",
  "status": {},
  "paidAt": "<string>",
  "metadata": {
    "metadata.paymentId": "<string>",
    "metadata.txHash": "<string>",
    "metadata.note": "<string>"
  }
}

Overview

After creating an order with POST /v1/order and directing the user through an external payment flow, use this endpoint to poll for the outcome. The order status will progress from STARTED to one of the terminal states: COMPLETED, FAILED, or EXPIRED.

Request

Headers

Authorization · string · required

Bearer token for the authenticated user. Format: Bearer <userAccessToken>

X-Client-ID · string · required

Your application’s client ID, issued during onboarding.

Path Parameters

orderId · string · required

The unique ID of a previously created order, as returned by POST /v1/order. Example: "abcd_1234"

Example Request

Node.js

const response = await fetch(`https://api.baanx.com/v1/order/${orderId}`, {
  headers: {
    'X-Client-ID': 'your_client_id',
    'Authorization': `Bearer ${userAccessToken}`
  }
});

const order = await response.json();
console.log(order.status); // e.g. "COMPLETED"

Response

200 — Success

{
  "requestId": "payment_1234",
  "orderId": "abcd_1234",
  "status": "COMPLETED",
  "paidAt": "2023-03-27 17:07:12.662+03",
  "metadata": {
    "paymentId": "abcpaymentId1234ABC",
    "txHash": "0x3a11a86cf218c448be519728cd3ac5c741fb3424",
    "note": "payment_refunded"
  }
}

requestId · string

The payment request identifier, correlating this order to a payment gateway transaction. Example: "payment_1234"

orderId · string · required

The unique identifier of the order.

status · enum · required

The current state of the order.

Value	Description
STARTED	Order created; payment not yet confirmed. Continue polling.
COMPLETED	Payment received and order fulfilled successfully.
FAILED	Payment failed or was rejected. Check metadata.note for context.
EXPIRED	Order was not paid within the allowed time window.

paidAt · string

Timestamp of when payment was confirmed. Only present when status is COMPLETED.

metadata · object

Additional context about the payment outcome. Individual fields may be absent depending on the result.

Show metadata fields

metadata.paymentId · string

The identifier assigned to the payment by the payment gateway.

metadata.txHash · string

The on-chain transaction hash for the crypto payment.

metadata.note · string

A short note providing context in failure cases, if available. Example: "payment_refunded"

Error Responses

401 — Authentication Error

The bearer token is missing, expired, or invalid.

403 — Authorization Error

The authenticated user does not have permission to access this order.

404 — Order Not Found

No order exists with the given orderId. Verify the ID matches one returned by POST /v1/order.

{
  "error": "Order not found"
}

498 — Invalid Client Key

The X-Client-ID header value is not recognised.

499 — Missing Client Key

The X-Client-ID header is absent from the request.

500 — Internal Server Error

An unexpected server error occurred. Retry with exponential backoff.

Polling Pattern

Order completion is asynchronous. Poll this endpoint after the user completes the external payment step, stopping when status reaches a terminal value (COMPLETED, FAILED, or EXPIRED).

async function waitForOrderCompletion(orderId, clientId, accessToken) {
  const TERMINAL_STATES = ['COMPLETED', 'FAILED', 'EXPIRED'];
  const MAX_ATTEMPTS = 40; // ~2 minutes at 3s intervals
  const POLL_INTERVAL_MS = 3000;

  for (let i = 0; i < MAX_ATTEMPTS; i++) {
    const response = await fetch(`https://api.baanx.com/v1/order/${orderId}`, {
      headers: {
        'X-Client-ID': clientId,
        'Authorization': `Bearer ${accessToken}`
      }
    });

    if (!response.ok) throw new Error(`Unexpected error: ${response.status}`);

    const order = await response.json();

    if (TERMINAL_STATES.includes(order.status)) return order;

    await new Promise(resolve => setTimeout(resolve, POLL_INTERVAL_MS));
  }

  throw new Error('Order polling timed out. Please check back later.');
}

const order = await waitForOrderCompletion(orderId, clientId, accessToken);

if (order.status === 'COMPLETED') {
  // Unlock product, show success UI
} else {
  // Handle failure or expiry
  console.warn('Order did not complete:', order.metadata?.note);
}

Related Endpoints

Create Order

Initiate a new order and receive the orderId to track here.

Get Available Products

Discover which products are available and eligible before ordering.