Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.walletconnect.com/llms.txt

Use this file to discover all available pages before exploring further.

This guide takes you from zero to a live payment in six steps:
  1. Create an API key in the dashboard.
  2. Authenticate your requests with the key.
  3. Create your first merchant via POST /v1/merchants.
  4. Configure crypto settlement via POST /v1/merchants/{merchantId}/settlements/crypto.
  5. Create your first payment via POST /v1/payments.
  6. Check the payment status via GET /v1/payments/{id}/status.
Don’t have access to the dashboard yet? Contact sales to get started.
1

Create an API key

  1. Open API Keys in the dashboard and sign in if prompted.
  2. Click Create key. Copy the key — it is shown only once.
  3. Store it in a secret manager. Anyone with this key can act on behalf of your account.
2

Authenticate

Every request to the Merchant API uses the Api-Key header.
export WCP_API_KEY="wcp_…"           # the key you just created
export WCP_BASE="https://api.pay.walletconnect.com"
A quick sanity check — list your merchants:
curl "$WCP_BASE/v1/merchants" \
  -H "Api-Key: $WCP_API_KEY"
A 200 OK with a (possibly empty) data array confirms the key works. A 401 means the key is wrong; a 403 means the key is valid but lacks permission for this account.
Pin requests to a specific API version with the WCP-Version header (for example, WCP-Version: 2026-02-18). Without it, your account’s default version is used. See Versioning for the full policy.
3

Create your first merchant

A merchant is the entity that receives payments. One account can hold many merchants — typically one per brand, storefront, or legal entity.
curl -X POST "$WCP_BASE/v1/merchants" \
  -H "Api-Key: $WCP_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantName": "Acme Store",
    "merchantEmail": "billing@acme.store"
  }'
The response includes the merchant id — save it, you’ll need it for every payment.
{
  "merchant": {
    "id": "mrch_7kBz2qR9xPvLmN4Yw",
    "name": "Acme Store",
    "email": "billing@acme.store",
    "status": "active",
    "createdAt": "2026-02-18T10:30:00.000Z"
  }
}

export WCP_MERCHANT_ID="mrch_7kBz2qR9xPvLmN4Yw"
Idempotency-Key is required on this endpoint. Use a fresh UUID per merchant — replays with the same key return the original result instead of creating a duplicate.
See the full schema and field reference in Create a merchant.
4

Configure crypto settlement

Before you can accept payments, tell us where to deliver settled funds. Each settlement entry pairs a CAIP-19 asset (the token you want to settle in) with a CAIP-10 destination wallet on the same chain.
curl -X POST "$WCP_BASE/v1/merchants/$WCP_MERCHANT_ID/settlements/crypto" \
  -H "Api-Key: $WCP_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "settlements": [
      {
        "asset": "eip155:8453/erc20:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
        "destination": "eip155:8453:0x1234567890abcdef1234567890abcdef12345678"
      }
    ]
  }'
The example above registers USDC on Base. For the full list of supported asset values and the chains we settle to, see Token & Chain Coverage.
Each (merchant, asset) pair must be unique — registering the same asset twice returns settlement_asset_conflict. To change a destination, use Update a crypto settlement instead.
See the full schema in Create crypto settlements.
5

Create your first payment

A payment is a request for funds against one of your merchants. You pass the merchant via the Merchant-Id header and your own order identifier as referenceId.
curl -X POST "$WCP_BASE/v1/payments" \
  -H "Api-Key: $WCP_API_KEY" \
  -H "Merchant-Id: $WCP_MERCHANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "referenceId": "ORDER-123",
    "amount": {
      "unit": "iso4217/USD",
      "value": "100"
    }
  }'
The response includes the payment id and a link your buyer can open in any WalletConnect-compatible wallet. Hand that link to your checkout, share it directly, or render it as a QR code.
export WCP_PAYMENT_ID="pay_…"        # from the response above
6

Check the payment status

Poll the status endpoint to know when the payment has completed:
curl "$WCP_BASE/v1/payments/$WCP_PAYMENT_ID/status" \
  -H "Api-Key: $WCP_API_KEY" \
  -H "Merchant-Id: $WCP_MERCHANT_ID"

{
  "status": "succeeded",
  "isFinal": true,
  "pollInMs": null,
  "info": {
    "txId": "0xabc123…",
    "optionAmount": {
      "unit": "caip19/eip155:8453/erc20:0x...",
      "value": "1000000"
    }
  }
}
Use isFinal to decide when to stop polling. While the payment is still in flight, the response returns isFinal: false and a pollInMs hint for how long to wait before polling again. Once isFinal is true, status is one of succeeded, failed, cancelled, or expired and pollInMs is null.
Prefer webhooks for production — they remove the need to poll. The status endpoint is the right tool for one-off checks, scripts, and debugging.
See the full response schema in Get the payment status.