Skip to main content

​
Overview

Pepay Commerce APIs power product search, carts, checkout invoicing, order tracking, and commerce payment status. Key ideas:
  • Base path: /api/commerce/*
  • Merchant addresses: /api/v1/commerce/merchant/addresses
  • SDK mapping: pepay.commerce.*
  • Typical flow: Search → Merchant carts → Checkout invoice → Orders → Payments

​
Authentication

Commerce requests use a commerce-scoped API key:
  • x-commerce-api-key: ck_...
There are two common patterns:
  • Merchant operations (server-to-server): x-commerce-api-key
  • Wallet-auth operations (not included here): x-commerce-api-key + User-Authorization: Bearer <userAccessToken>

​
Request

Start by checking the Commerce service status: 
BASE_URL=${PEPAY_API_URL}

curl "$BASE_URL/api/commerce/status" \
  -H "x-commerce-api-key: ck_..."

​
Response

Representative GET /api/commerce/status response: 
{
  "success": true,
  "data": {
    "status": "available",
    "escrowBalance": 50,
    "minimumRequired": 50,
    "features": {
      "search": true,
      "cart": true,
      "checkout": true,
      "orders": true
    }
  }
}

​
Errors

  • 401 missing/invalid commerce API key
  • 429 rate limits (retry with backoff; respect Retry-After when present)
  • 5xx transient errors (retry where safe)

​
Examples

If you’re building the canonical Commerce experience, follow the sidebar in order:
  1. API keys → 2) Search → 3) Checkout → 4) Orders
Next: Commerce API keys