v1JSON over HTTPS

API reference

Create invoices, open checkout and track payments.

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 credentialsKeep API tokens on your server, never in browser code. Examples do not send requests.

Quickstart

Examples use this installation’s active API and checkout URLs. Copy your project and store IDs and set WHOLLY_TOKEN on your server.

1
Prepare the store
Enable store payment methods and back up their wallets. Check that nodes and rates are ready.
2
Create a credential
In API access, choose read/write and assign the project. Save the token securely.
3
Create the invoice
Send decimal amounts as strings. Keep the same Idempotency-Key and body when retrying.
4
Redirect and reconcile
Send the customer to links.checkout. Verify settlement before fulfilling the order.

Project & store IDs

Authentication & scope

Bearer token

Use Authorization: Bearer …. Tokens are shown once; disabling or rotating one revokes it.

Permission level

Read only retrieves data. Read + write also creates invoices and changes payment methods. Neither grants console access.

Project scope

Assign each credential to its projects. Creating invoices also requires an enabled store in that project.

Exact IP allowlist

Optionally allow exact public IPv4/IPv6 egress addresses. CIDR ranges and private workstation addresses are not supported.

Permission reference

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

Assets & wallets

Enable the native chain

Enable the native chain before selecting its tokens. It needs ready wallets and scanner-compatible nodes.

Verify tokens on-chain

Browse matching tokens or add a custom contract. On-chain verification is required; custom rates can be fixed in USD or linked to a DEX pool.

Select per store

Select up to 64 payment methods per store. Only ready methods appear on new invoices.

Read cached balances

Tokens share their chain wallet. Cached balances include invoice addresses; stale or unavailable data does not mean zero. Fiat values are advisory.

Scanner readiness & Monero setup

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 verifiedScanners verify transfers and required tags or memos. A second endpoint from a different provider must agree before finality. Wallet balances are not payment proof.

Invoice lifecycle

Poll the merchant detail

Poll using public_id, not the internal id. Back off when the response is unchanged.

Expect late movement

Late transfers can change an expired invoice while monitoring continues. A cancelled invoice needs explicit reconciliation to reopen.

Order with sequence

Save the highest sequence per invoice. Ignore older notifications so retries cannot roll back your order state.

Dynamic IPN & webhooks

Per invoice

Dynamic IPN

Set ipn_url at creation, or inherit the store default. Create the store’s IPN signing secret first.

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

Per store

Webhook endpoint

In Stores → Webhooks, choose URLs and events. Webhooks work independently of an invoice’s IPN URL.

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

Signature verification & delivery rules

Endpoints

Errors & limits

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.

Error codes

Limits, caching & retries

Support matrix

Capabilities & console-only operations

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.