Skip to main content
This guide covers the merchant commerce flow end to end: search, checkout, orders, and lifecycle updates.

​
Prerequisites

  • Pepay dashboard access
  • A commerce API key (scope=commerce)
  • A backend service to create checkout orders and handle events
Mainnet access is gated. Request access in the dashboard or via [email protected]. Devnet orders use testnet flows and do not place real retailer orders.
Base URL for examples: https://api-beta.pepay.io

​
Step 1 - Create a commerce API key

Create a key in the dashboard and store it in your server config. Dashboard: https://pepay.io/sign-in

​
Step 2 - Verify commerce availability

Check that commerce is enabled for your key: 
BASE_URL=https://api-beta.pepay.io

curl "$BASE_URL/api/commerce/status" \
  -H "x-api-key: <commerce_api_key>"

​
Step 3 - Search products (optional)

If you are building a catalog experience, query the search endpoint: 
curl "$BASE_URL/api/commerce/search?q=headphones&limit=5" \
  -H "x-api-key: <commerce_api_key>"

​
Step 4 - Identify the customer

Commerce checkout requires one identifier:
  • customer_id (merchant-owned customer id), or
  • wallet_address + wallet_network
Choose one and use it consistently for carts, checkout, and order lookup.

​
Step 5 - Create checkout (estimate -> address -> invoice)

The checkout flow is three steps:
  1. Estimate: validate items and pricing
  2. Address: attach shipping details
  3. Invoice: finalize checkout and create the order
Example (estimate with direct items): 
curl -X POST "$BASE_URL/api/commerce/merchant/checkout/estimate" \
  -H "x-api-key: <commerce_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cust_123",
    "items": [
      { "product_id": "B0B844T634", "quantity": 1, "retailer": "amazon" }
    ]
  }'
The invoice response includes an orderId and invoiceId.

​
Step 6 - Collect payment

Use the commerce invoice to present checkout and collect payment. The payment status and order status move together under the hood.

​
Step 7 - Track order lifecycle

Use these for merchant-facing order state:
  • GET /api/commerce/merchant/orders
  • GET /api/commerce/merchant/orders/{orderId}
  • Filter by customer_id or wallet when listing
For realtime:
  • Commerce WebSocket for streaming commerce.order.*
  • Webhooks for delivery to your backend (same events)
Recommended pattern:
  • Use both WebSockets and webhooks.
  • Deduplicate by event.id.
  • Keep handlers idempotent.

​
Step 8 - Cancellation and refunds

If you support cancellations:
  • POST /api/commerce/merchant/orders/{orderId}/cancel
  • Provide an Idempotency-Key
  • Include a refund destination when applicable

​
Step 9 - Devnet simulation (testing)

On devnet, you can simulate order transitions:
  • POST /api/commerce/devnet/orders/{orderId}/simulate
Each simulation emits the normal commerce.order.updated event so you can test your event handling.

​
Step 10 - Go live

When mainnet access is enabled:
  1. Switch to a mainnet commerce API key.
  2. Verify webhook delivery in production.
  3. Monitor commerce order updates and settlement.

​
Integration checklist

  • Commerce API key stored in server config
  • Commerce status verified as available
  • Customer identification strategy chosen and consistent
  • Checkout flow wired (estimate -> address -> invoice)
  • Merchant order views implemented
  • Webhooks configured and verified
  • WebSocket stream added for realtime
  • Devnet simulation used to validate lifecycle handling
  • Mainnet access requested

​
SDK references

If you want help or a review of your integration, reach out at [email protected].