ChainPayments Logo
ChainPayments
HomeAboutDocsPlaygroundContact
Developer Documentation

Build The Future Of Payments.

Integrate ChainPayments into your workflow with our self-custodial infrastructure and real-time polling engine.

Introduction

ChainPayments is a self-custodial cryptocurrency payment infrastructure. Our REST API allows you to integrate direct on-chain payments into your application with instant verification and no escrow.

  • RESTful JSON API
  • SHA-256 Hashed Keys
  • HTTPS Only
EXAMPLE
# Base URL
https://chainpayments.io/api/public/v1

Authentication

All API requests require an API key starting with 'crypt_' (Live) or 'test_' (Sandbox/Test). You can pass it via the 'Authorization: Bearer' header or the 'x-api-key' header.

  • RESTful JSON API
  • SHA-256 Hashed Keys
  • HTTPS Only
EXAMPLE
curl -X GET "https://chainpayments.io/api/public/v1/payments/pay_123" \
  -H "Authorization: Bearer crypt_YOUR_KEY"

Test Mode Sandbox

When using a 'test_' API key, the generated payment will be flagged as 'isTest: true' with stricter rate limits. In the checkout UI, users will see a 'Simulate Payment' flow instead of real wallet connections.

  • RESTful JSON API
  • SHA-256 Hashed Keys
  • HTTPS Only
EXAMPLE
// Test Mode Response
{
  "success": true,
  "payment": {
    "id": "pay_test123",
    "isTest": true,
    "checkoutUrl": "https://chainpayments.io/checkout/pay_test123"
  }
}

Create Payment (Fixed)

Initiate a payment with a specific chain and token preset. The customer will be prompted to pay exactly this amount on the specified network.

  • RESTful JSON API
  • SHA-256 Hashed Keys
  • HTTPS Only
EXAMPLE
curl -X POST "https://chainpayments.io/api/public/v1/payments" \
  -H "x-api-key: crypt_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chain": "eth",
    "token": "usdc",
    "amount": 49.99,
    "customerEmail": "[email protected]",
    "externalId": "order_777",
    "webhookUrl": "https://your-app.com/webhooks"
  }'

Create Payment (Flexible)

Create a payment without specifying a chain or token. The customer can select their preferred network from your active wallets during checkout.

  • RESTful JSON API
  • SHA-256 Hashed Keys
  • HTTPS Only
EXAMPLE
curl -X POST "https://chainpayments.io/api/public/v1/payments" \
  -H "x-api-key: crypt_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 49.99,
    "customerEmail": "[email protected]"
  }'

Get Status

Retrieve real-time status, received amounts, nested payment link data, and transaction hashes for any payment.

  • RESTful JSON API
  • SHA-256 Hashed Keys
  • HTTPS Only
EXAMPLE
curl -X GET "https://chainpayments.io/api/public/v1/payments/pay_abc123" \
  -H "x-api-key: crypt_YOUR_KEY"

Select Chain/Token

For flexible payments, use this endpoint to lock in a specific chain and token once the user makes a selection.

  • RESTful JSON API
  • SHA-256 Hashed Keys
  • HTTPS Only
EXAMPLE
curl -X PATCH "https://chainpayments.io/api/public/v1/payments/pay_abc123" \
  -H "x-api-key: crypt_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chain": "sol",
    "token": "usdc"
  }'

Webhooks

We send a signed POST to your configured 'webhookUrl' on every payment status change, including expiry. Verify the 'X-Signature' header (HMAC-SHA256 of the raw body with your webhook secret). Each event carries an 'eventId' (also sent as the 'X-Webhook-Id' header) built as '{paymentId}:{status}:{receivedAmount}': it is stable per payment status and amount, and identical across retries and manual resends — use it to deduplicate. A top-up that changes the received amount without changing the status is a new event with a new 'eventId'. Respond with a 2xx within 10 seconds; redirects are not followed and count as a failed delivery, and failed deliveries are retried with backoff.

  • RESTful JSON API
  • SHA-256 Hashed Keys
  • HTTPS Only
EXAMPLE
{
  "event": "payment.confirmed",
  "eventId": "pay_abc123:confirmed:49.99",
  "payment": {
    "id": "pay_abc123",
    "externalId": "order_1042",
    "status": "confirmed",
    "chain": "eth",
    "token": "usdc",
    "expectedAmount": 49.99,
    "receivedAmount": 49.99,
    "txHash": "0xabc...def",
    "createdAt": "2024-03-20T11:58:02Z",
    "updatedAt": "2024-03-20T12:00:00Z"
  },
  "timestamp": "2024-03-20T12:00:00Z"
}

XRP Destination Tags

XRP uses 'Destination Tags' — numeric identifiers that route payments on shared wallets. Every XRP payment session is issued its own unique destination tag, returned as 'xrpDestinationTag' and shown to the payer at checkout, so concurrent sessions on one wallet are matched exactly. A payment sent without the tag (common from exchange withdrawals) is still detected and matched by amount. Use a self-custodied XRP address you control: an exchange deposit address that requires its own fixed tag is not supported, because payers are shown the per-session tag.

  • RESTful JSON API
  • SHA-256 Hashed Keys
  • HTTPS Only
EXAMPLE
// API Response with XRP Destination Tag
{
  "success": true,
  "payment": {
    "id": "pay_xrp789",
    "chain": "xrp",
    "token": "xrp",
    "walletAddress": "rN7...",
    "xrpDestinationTag": "123456789",
    "amount": 50.00,
    "checkoutUrl": "https://chainpayments.io/checkout/pay_xrp789"
  }
}

// Wallet Configuration (Dashboard API) — a classic r-address is required
POST /api/wallets
{
  "chain": "xrp",
  "token": "xrp",
  "address": "rN7..."
}

Supported Chains

We support Ethereum, Bitcoin, Solana, XRP, BNB Smart Chain, Polygon, Tron, Dogecoin, Zcash and Cardano. XRP additionally supports Destination Tags for shared wallet routing. Zcash payments are watched on transparent (t1…/t3…) addresses only — shielded balances can't be observed. All chain and token inputs are case-insensitive.

  • RESTful JSON API
  • SHA-256 Hashed Keys
  • HTTPS Only
EXAMPLE
Supported Chains/Tokens:
- eth  / eth
- eth  / usdc
- eth  / usdt
- sol  / sol
- sol  / usdc
- sol  / usdt
- btc  / btc
- xrp  / xrp  (supports Destination Tags)
- bsc  / bnb
- bsc  / usdc  (BEP20)
- bsc  / usdt  (BEP20)
- polygon / pol
- polygon / usdc
- polygon / usdt
- tron / trx
- tron / usdt  (TRC20)
- doge / doge
- zec  / zec  (transparent addresses only)
- ada  / ada

Note: All chain/token inputs are case-insensitive.

Need more help?

Join our Discord community or reach out to our dedicated developer support team for custom integrations.

API PlaygroundContact DevRel