v1JSON over HTTPS

Merchant integration

Create an invoice.
Let settlement stay verifiable.

Source-aligned reference for asset and wallet readiness, server-side invoice creation, searchable reconciliation, hosted checkout, dynamic IPN delivery, and store webhooks. Examples are inert templates with deliberate copy controls—this page never reads or inserts a merchant token.

Start integrating Browse endpoints

Active installationService originsResolving…

Merchant API: https://api.example.com
Hosted checkout: https://pay.example.com
Console: Current origin

Loading active service URLs, including custom subdomain names. Safe placeholders remain if settings are unavailable.

Backend-only credentialsCall the merchant API from infrastructure you control. Browser CORS is not enabled, and embedding a bearer token in frontend code would expose it.

01 · First request

Quickstart

Four deliberate steps from credential to checkout.

Default hosts: merchant.example.com for the console, pay.example.com for checkout, and api.example.com for API requests. Existing installations keep their configured names; examples below use your active URLs.

1
Prepare the store
Enable a scanner-ready native asset or verified token, generate and back up its chain wallet, then select it for the store. A fresh trusted rate must be available.
2
Create a credential
In Settings → API access, choose read/write, assign the project, optionally restrict exact egress IPs, and save the one-time token securely.
3
Create the invoice
Send the token and a new Idempotency-Key. Decimal money values are strings; unknown JSON fields are rejected.
4
Redirect and reconcile
Open links.checkout for the customer. Poll the invoice detail endpoint and verify signed notifications independently.

02 · Trust boundary

Authentication & scope

Every merchant route checks identity, permission, project assignment, and source IP.

Bearer token

Send exactly one Authorization: Bearer … header. Tokens begin with wc_live_, are shown once, and are invalidated immediately when disabled or rotated.

Permission level

Read only can list and retrieve. Read + write can also create. Neither grants console, node, system, webhook-management, or credential-management access.

Project scope

A credential can access only enabled projects explicitly assigned to it. Invoice creation additionally requires the store UUID to belong to that project and both resources to be enabled.

Exact IP allowlist

When enabled, the public API compares the proxy-established client address to exact IPv4/IPv6 entries. CIDR ranges are not accepted; allowlist stable outbound proxy/NAT addresses, not private workstation addresses.

Permission boundary
Operation	Read only	Read + write	No token
List/retrieve scoped invoices, assets, store methods, and wallet balances	Allowed	Allowed	Denied
Change asset policy, verify a token, or replace store methods	Denied	Allowed	Denied
Create scoped store invoice	Denied	Allowed	Denied
Open checkout page/API/assets	Not needed	Not needed	Allowed with public ID
Generate/reveal wallet secrets, configure automatic sweep, or approve/sign/broadcast a treasury plan	Console only	Console only	Console only

03 · Capability gate

Assets & wallets

Catalog discovery, on-chain verification, project policy, and store selection are separate steps.

Enable the native chain

The project’s native asset is the chain switch. It must be payment-supported, runtime-wired, and scanner-ready with the required endpoint role before a token on that chain can be promoted or selected.

Verify tokens on-chain

CoinGecko supplies a candidate contract or mint, icon, and price identity. Wholly Crypto verifies network identity and token metadata through configured nodes before creating a durable asset.

Select per store

Project enablement makes an asset available. The store’s ordered subset controls which ready methods appear on newly created invoices; up to 64 can be selected.

Read cached balances

One chain wallet serves its native asset and verified tokens. Payment-acceptance switches do not pause read-only tracking: active and disabled wallets continue refreshing registered same-chain assets. Exact balances include issued invoice addresses; USD values are advisory. Pending or stale data is never proof of zero.

Healthy node does not mean payment-readyEvery payment scanner requires its exact endpoint role, a ready project wallet, and two independent healthy scanner-compatible endpoints. Monero becomes selectable only after its project wallet is bound to an exact external watch-only wallet-RPC behind an HTTPS method-allowlisting gateway, the live proof passes, and the operator completes both attestations. Public daemons supply settlement quorum but cannot discover private incoming outputs; native --restricted-rpc is incompatible because it denies subaddress creation.

Invoice evidence is transaction-level and independently verifiedOutputs, transactions, operations, events, required tags or memos, and canonical block evidence are parsed by each rail’s dedicated scanner. A second endpoint from a different provider must agree before a transfer becomes final; wallet balance snapshots remain advisory.

04 · Reconciliation

Invoice lifecycle

Status, amount, timing, and sequence are separate signals—persist all four.

Poll the merchant detail

Use the public invoice UUID returned as public_id, not the internal id. Poll GET /v1/projects/{project_id}/invoices/{public_id}; back off between unchanged responses.

Expect late movement

expired is not necessarily the end of monitoring. A late transfer can move an invoice back to processing or onward to settled/invalid. cancelled is terminal.

Order with sequence

sequence starts at 1 and increases on state transitions and additional-payment events, even when status fields stay unchanged. Store the highest processed value per invoice so retried or out-of-order notifications cannot regress local state.

05 · Server-to-server events

Dynamic IPN & webhooks

Two delivery models, one exact payload and signature contract.

Per invoice

Dynamic IPN

Set ipn_url while creating an invoice to override the store default. Omitted or null inherits that default. The store must already have an IPN signing secret created in the console.

One target URL for that invoice
Shared store IPN signing secret
All invoice events

Per store

Webhook endpoint

Configure endpoints and their event subscriptions in the project’s Webhooks console. They receive selected store events independently of any invoice IPN URL.

Up to 64 active endpoints per store
Distinct one-time signing secret per endpoint
Automatic retry can be disabled per endpoint

06 · Route catalog

Endpoints

Generated from one maintainable catalog below.

07 · Failure handling

Errors & limits

JSON errors are machine-readable; transport limits can fail before a JSON handler runs.

Canonical JSON envelope

{
  "error": {
    "code": "invalid_payment_request",
    "message": "must be greater than zero",
    "details": { "field": "amount" }
  }
}

Branch on the HTTP status and stable error.code. Treat message as operator-facing context. details is optional.

08 · Current contract

Support matrix

What exists in this build—and what deliberately does not.

Operating note

Pin your integration to the documented v1 fields you use, tolerate additive response fields, retain idempotency keys, and test notification verification before accepting live payments. No refund, payout, or private-key operation is exposed through merchant credentials.

Create an invoice.Let settlement stay verifiable.