Skip to main content

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.

​
Overview

Checkout is a 3-step flow:
  1. estimate totals → 2) collect/validate shipping address → 3) create an invoice.

​
Authentication

Merchant checkout routes require x-commerce-api-key.

​
Request

​
Estimate checkout

const estimate = await pepay.commerce.checkout.estimate({
  customer_id: 'cust_123456',
  items: [
    {
      productId: 'B08N5WRWNW',
      retailer: 'amazon',
      title: 'Item',
      quantity: 1,
      price: 9.99
    }
  ]
});

​
Submit address

const address = await pepay.commerce.checkout.address({
  customer_id: 'cust_123456',
  estimateId: '550e8400-e29b-41d4-a716-446655440000',
  address: {
    first_name: 'Jane',
    last_name: 'Doe',
    street_address: '123 Main St',
    address_line2: 'Apt 4B',
    city: 'Miami',
    state: 'FL',
    zip_code: '33101',
    country: 'US',
    phone: '+13055550123',
    email: 'jane@example.com'
  }
});

​
Create invoice

const invoice = await pepay.commerce.checkout.createInvoice({
  customer_id: 'cust_123456',
  estimateId: '550e8400-e29b-41d4-a716-446655440000',
  addressId: '550e8400-e29b-41d4-a716-446655440222',
  refundDestinationWalletAddressBsc: '0x0000000000000000000000000000000000000001'
});

​
Response

Example invoice response (truncated): 
{
  "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": "550e8400-e29b-41d4-a716-446655440444",
    "signature": "<signatureHash>.<timestamp>",
    "payment_session_headers": {
      "x-session-token": "550e8400-e29b-41d4-a716-446655440444",
      "x-signature": "<signatureHash>.<timestamp>"
    },
    "merchantId": 123,
    "networkEnvironment": "devnet",
    "customerId": "cust_123456",
    "amount": 13.99,
    "status": "unpaid",
    "expiresAt": 1765844400,
    "endpoints": {
      "checkOrder": "/api/commerce/merchant/orders/550e8400-e29b-41d4-a716-446655440111",
      "checkPayment": "/api/commerce/merchant/payments/550e8400-e29b-41d4-a716-446655440111/status",
      "cancelOrder": "/api/commerce/merchant/orders/550e8400-e29b-41d4-a716-446655440111/cancel"
    }
  }
}
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.

​
Errors

  • 400 invalid checkout/address payload
  • 401 missing/invalid commerce API key
  • 409 idempotency conflict on invoice creation

​
Examples

  • Treat invoice creation as a write: always pass an Idempotency-Key when calling the API directly. Next: Orders