Skip to main content
This guide walks a merchant through the full cross-chain payments flow, from keys to settlement.

​
Prerequisites

  • Pepay dashboard access
  • A merchant API key (scope=merchant)
  • A backend service to create invoices and handle events
Mainnet access is gated. Request access in the dashboard or via [email protected]. Until then, use devnet keys and testnet flows.
Base URL for examples: https://api-beta.pepay.io

​
Step 1 - Create a merchant API key

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

​
Step 2 - Create an invoice (server)

Invoices are the source of truth for payment status and reconciliation. 
BASE_URL=https://api-beta.pepay.io

curl -X POST "$BASE_URL/api/v1/invoices" \
  -H "x-api-key: <merchant_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_usd": 49.00,
    "description": "Order #1001",
    "customer_id": "cust_123"
  }'
The response includes:
  • invoice_id: canonical id for reconciliation
  • payment_url: hosted checkout link (valid until expiration)
  • payment_session_headers: session headers for embedded checkout flows

​
Step 3 - Present checkout (payor)

Send the payor to the hosted payment_url, or embed checkout using the payment session headers (x-session-token and x-signature) on payor endpoints.

​
Step 4 - Track status (server)

Use realtime delivery and/or polling:
  • Webhooks: configure in the dashboard and process invoice.updated and invoice_payment.updated.
  • Merchant WebSocket: connect with an API key or ws_token to stream the same events in realtime.
Recommended pattern:
  • Use both webhooks and WebSockets for resiliency.
  • Deduplicate by event.id.
  • Keep handlers idempotent.

​
Step 5 - Reconcile

Use invoice status for business decisions and reconciliation:
  • GET /api/v1/invoices/{invoiceId}
  • GET /api/v1/invoices/{invoiceId}/status

​
Step 6 - Go live

When mainnet access is enabled:
  1. Switch to a mainnet API key.
  2. Verify webhook delivery in production.
  3. Monitor invoice lifecycle events and settlement.

​
Integration checklist

  • Merchant API key stored in server config
  • Invoice creation wired to your backend
  • Hosted or embedded checkout presented to payors
  • Webhooks configured and verified
  • WebSocket or polling added for redundancy
  • Invoice reconciliation logic implemented
  • Devnet flows verified and mainnet access requested

​
SDK references

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