API Documentation

Integrate Zypher payments into your application. Test endpoints directly from this page.

API Key

API Secret

Base URL

Authentication

All API requests require two headers: your API key and an HMAC-SHA256 signature of the request body.

Required Headers

X-API-KeyYour store API key (UUID format)

X-API-SignHMAC-SHA256 signature of the JSON body, signed with your API secret. For GET requests, sign an empty string.

request-headers

X-API-Key: your-api-key
X-API-Sign: hmac-sha256-signature

sign-request.js

const crypto = require('crypto');
const apiSecret = 'your-api-secret';

// POST: sign the JSON body
const body = JSON.stringify({ currency: 'USDT', network: 'tron', amount: '100.00' });
const signature = crypto.createHmac('sha256', apiSecret).update(body).digest('hex');

// GET: sign empty string
const getSignature = crypto.createHmac('sha256', apiSecret).update('').digest('hex');

Security

The API secret is shown only once when the store is created or the key is regenerated. Store it securely. If compromised, regenerate immediately from the Merchant Dashboard.

Create Invoice

POST/api/v1/invoice

Two modes: specify exact crypto amount, or set a fiat amount and let the customer choose cryptocurrency on the payment page.

Option A — Crypto Invoice

Specify exact crypto currency, network, and amount. Deposit address is generated immediately.

crypto-invoice.json

{
  "currency": "USDT",
  "network": "tron",
  "amount": "100.00",
  "orderId": "order-123",
  "metadata": { "customer": "[email protected]" }
}

Option B — Fiat Invoice

Recommended

Set a fiat amount (e.g. $50 USD). The customer picks their preferred coin on the payment page. Crypto amount is calculated at current market rates.

fiat-invoice.json

{
  "fiatAmount": "50.00",
  "fiatCurrency": "USD",
  "orderId": "order-456"
}

Response

response.json

{
  "id": "uuid-invoice-id",
  "storeId": "uuid-store-id",
  "orderId": "order-123",
  "currency": "USDT",       // null for fiat invoices
  "network": "tron",        // null for fiat invoices
  "amount": "100.00",       // null for fiat invoices
  "fiatAmount": null,        // "50.00" for fiat invoices
  "fiatCurrency": null,      // "USD" for fiat invoices
  "depositAddress": "T...", // null for fiat invoices
  "status": "PENDING",
  "expiresAt": "2026-01-01T00:30:00.000Z",
  "paymentUrl": "/pay/uuid-invoice-id",
  "createdAt": "2026-01-01T00:00:00.000Z"
}

cURL Examples

crypto-invoice.sh

BODY='{"currency":"USDT","network":"tron","amount":"100.00","orderId":"order-123"}'
SIGN=$(echo -n "$BODY" | openssl dgst -sha256 -hmac "your-api-secret" | awk '{print $2}')

curl -X POST https://zypher.exchange/api/v1/invoice \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -H "X-API-Sign: $SIGN" \
  -d "$BODY"

fiat-invoice.sh

BODY='{"fiatAmount":"50.00","fiatCurrency":"USD","orderId":"order-456"}'
SIGN=$(echo -n "$BODY" | openssl dgst -sha256 -hmac "your-api-secret" | awk '{print $2}')

curl -X POST https://zypher.exchange/api/v1/invoice \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -H "X-API-Sign: $SIGN" \
  -d "$BODY"

Get Invoice

GET/api/v1/invoice/:id

Retrieve details and current status of an invoice.

response.json

{
  "id": "uuid-invoice-id",
  "status": "PAID",
  "currency": "USDT",
  "network": "tron",
  "amount": "100.00",
  "paidAmount": "100.00",
  "depositAddress": "T...",
  "txHash": "0x...",
  "paidAt": "2026-01-01T00:15:00.000Z",
  "expiresAt": "2026-01-01T00:30:00.000Z"
}

Webhooks

Receive real-time payment notifications via HTTP POST.

How it works

When an invoice status changes, Zypher sends a POST request to your webhook URL with the full invoice data. Configure your webhook URL in the Merchant Dashboard.

webhook-payload.json

{
  "event": "invoice.paid",
  "data": {
    "id": "uuid-invoice-id",
    "storeId": "uuid-store-id",
    "orderId": "order-123",
    "currency": "USDT",
    "network": "tron",
    "amount": "100.00",
    "paidAmount": "100.00",
    "fiatAmount": "50.00",
    "fiatCurrency": "USD",
    "status": "PAID",
    "txHash": "0x...",
    "paidAt": "2026-01-01T00:15:00.000Z"
  }
}

Signature Verification

Each webhook includes an X-Webhook-Signature header — HMAC-SHA256 of the raw body, signed with your API secret.

verify-webhook.js

const crypto = require('crypto');

function verifyWebhook(body, signature, apiSecret) {
  const expected = crypto
    .createHmac('sha256', apiSecret)
    .update(body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Invoice Statuses

PENDINGInvoice created, awaiting payment

CONFIRMINGPayment detected, waiting for confirmations

PAIDPayment confirmed and credited

OVERPAIDConfirmed — customer sent more than required

UNDERPAIDCustomer sent less than required

EXPIREDInvoice expired without full payment

Supported Currencies

Currency	API Value	Networks
ETH	`ETH`	EthereumBaseArbitrum
USDT	`USDT`	EthereumTronBSCTON
USDC	`USDC`	EthereumBaseArbitrumBSC
BNB	`BNB`	BSC
TRX	`TRX`	Tron
TON	`TON`	TON
BTC	`BTC`	Bitcoin
LTC	`LTC`	Litecoin
SOL	`SOL`	Solana
DOGE	`DOGE`	Dogecoin
DAI	`DAI`	EthereumBaseArbitrumBSC

Network API Values

"ethereum""base""arbitrum""bsc""tron""ton""bitcoin""litecoin""solana""dogecoin"

Rate Limits

Create Invoice: 10 requests / minute

Get Invoice: 30 requests / minute