> ## Documentation Index
> Fetch the complete documentation index at: https://docs-alpha.pepay.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrate Commerce

> A-to-Z merchant guide for commerce checkout, orders, and fulfillment.

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 [support@pepay.io](mailto:support@pepay.io). 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](https://pepay.io/sign-in)

## Step 2 - Verify commerce availability

Check that commerce is enabled for your key:

```bash theme={null}
BASE_URL=https://api-beta.pepay.io

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

## Step 3 - Search products (optional)

If you are building a catalog experience, query the search endpoint:

```bash theme={null}
curl "$BASE_URL/api/commerce/search?q=headphones&limit=5" \
  -H "x-commerce-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):

```bash theme={null}
curl -X POST "$BASE_URL/api/commerce/merchant/checkout/estimate" \
  -H "x-commerce-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`. Commerce invoices expire after \~30 minutes (`expiresAt`). Create a new invoice for every checkout attempt or retry; do not reuse expired or failed invoices.

## 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

If a commerce order is unsuccessful (canceled/failed after payment), Pepay currently returns funds to the customer’s **BSC wallet** in **native USD1**. Make sure you collect or store a BSC wallet address for the customer at checkout so returns can be delivered.

## 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

* [Checkout estimate](/sdk/commerce/checkout#estimate-checkout)
* [Create invoice](/sdk/commerce/checkout#create-invoice)
* [List merchant orders](/sdk/commerce/orders#list-merchant-orders) and [retrieve an order](/sdk/commerce/orders#retrieve-an-order)
* [Cancel orders](/sdk/commerce/orders#cancel-an-order)
* [Webhook config](/sdk/commerce/webhooks#create-or-update-webhook-configuration)
* [Commerce WebSocket stream](/sdk/commerce/websockets#connect-to-commerce-events)

If you want help or a review of your integration, reach out at [support@pepay.io](mailto:support@pepay.io).