Skip to main content
GET
/
v1
/
order
/
{orderId}
Get Order Status
curl --request GET \
  --url https://api.example.com/v1/order/{orderId} \
  --header 'Authorization: <authorization>' \
  --header 'X-Client-ID: <x-client-id>'
{
  "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

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.
ValueDescription
STARTEDOrder created; payment not yet confirmed. Continue polling.
COMPLETEDPayment received and order fulfilled successfully.
FAILEDPayment failed or was rejected. Check metadata.note for context.
EXPIREDOrder 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.

​
Error Responses

The bearer token is missing, expired, or invalid.
The authenticated user does not have permission to access this order.
No order exists with the given orderId. Verify the ID matches one returned by POST /v1/order.
{
  "error": "Order not found"
}
The X-Client-ID header value is not recognised.
The X-Client-ID header is absent from the request.
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);
}

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.