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]"
  }'

Payment Links

Create reusable payment links. Each visit to the link dynamically generates a unique payment session. Configure optional expiration and maximum payment limits.

RESTful JSON API
SHA-256 Hashed Keys
HTTPS Only

EXAMPLE

curl -X POST "https://chainpayments.io/api/public/v1/payment-links" \
  -H "x-api-key: crypt_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Premium Subscription",
    "amount": 99.99,
    "chain": "sol",
    "token": "usdc"
  }'

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 POST requests to your configured 'webhookUrl' when payment status changes. The payload includes nested paymentLink details if applicable.

RESTful JSON API
SHA-256 Hashed Keys
HTTPS Only

EXAMPLE

{
  "event": "payment.confirmed",
  "payment": {
    "id": "pay_abc123",
    "status": "confirmed",
    "chain": "eth",
    "token": "usdc",
    "expectedAmount": 49.99,
    "receivedAmount": 49.99,
    "txHash": "0xabc...def",
    "paymentLink": {
      "title": "Premium Subscription",
      "description": "Monthly access"
    }
  },
  "timestamp": "2024-03-20T12:00:00Z"
}

XRP Destination Tags

XRP uses 'Destination Tags' — numeric identifiers that route payments on shared wallets. Most exchanges use a single XRP address for all users, with the tag identifying the recipient. When you configure an XRP wallet in your dashboard, you can optionally set a Destination Tag. If set, it will be displayed to payers during checkout and used by our payment engine to accurately match incoming transactions.

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)
POST /api/wallets
{
  "chain": "xrp",
  "token": "xrp",
  "address": "rN7...",
  "xrpTag": "123456789"  // Numeric, up to 10 digits
}

Supported Chains

We support Ethereum, Bitcoin, Solana, and XRP networks. XRP additionally supports Destination Tags for shared wallet routing. 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)

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 Playground Contact DevRel