ChainPay API v1

The ChainPay API lets you create crypto payment invoices, derive wallet addresses from xPub keys, and receive real-time payment webhooks. Base URL: https://api.chainpay.store/v1

✓ Sandbox available at https://sandbox.chainpay.store/v1 — use test API keys, no real funds required.

Authentication

All API requests require a Bearer token in the Authorization header. Get your key from the merchant dashboard.

// Authorization header
Authorization: Bearer cp_live_your_api_key_here
Content-Type: application/json

Live keys start with cp_live_, sandbox keys with cp_test_.

Create Invoice

Creates a new payment invoice for a given fiat amount. Returns a crypto amount, receive address, and payment URI.

POST /invoices Creates a payment invoice

Request Parameters

Parameter	Type	Description
order_id required	string	Your internal order ID or reference
coin required	string	Coin key: `BTC`, `LTC`, `ETH`, etc.
amount required	number	Fiat amount to charge (e.g. 49.99)
currency required	string	Fiat currency code: `USD`, `EUR`, `GBP`
timeout_min optional	integer	Invoice expiry in minutes (default: 15)
metadata optional	object	Any additional data to store with the invoice

// POST /v1/invoices
{
  "order_id": "wc_order_12345",
  "coin": "BTC",
  "amount": 49.99,
  "currency": "USD",
  "timeout_min": 15
}

Response

{
  "invoice_id": "cp_inv_6a7f2b...",
  "order_id": "wc_order_12345",
  "coin": "BTC",
  "network": "Bitcoin Mainnet",
  "address": "bc1q9x3e...",
  "amount_crypto": "0.00078423",
  "amount_fiat": 49.99,
  "fiat_currency": "USD",
  "exchange_rate": 63769.42,
  "uri": "bitcoin:bc1q9x3e...?amount=0.00078423&label=MyStore",
  "status": "pending",
  "expires_at": "2025-04-01T12:30:00Z",
  "created_at": "2025-04-01T12:15:00Z"
}

Get Invoice

GET /invoices/{invoice_id} Retrieve invoice by ID

// GET /v1/invoices/cp_inv_6a7f2b
// Response: same structure as create, with updated status
{
  "invoice_id": "cp_inv_6a7f2b...",
  "status": "confirmed",
  "tx_hash": "a1b2c3d4...",
  "confirmations": 3
}

Payment Statuses

Status	Meaning	Action
pending	string	Awaiting payment — show QR / address to customer
detected	string	Payment seen on-chain, waiting for confirmations
confirmed	string	Required confirmations reached — fulfil order
underpaid	string	Less than expected received — send recovery email
expired	string	Invoice timed out without payment

Webhook Events

ChainPay sends signed POST requests to your webhook URL on every payment state change. All payloads are JSON with an X-ChainPay-Signature header (HMAC-SHA256).

Event	Fired when
payment.detected	Transaction seen on-chain (unconfirmed)
payment.confirmed	Required confirmations reached
payment.underpaid	Less than required amount received
invoice.expired	Invoice timeout passed without payment
test.ping	Manual test webhook from dashboard

Signature Verification

// PHP: verify HMAC-SHA256 signature
$payload = file_get_contents('php://input');
$sig     = $_SERVER['HTTP_X_CHAINPAY_SIGNATURE'];
$secret  = 'your_webhook_secret';

$expected = hash_hmac('sha256', $payload, $secret);

if (!hash_equals($expected, $sig)) {
    http_response_code(401);
    exit('Unauthorized');
}

Verify License

POST /license/verify Activate and verify a Pro license key

// POST /v1/license/verify
{
  "license_key": "cp_lic_your_key_here",
  "domain": "https://yourstore.com",
  "plugin_ver": "1.0.0"
}

// Response (success)
{
  "active": true,
  "plan": "pro",
  "expires": "2026-04-01",
  "coins_unlocked": 14
}

WooCommerce Plugin — Quick Start

Install the ChainPay plugin in 3 steps:

# 1. Download and install via WP Admin
#    Plugins → Add New → Upload Plugin → chainpay-payment-gateway.zip

# 2. Activate the plugin

# 3. Configure: ChainPay → General
#    - Enter your API key (optional for BTC/LTC)
#    - Go to ChainPay → Wallets → enter xPub for BTC
#    - Go to WooCommerce → Settings → Payments → enable ChainPay

PHP SDK

// Install via Composer
composer require chainpay/sdk

// Usage
use ChainPay\Client;

$client = new Client('cp_live_your_key');

// Create invoice
$invoice = $client->invoices()->create([
    'order_id'  => 'ord_123',
    'coin'      => 'BTC',
    'amount'    => 49.99,
    'currency'  => 'USD',
]);

echo $invoice['address']; // bc1q9x3e...

Node.js SDK

// Install
npm install @chainpay/sdk

// Usage
import { ChainPay } from '@chainpay/sdk';

const client = new ChainPay({ apiKey: 'cp_live_your_key' });

// Create invoice
const invoice = await client.invoices.create({
  orderId:  'ord_123',
  coin:     'BTC',
  amount:   49.99,
  currency: 'USD',
});

console.log(invoice.address); // bc1q9x3e...

💡 Need help? Email support@chainpay.store or join our Discord community.