Developer Documentation

Welcome

CryptoPay helps you accept crypto payments, create invoice links, run payouts, and receive signed webhook events.

Environments

Base URL

https://cryptopay.africa/api/v1

API Credentials

Create API keys from merchant dashboard, then use the public key in headers and secret key for HMAC signing.

Authentication

Every request must include these headers:

• X-API-KEY
• X-API-SIGNATURE
• X-API-TIMESTAMP
• X-API-NONCE

signature_payload = timestamp + "." + nonce + "." + sha256(raw_body)
signature = HMAC_SHA256(signature_payload, secret_key)

Idempotency

For POST endpoints, send Idempotency-Key to safely retry requests without duplicate resources.

Invoices

• POST /api/v1/invoices - Create invoice
• GET /api/v1/invoices - List invoices
• GET /api/v1/invoices/{id} - Get invoice

Payouts

• POST /api/v1/payouts - Create single payout
• POST /api/v1/payouts/batch - Create batch payout
• POST /api/v1/payouts/batch/csv - Upload CSV batch
• GET /api/v1/payouts/{id} - Get payout

Supported rails: TRON-USDT, ETH-USDT, BSC-USDT, TON-USDT, TON-native.

Payout Readiness & Validation

Before chain broadcast, CryptoPay validates destination format and treasury fee balance so merchants receive clear operational errors quickly.

• TRON invalid destination format -> Invalid TRON destination address format
• ETH gas shortfall -> Insufficient ETH in treasury wallet for gas fees
• BSC gas shortfall -> Insufficient BNB in treasury wallet for gas fees
• TON reserve shortfall -> Insufficient TON in treasury wallet for payout amount + network fee reserve

TON native payouts now finalize to terminal states (completed or failed) and no longer remain stuck in processing.

Webhooks

• POST /api/v1/webhooks - Register endpoint
• POST /api/v1/webhooks/{id}/rotate-secret - Rotate secret
• POST /api/v1/webhooks/test - Send test event

Verify webhook signature from header X-CryptoPay-Signature.