Quick Start

This guide walks you through the actual dashboard flow merchants follow today. Test mode is fully sandboxed: a pk_test_* key cannot touch mainnet. New accounts get $100 test credit and $50 live credit automatically, which covers your first integration without any top-up.

1. Create your account

2. Switch to test mode

Toggle the mode switch at the bottom of the sidebar to Test (on mobile, open the navigation menu - the switch is at the bottom of the drawer). Live and test modes are isolated: a pk_test_* key cannot create live payments, and vice versa. The toggle is saved to your account and re-applied on every sign-in, from any browser or device.

3. Add a wallet

API keys cannot be created until at least one wallet exists in the current mode. The API key creation page otherwise shows an empty state: "No test wallets yet" when your wallets are all in live mode, or "Add a wallet before creating an API key" when you have no wallets at all.

Not sure which wallet to use for each chain? See Choosing your wallets.

4. Create a test API key

The key starts with pk_test_. Store it server-side, never in browser code.

5. Create a test payment

Call POST /api/v1/payments with your test API key:

POST /api/v1/payments
Authorization: Bearer pk_test_...
Content-Type: application/json

{
  "fiat_amount": "10.00",
  "fiat_currency": "USD",
  "accepted_chains": ["ETH_SEPOLIA"]
}

Required fields:

Optional fields: accepted_chains (array), accepted_coins (array), accepted_tokens (array of CHAIN:SYMBOL), restrict_to_accepted (boolean, default false), order_id, description (200 char max), customer_email, success_url, cancel_url.

accepted_chains / accepted_coins / accepted_tokens set the checkout default coin (which coin the checkout opens on). By default they are not a restriction: the customer can switch to any coin your API key accepts. Omit them and the checkout shows the full picker. To limit which coins you receive, set the allowlist on the API key.

Set restrict_to_accepted: true to turn the accepted set into a hard restriction for that one payment: the checkout then offers only the coins/chains in the set, and select-chain rejects anything outside it with 422 COIN_NOT_IN_ACCEPTED_SET. restrict_to_accepted: true with no accepted set returns 422 RESTRICT_TO_ACCEPTED_REQUIRES_ALLOWLIST. Use it to accept a specific coin group (for example stablecoins only) with a single API key instead of one key per group.

Response (201 Created):

{
  "data": {
    "id": "018f7a3e-12b4-4a8d-bc5e-9f234567890a",
    "status": "pending",
    "fiat_amount": "10.00",
    "fiat_currency": "USD",
    "checkout_url": "https://checkout.noholdpay.com/018f7a3e-12b4-4a8d-bc5e-9f234567890a",
    "expires_at": "2026-05-14T12:20:00Z",
    "created_at": "2026-05-14T12:00:00Z",
    "chain_options": [
      {
        "chain_id": "ETH_SEPOLIA",
        "coin_symbol": "ETH",
        "crypto_amount": "3456789012345678",
        "display_amount": "0.003456",
        "address": "",
        "payment_uri": "",
        "exchange_rate": "2892.45",
        "exchange_rate_locked_at": "2026-05-14T12:00:00Z"
      }
    ]
  }
}

address and payment_uri are empty at creation. The deposit address is derived lazily when the customer picks a chain on the checkout page. Server integrations that need the address up-front can call POST /api/v1/checkout/{id}/select-chain and then GET /api/v1/checkout/{id}.

Open checkout_url in a browser to see the hosted checkout.

6. Pay the test invoice

Pay with testnet funds:

• ETH_SEPOLIA: send Sepolia ETH or Sepolia USDC from MetaMask.
  • ETH: ghostchain faucet (no auth), Chainlink (requires ~1 LINK).
  • USDC: Circle faucet (10 USDC per request).
• BTC_TESTNET: send testnet4 BTC. Faucets: coinfaucet.eu, testnet.help, mempool.space (GitHub auth).

The checkout updates in real time as the transaction is detected and confirmed.

7. Verify the webhook

If you added a webhook in step 4, your endpoint receives a signed payment.confirmed event after the required confirmations.

See Webhooks for signature verification.

Webhook URLs are managed on the API Keys page, not the Webhooks page. The Webhooks page is a read-only delivery inspector. To add, edit, or remove a webhook, expand the relevant API key on /api-keys.

Test vs live

Both modes deduct platform fees from a Prepaid Credit reserve. The reserves are separate. New accounts get both grants automatically at signup, so no top-up is needed to start integrating.

Switch to live by toggling the mode switch at the bottom of the sidebar, creating a live wallet, and issuing a pk_live_* key. The API calls are identical.

Next steps

• Payment lifecycle. Every status and what each means.
• Webhooks. Signature verification, retry handling, full event list.
• Trust model. What NoHoldPay can and cannot do with your funds.
• Pick your chain: Bitcoin, Ethereum and EVM, Solana, TRON, XRP, Monero.