Skip to main content

​
Overview

Checkout is the bridge between a cart (items + shipping) and payment. The Commerce checkout flow is intentionally stepwise so you can validate totals before creating an invoice.

​
Authentication

Requires a commerce-scoped API key: x-commerce-api-key: ck_....

​
Request

Endpoints:
  • POST /api/commerce/merchant/checkout/estimate
  • POST /api/commerce/merchant/checkout/address
  • POST /api/commerce/merchant/checkout/invoice

​
Playground (interactive reference)

Example (create invoice): 
BASE_URL=${PEPAY_API_URL}

curl -X POST "$BASE_URL/api/commerce/merchant/checkout/invoice" \
  -H "x-commerce-api-key: ck_..." \
  -H "Idempotency-Key: 123e4567-e89b-42d3-a456-556642440000" \
  -H "Content-Type: application/json" \
  -d '{}'

​
Response

Representative invoice creation response: 
{
  "success": true,
  "data": {
    "orderId": "550e8400-e29b-41d4-a716-446655440111",
    "invoiceId": "550e8400-e29b-41d4-a716-446655440000",
    "invoiceUrl": "https://<payment-iframe-host>/pay?session=pst_...&signature=sig_...",
    "session": "pst_...",
    "signature": "sig_...",
    "payment_session_headers": {
      "x-session-token": "pst_...",
      "x-signature": "sig_..."
    },
    "merchantId": 123,
    "networkEnvironment": "devnet",
    "status": "unpaid"
  }
}
Notes:
  • Commerce invoices expire after ~30 minutes (expiresAt in the response).
  • Create a new invoice for every checkout attempt or retry; do not reuse expired or failed invoices.
  • Max commerce order value is $2500; requests above this return a checkout error.
  • Offers must be deliverable within 10 days to be eligible for checkout.

​
Errors

  • 400 invalid checkout payload
  • 401 missing/invalid commerce auth

​
Examples

Recommended flow:
  1. Estimate (/estimate) → 2) Address (/address) → 3) Invoice (/invoice)
Next: Orders