Skip to main content

​
Overview

Orders represent the commerce lifecycle (placed/shipped/delivered/cancelled). Use these endpoints for merchant dashboards and operational tooling.

​
Authentication

Requires x-commerce-api-key.

​
Request

​
List merchant orders

const orders = await pepay.commerce.orders.list({ limit: 10 });

​
Retrieve an order

const order = await pepay.commerce.orders.retrieve('order_123');

​
Cancel an order

await pepay.commerce.orders.cancel(
  'order_123',
  { refundDestinationWalletAddressBsc: '0x1111111111111111111111111111111111111111' },
  { idempotencyKey: '123e4567-e89b-42d3-a456-556642440000' }
);

​
Devnet order simulation (devnet only)

Use this to advance a devnet order through its lifecycle for integration testing and to trigger the same webhook + event stream updates you will receive in production. 
await pepay.commerce.devnet.simulateOrder('order_123', {
  transitionTo: 'payment_confirmed',
  walletNetwork: 'bsc',
  walletAddress: '0x0000000000000000000000000000000000000001'
});

​
How it works

  • Requires a devnet commerce API key and only operates on orders created in devnet.
  • Each simulation emits a commerce.order.updated merchant webhook event and a matching event on the commerce WebSocket stream.
  • If the simulated transition changes the linked invoice state, corresponding invoice.* events are emitted as well.

​
Suggested end-to-end test flow

  1. Create a devnet order + invoice via commerce.checkout.createInvoice (save orderId and invoiceId).
  2. Configure webhooks or connect a WebSocket listener (examples below).
  3. Simulate the happy path sequence:
    • payment_confirmed
    • payment_settled
    • placed
    • shipped (include tracking)
    • delivery_confirmed
  4. Optionally test failure paths:
    • failed (only valid from status=processing)
    • cancelled (only valid from status=placed)
    • refunded (requires a valid BSC refund destination)

​
Webhook setup (merchant)

Configure webhooks in the dashboard (or via /api/v1/webhooks/*) to receive:
  • X-Pepay-Event: commerce.order.updated
  • data.object.id set to the orderId you simulated

​
WebSocket updates (commerce stream)

const token = await pepay.ws.token.mint({ scope: 'commerce', ttlSeconds: 300 });
const stream = pepay.ws.connectCommerceEvents({
  token: String(token?.data?.token),
  format: 'event_v1',
  types: 'commerce.order.*'
});

stream.on('event', (event) => {
  if (event.type !== 'commerce.order.updated') return;
  if (event.data?.object?.id !== 'order_123') return;
  console.log('order update', event.data?.object);
});

​
Response

Example merchant order snapshot (truncated): 
{
  "success": true,
  "data": {
    "orderId": "550e8400-e29b-41d4-a716-446655440000",
    "invoiceId": "550e8400-e29b-41d4-a716-446655440111",
    "networkEnvironment": "devnet",
    "status": "placed",
    "substatus": "AWAITING_TRACKING",
    "actions": { "canCancel": true }
  }
}

​
Errors

  • 401 missing/invalid commerce API key
  • 404 order not found
  • 400 missing Idempotency-Key on cancel

​
Examples

  • When building an order dashboard, combine:
    • order snapshot (orders.retrieve)
    • payment status (payments.status)
    • invoice reconciliation (merchantInvoices.status) Next: Payments