# White label payment API — complete reference in one file

This file is the whole documentation, condensed for an AI assistant. Give it to your assistant and ask it to write the integration. Human-readable version: https://whitelabel.chain2pay.is/

Base address: `https://YOUR-API-ADDRESS` — this stands for the address you receive with your API key.

## What the service does

- A buyer pays by card (or another everyday payment method) on a hosted checkout page.
- The payment arrives as crypto and is split on-chain as soon as it is confirmed: the merchant's wallet, every wallet listed in `splits` and the platform are all paid at that moment. Nothing is held, there is no balance to withdraw.
- You never hold or move money. You only create payments and read their status.
- One API key serves any number of merchants: the merchant's wallet is given on each payment.

## Authentication

Every call carries `Authorization: Bearer <key>`. Live keys start with `wl_live_`, test keys with `wl_test_`. Bodies and answers are JSON. Behind a reseller's own domain, shops may need no key: the reseller's domain adds its own.

## Endpoints

| Call | Purpose |
|---|---|
| `POST /v1/payments` | Create a payment |
| `GET /v1/payments/{id}` | Read a payment and its status |
| `GET /v1/providers` | Payment methods offered now, with their minimum amounts per currency |
| `GET /v1/balances/{wallet}` | What a wallet listed in `splits` has received so far |
| `POST /v1/payments/{id}/test-confirm` | Test keys only: mark a test payment as paid |

## Create a payment

```
curl -X POST https://YOUR-API-ADDRESS/v1/payments \
  -H "Authorization: Bearer wl_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: INV-2041" \
  -d '{
    "amount": "100.00",
    "currency": "EUR",
    "merchant_wallet": "0xMERCHANT...",
    "splits": [ { "wallet": "0xYOU...", "bps": 300, "label": "my margin" } ],
    "order_ref": "INV-2041",
    "callback_url": "https://your-site.com/hooks/payments"
  }'
```

| Field | Required | Meaning |
|---|---|---|
| `amount` | yes | Text, two decimals: `"49.90"` |
| `currency` | yes | Three-letter code: `EUR`, `USD`, `GBP`… |
| `merchant_wallet` | yes | Wallet (0x + 40 hex) of the merchant who receives the payment minus the fees |
| `splits` | no | List of `{ wallet, bps, label }`: wallets that take a share. 100 bps = 1%. `bps` is a whole number |
| `provider` | no | `multihosted` (default: the buyer chooses among the best methods for their country, crypto included), `crypto` (crypto-only payment: the page goes straight to the coin list), or one id from `GET /v1/providers` |
| `order_ref` | no | Your own reference, returned everywhere |
| `callback_url` | no | Public https address notified when the status changes |
| `customer_email` | no | Prefills the buyer's email where a method asks for it |
| `metadata` | no | Your own data, returned as it is |

Send an `Idempotency-Key` header with your own reference: a repeated call returns the same payment instead of creating a second one.

Answer (HTTP 201, or 200 when the idempotency key was already used):

```
{
  "id": "pay_8Hq2mZx4LrT6bN0cVw3K",
  "status": "pending",
  "amount": "100.00",
  "currency": "EUR",
  "provider": "multihosted",
  "checkout_url": "https://YOUR-API-ADDRESS/c/9f3b...",
  "merchant_wallet": "0xMERCHANT...",
  "fees": { "total_bps": 500, "merchant_bps": 9500, "splits": [ { "wallet": "0xYOU...", "bps": 300, "label": "my margin" } ] },
  "order_ref": "INV-2041",
  "test": false,
  "created_at": "2026-11-19T10:12:00.000Z"
}
```

Redirect the buyer to `checkout_url`. The page shows the payment methods available in the buyer's country, in the buyer's language. A method under maintenance sends the buyer to the other methods.

## Statuses

| Status | Meaning |
|---|---|
| `pending` | Waiting for the buyer |
| `processing` | Payment seen, being confirmed |
| `paid` | Confirmed and split on-chain |
| `expired` | Not paid in time |

## Fees and sharing

- `fees.total_bps`: everything taken from the payment, all levels together. `fees.merchant_bps`: what the merchant receives.
- The platform fee is included in `fees.total_bps` and is fixed. You add your own share with `splits`.
- Crypto payments carry a lower platform share than card payments. A crypto-only payment shows it from creation; when a buyer pays in crypto on the multihosted page, `GET /v1/payments/{id}` shows the share that applied. The wallets in `splits` keep their share either way.
- At most 20 wallets share one payment, all resale levels together. The total of all fees is at most 30% of the payment.
- Every share is paid on-chain with the payment, in the asset and on the network the payment method delivers. Each wallet in `splits` is one more transfer: keep the list short.
- `GET /v1/balances/{wallet}` answers `{ wallet, currency, earned, paid_out, pending, payments, last_payout_at }` (amounts in US dollars).

## Notifications

When a payment changes status, `callback_url` receives a POST:

```
{
  "type": "payment.paid",
  "created": 1794046320,
  "data": { "id": "pay_8Hq2mZx4LrT6bN0cVw3K", "status": "paid", "amount": "100.00", "currency": "EUR", "order_ref": "INV-2041" }
}
```

- Events: `payment.paid`, `payment.expired`.
- Header `X-WL-Signature: t=<unix seconds>,v1=<hex>`, where `v1` = HMAC-SHA256 of `<t>.<raw body>` with your `whsec_…` secret. Reject a `t` older than 5 minutes.
- Answer any 2xx within 10 seconds. Otherwise it is sent again with growing delays, up to eight times over about two days.
- The same event can arrive twice: use `data.id` to handle it once.
- Never deliver on a notification alone. Verify the signature, or read the payment again with `GET /v1/payments/{id}` and check `status`, `merchant_wallet`, `order_ref`, `amount`, `currency` and `test`.

```js
import crypto from "node:crypto"
// rawBody: the body exactly as received (a string, before JSON.parse)
export function isGenuine(rawBody, header, secret) {
  const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header || "")
  if (!m || Math.abs(Date.now() / 1000 - Number(m[1])) > 300) return false
  const expected = crypto.createHmac("sha256", secret).update(m[1] + "." + rawBody).digest("hex")
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(m[2]))
}
```

## Errors

An error answers `{ "error": { "code": "…", "message": "…" } }`.

| HTTP | Code | Meaning |
|---|---|---|
| 400 | `invalid_request` | A field is missing or malformed; the message names it |
| 400 | `invalid_splits` | A split has no valid wallet, or `bps` is not a whole number |
| 400 | `too_many_splits` | More than 20 wallets share the payment |
| 400 | `fees_too_high` | The fees add up to more than 30% |
| 400 | `amount_out_of_range` | Below what the payment method accepts |
| 400 | `provider_unavailable` | This method is not offered; use `multihosted` or another one |
| 401 | `unauthorized` | Unknown or missing key |
| 403 | `key_suspended` | The key is suspended |
| 404 | `not_found` | Unknown payment |
| 429 | `rate_limited` | Too many calls; wait and try again |

## Pay with crypto

- The multihosted page shows "Pay with crypto" under the card methods. The buyer picks a coin and a network (USDT, USDC, ETH, BNB, POL, AVAX, DAI and more, on Ethereum, BNB Chain, Polygon, Arbitrum, Optimism, Base and Avalanche), then sends it from their own wallet to the address shown, with a QR code and a live status.
- `provider: "crypto"` creates a crypto-only payment: `checkout_url` opens the coin list directly. `GET /v1/providers` lists `crypto` with its minimum amounts.
- Each coin has a minimum; below it, the page says so.
- The payment is split on-chain like any other one: merchant, platform and every wallet in `splits`.

## Test mode

A `wl_test_…` key works like a live one with no real money: answers carry `"test": true`, `POST /v1/payments/{id}/test-confirm` marks the payment as paid (the crypto page itself is not shown for test payments) and sends the signed notification. Never deliver real goods on a payment where `test` is true.

## Plugins

Ready-made shop plugins, with no brand (rename them and ship them as yours). The shop owner enters the payment address (the API address, or the reseller's own domain), a wallet, and a key if one was given. Before completing an order, each plugin reads the payment back and checks the wallet, the reference, the amount and the currency.

| Platform | File |
|---|---|
| WooCommerce | `https://whitelabel.chain2pay.is/wl-plugins/woocommerce.zip` |
| WHMCS | `https://whitelabel.chain2pay.is/wl-plugins/whmcs.zip` |
| PrestaShop | `https://whitelabel.chain2pay.is/wl-plugins/prestashop.zip` |
| OpenCart 4 | `https://whitelabel.chain2pay.is/wl-plugins/opencart.zip` (save it as `cardpayments.ocmod.zip`) |
| Easy Digital Downloads | `https://whitelabel.chain2pay.is/wl-plugins/edd.zip` |
| FOSSBilling | `https://whitelabel.chain2pay.is/wl-plugins/fossbilling.zip` (folder goes into `library/Payment/Adapter/`) |
| Paymenter | `https://whitelabel.chain2pay.is/wl-plugins/paymenter.zip` (folder goes into `extensions/Gateways/`) |

## Resell under your own domain

You can offer this same service on your own domain and earn a commission on every payment your customers receive.

1. Make your `worker.js`: use the form on https://whitelabel.chain2pay.is/ (section "Resell"; everything stays in the browser), or download `https://whitelabel.chain2pay.is/wl-worker.js` and set the four values at the top: `UPSTREAM` (the API address), `API_KEY`, `WALLET`, `FEE_PERCENT`.
2. Cloudflare (free plan): Compute → Workers & Pages → Create application → Start with Hello World → Deploy → Edit code → paste `worker.js` → Deploy.
3. Worker → Domains → Add Domain: for example `pay.your-domain.com`. Cloudflare creates the DNS record and the certificate.
4. Give your customers your domain and a plugin. They enter your domain as the payment address and their own wallet.

- Your domain then serves the API (`/v1/*`) and the payment pages under your name. Nothing else is served there: no guide, no download.
- Your commission is added on your domain to every payment, as one more entry in `splits`, and is paid to your wallet on-chain with the payment. Your customers cannot remove it.
- To let a customer resell under their own domain, make them a `worker.js` with your domain as `UPSTREAM`, an empty `API_KEY`, their wallet and their commission. There is no depth limit; a payment is shared between 20 wallets at most.
- A customer sees the total taken from a payment and their own shares, not what the levels above take.
- One key per customer, with the ability to price and suspend each one: use the advanced relay `https://whitelabel.chain2pay.is/wl-relay.zip` (Cloudflare command line; its README explains every step).

## Integration checklist

1. Create the payment server-side with an `Idempotency-Key`; store `id` next to your order.
2. Redirect the buyer to `checkout_url`.
3. On notification: verify, read `GET /v1/payments/{id}`, check `status === "paid"`, the wallet, your `order_ref`, the amount, the currency and `test === false`, then deliver once.
4. Treat `expired` as unpaid; create a new payment if the buyer comes back.
