> ## 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 Cross-chain Payments

> A-to-Z merchant guide for accepting multi-chain payments with Pepay.

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

## Step 2 - Create an invoice (server)

Invoices are the source of truth for payment status and reconciliation.

```bash theme={null}
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

* [Create an invoice](/sdk/merchants/invoices#create-an-invoice)
* [Poll status](/sdk/merchants/invoices#poll-status) and [wait for terminal status](/sdk/merchants/invoices#wait-for-terminal-status)
* [Event recovery](/sdk/merchants/events#recover-events-since-a-cursor-helper)
* [Realtime stream](/sdk/merchants/websockets#connect-to-merchant-events)
* [Payor session details (embedded)](/sdk/payors/payment-session#fetch-session-details)

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