Orders

​

Overview

​

Authentication

​

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)

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)

• 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

{
  "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