Quickstart

You’ll need a Paywire gateway with an API key, an https URL that can receive webhooks, and a testnet wallet with a little ETH on Sepolia.

Get an API key

A Paywire admin creates a gateway for your product in the dashboard (Gateways → New gateway). Its first API key is shown once and starts with w3g_. Store it as a secret on your server, never in a browser or app.

export PAYWIRE_API_KEY="w3g_..."

Get a webhook URL

For a first test, use a request inspector such as webhook.site: it gives you an https URL and shows what arrives. Later this is an endpoint on your own server; see Webhooks.

Create a payment link

Ask for 5 USD, payable in Sepolia ETH or test USDC:

curl -X POST https://api.staging.paywire.xyz/payments/links \
  -H "Authorization: Bearer $PAYWIRE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5,
    "currency": "USD",
    "callbackUrl": "https://webhook.site/your-id",
    "allowedAssets": [
      { "network": "ethereum_sepolia", "token": "native" },
      { "network": "ethereum_sepolia", "token": "0x1c7d4b196cb0c7b01d743fbc6116a902379c7238" }
    ]
  }'

const response = await fetch("https://api.staging.paywire.xyz/payments/links", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PAYWIRE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    amount: 5,
    currency: "USD",
    callbackUrl: "https://webhook.site/your-id",
    allowedAssets: [
      { network: "ethereum_sepolia", token: "native" },
      { network: "ethereum_sepolia", token: "0x1c7d4b196cb0c7b01d743fbc6116a902379c7238" },
    ],
  }),
});
const link = await response.json();
console.log(`https://pay.staging.paywire.xyz/pay/${link.id}`);

import os, requests

link = requests.post(
    "https://api.staging.paywire.xyz/payments/links",
    headers={"Authorization": f"Bearer {os.environ['PAYWIRE_API_KEY']}"},
    json={
        "amount": 5,
        "currency": "USD",
        "callbackUrl": "https://webhook.site/your-id",
        "allowedAssets": [
            {"network": "ethereum_sepolia", "token": "native"},
            {"network": "ethereum_sepolia", "token": "0x1c7d4b196cb0c7b01d743fbc6116a902379c7238"},
        ],
    },
).json()
print(f"https://pay.staging.paywire.xyz/pay/{link['id']}")

The response is the link, with its id:

{
  "id": "0193a0c4-5f2e-7c1d-9b8a-3e4f5a6b7c8d",
  "merchantId": "0193a0b1-2c3d-7e4f-8a9b-0c1d2e3f4a5b",
  "amount": 5,
  "currency": "USD",
  "allowedAssets": [
    { "network": "ethereum_sepolia", "token": "native", "decimals": 18 },
    { "network": "ethereum_sepolia", "token": "0x1c7d4b196cb0c7b01d743fbc6116a902379c7238", "decimals": 6 }
  ],
  "callbackUrl": "https://webhook.site/your-id",
  "orderTtlMinutes": 30,
  "policyOverride": null,
  "returnUrl": null,
  "isActive": true,
  "createdAt": "2026-10-24T09:12:31.204Z"
}

Pay it

Open https://pay.staging.paywire.xyz/pay/<id>, pick ETH on Ethereum Sepolia, and send the exact amount shown from your wallet (MetaMask on Sepolia works). The checkout updates within seconds of your transaction.

Receive the webhook

After 12 confirmations (2–3 minutes) the payment is Settled and your URL receives:

{
  "id": "0193a0c9-1b2c-7d3e-8f4a-5b6c7d8e9f0a",
  "type": "order.settled",
  "createdAt": "2026-10-24T09:16:02.511Z",
  "data": {
    "orderId": "0193a0c5-0a1b-7c2d-8e3f-4a5b6c7d8e9f",
    "paymentLinkId": "0193a0c4-5f2e-7c1d-9b8a-3e4f5a6b7c8d",
    "status": "Settled",
    "previousStatus": "Confirming",
    "expectedAmount": { "network": "ethereum_sepolia", "token": "native", "decimals": 18, "baseUnits": "1612903225806451" },
    "confirmedAmount": { "network": "ethereum_sepolia", "token": "native", "decimals": 18, "baseUnits": "1612903225806451" },
    "fiat": { "amount": 5, "currency": "USD" }
  }
}

Before trusting a webhook in production, verify its signature.

Next steps

Payment statuses

What each webhook means and what to do with it.

Build your own checkout

Skip the hosted page and show the address in your own app.

Get started

Concepts

Integrate

Next steps

Payment statuses

Build your own checkout

​Next steps

Payment statuses

Build your own checkout

Next steps