API Documentation

Dashboard

API Documentation

Accept cryptocurrency payments seamlessly with our powerful and developer-friendly API.

Getting Started

ZehaPay provides a simple RESTful API to integrate cryptocurrency payments into your application. No complex blockchain knowledge required.

Fast Integration

Get started in minutes with our simple API

Secure

HMAC signature verification for webhooks

70+ Cryptos

Support for major cryptocurrencies

Base URL

https://zehapay.com

All API endpoints should be prefixed with this base URL.

Authentication

ZehaPay uses API keys to authenticate requests. You can generate and manage your API keys from your dashboard.

API Key Authentication

Include your API key in the Authorization header using Bearer token authentication.

Authorization: Bearer YOUR_API_KEY

Keep your API keys secure!

Never expose your API keys in client-side code or public repositories. Always make API calls from your backend server.

Create Payment

Create a payment and redirect the customer to select their preferred cryptocurrency.

POST /api/create-payment

Request Parameters

Parameter Type Required Description
amount float Required Payment amount in the specified currency
currency string Optional

ISO 4217 currency code (3 letters). Defaults to USD.

USD, EUR, GBP, JPY, AUD, CAD, CHF, CNY, INR, KRW, BRL, MXN, SGD, HKD, NZD, SEK, NOK, DKK, PLN, TRY, RUB, ZAR, AED, SAR, THB, MYR, IDR, PHP, VND, CZK, HUF, CLP, ARS, COP, PEN, NGN, EGP, PKR, BDT
email string Optional Customer's email address
success_url string Optional Redirect URL after successful payment
fail_url string Optional Redirect URL if payment fails or is cancelled

Code Examples 

curl -X POST https://zehapay.com/api/create-payment \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.00,
    "currency": "EUR",
    "email": "[email protected]",
    "success_url": "https://example.com/success",
    "fail_url": "https://example.com/fail"
  }'

Note: If currency is omitted, it defaults to USD.

$ch = curl_init('https://zehapay.com/api/create-payment');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_API_KEY',
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'amount' => 100.00,
    'email' => '[email protected]',
    'success_url' => 'https://example.com/success',
    'fail_url' => 'https://example.com/fail'
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
const axios = require('axios');

const response = await axios.post('https://zehapay.com/api/create-payment', {
  amount: 100.00,
  email: '[email protected]',
  success_url: 'https://example.com/success',
  fail_url: 'https://example.com/fail'
}, {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
});

console.log(response.data);
import requests

response = requests.post(
    'https://zehapay.com/api/create-payment',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'amount': 100.00,
        'email': '[email protected]',
        'success_url': 'https://example.com/success',
        'fail_url': 'https://example.com/fail'
    }
)

data = response.json()

Response 

{
  "message": "Payment created successfully",
  "payment_id": "M5nQ8rS2tV4wX7yZ",
  "payment_url": "https://zehapay.com/payment/M5nQ8rS2tV4wX7yZ",
  "amount": 100.00,
  "currency": "USD",
  "amount_in_currency": 100.00
}

Create Crypto Payment

Create a payment with a specific cryptocurrency and get the payment address immediately. Perfect for when you want to show the address directly without redirecting to a payment page.

POST /api/create-crypto-payment

Rate Limit

This endpoint is limited to 200 requests per hour. For regular payments (where customer selects crypto), use /api/create-payment which has a 500/hour limit.

Request Parameters

Parameter Type Required Description
amount float Required Payment amount in the specified currency
currency string Optional

ISO 4217 currency code (3 letters). Defaults to USD.

USD, EUR, GBP, JPY, AUD, CAD, CHF, CNY, INR, KRW, BRL, MXN, SGD, HKD, NZD, SEK, NOK, DKK, PLN, TRY, RUB, ZAR, AED, SAR, THB, MYR, IDR, PHP, VND, CZK, HUF, CLP, ARS, COP, PEN, NGN, EGP, PKR, BDT
cryptocurrency string Required

Cryptocurrency symbol. Supported values:

Native Coins (19):

BTC, ETH, BNB, SOL, POL, AVAX, TRX, LTC, DOGE, DASH, BCH, ADA, XRP, ATOM, TON, XMR, ZEC, XLM, SUI

Stablecoins (5):

USDT, USDC, DAI, USDE, PYUSD

Tokens (9):

PAXG, XAUT, ARB, OP, SHIB, LINK, UNI, AAVE, WBTC, WETH
network string Required

Blockchain network code. Supported values:

BTC, ETH, BSC, POL, SOL, AVAXC, TRON, LTC, DOGE, DASH, BCH, ARBITRUM, BASE, OPTIMISM, ADA, XRP, ATOM, TON, XMR, ZEC, XLM, SUI
Code Network Name
BTCBitcoin
ETHEthereum
BSCBNB Chain
POLPolygon
SOLSolana
AVAXCAvalanche C-Chain
TRONTron
LTCLitecoin
DOGEDogecoin
DASHDash
BCHBitcoin Cash
ARBITRUMArbitrum One
BASEBase
OPTIMISMOptimism
ADACardano
XRPXRP Ledger
ATOMCosmos Hub
TONTON
XMRMonero
ZECZcash
XLMStellar
SUISui

Note: Not all cryptocurrencies are available on all networks.
email string Optional Customer's email address
success_url string Optional Redirect URL after successful payment
fail_url string Optional Redirect URL if payment fails or is cancelled

Code Examples 

curl -X POST https://zehapay.com/api/create-crypto-payment \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.00,
    "currency": "EUR",
    "cryptocurrency": "USDT",
    "network": "POL",
    "email": "[email protected]"
  }'

Note: If currency is omitted, it defaults to USD.

$ch = curl_init('https://zehapay.com/api/create-crypto-payment');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_API_KEY',
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'amount' => 100.00,
    'cryptocurrency' => 'USDT',
    'network' => 'POL',
    'email' => '[email protected]'
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
const axios = require('axios');

const response = await axios.post('https://zehapay.com/api/create-crypto-payment', {
  amount: 100.00,
  cryptocurrency: 'USDT',
  network: 'POL',
  email: '[email protected]'
}, {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
});

console.log(response.data);
import requests

response = requests.post(
    'https://zehapay.com/api/create-crypto-payment',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'amount': 100.00,
        'cryptocurrency': 'USDT',
        'network': 'POL',
        'email': '[email protected]'
    }
)

data = response.json()

Response 

{
  "success": true,
  "message": "Crypto payment created successfully",
  "payment": {
    "payment_id": "P3kL9qN7rT2uW4xZ",
    "payment_url": "https://zehapay.com/payment/P3kL9qN7rT2uW4xZ",
    "cryptocurrency": "USDT",
    "network": "POL",
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0",
    "amount": 100.00,
    "currency": "EUR",
    "amount_usd": 100.00,
    "crypto_amount": 99.85,
    "crypto_amount_with_fees": 99.90,
    "minimum_acceptable": 99.80,
    "required_confirmations": 30,
    "expires_at": "2025-01-15T11:30:00Z",
    "expires_in_seconds": 900,
    "memo": null
  }
}

Response Parameters

Parameter Type Description
success boolean Whether the request was successful
message string Human-readable status message
payment object Payment details object (see below)
payment object
Field Type Description
payment_id string Unique payment identifier
payment_url string URL to view payment page
cryptocurrency string Selected cryptocurrency symbol
network string Blockchain network code (e.g., POL, ETH, BSC)
address string Wallet address for payment
amount float Payment amount in the original currency
currency string ISO 4217 currency code (e.g., USD, EUR, TRY)
amount_usd float Payment amount in USD
crypto_amount float Amount in cryptocurrency (excluding fees)
crypto_amount_with_fees float Total crypto amount including fees
minimum_acceptable float Minimum acceptable crypto amount
required_confirmations integer Required blockchain confirmations
expires_at string Payment expiration time (ISO 8601)
expires_in_seconds integer Seconds until payment expires
memo string|null Memo/tag for chains that require it (XRP, XLM, etc.)

Check Payment Status

Check the current status of a payment.

GET /api/check-payment-status/{paymentId}

Code Examples 

curl -X GET https://zehapay.com/api/check-payment-status/K4mR7xP2nQ3sT4vW \
  -H "Authorization: Bearer YOUR_API_KEY"
$paymentId = 'K4mR7xP2nQ3sT4vW';
$ch = curl_init("https://zehapay.com/api/check-payment-status/{$paymentId}");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_API_KEY'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
const axios = require('axios');

const paymentId = 'K4mR7xP2nQ3sT4vW';
const response = await axios.get(
  `https://zehapay.com/api/check-payment-status/${paymentId}`,
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);

console.log(response.data);
import requests

payment_id = 'K4mR7xP2nQ3sT4vW'
response = requests.get(
    f'https://zehapay.com/api/check-payment-status/{payment_id}',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY'
    }
)

data = response.json()

Payment Statuses

Status Description
pending Payment created, no crypto selected
awaiting_payment Waiting for customer payment
waiting_for_confirmations TX detected, waiting for confirmations
completed Payment confirmed successfully
underpaid Paid less than required
expired Payment timeout

Response Examples

pending

Payment created, customer hasn't selected crypto yet.

{
  "success": true,
  "payment_id": "K4mR7xP2nQ3sT4vW",
  "status": "pending",
  "amount": 100.00,
  "currency": "USD",
  "amount_usd": 100.00,
  "payment_url": "https://zehapay.com/payment/K4mR7xP2nQ3sT4vW",
  "email": "[email protected]",
  "metadata": {"order_id": "12345"},
  "created_at": "2025-01-15T10:30:00+00:00"
}
awaiting_payment

Crypto selected, waiting for customer to send payment.

{
  "success": true,
  "payment_id": "K4mR7xP2nQ3sT4vW",
  "status": "awaiting_payment",
  "amount": 100.00,
  "currency": "USD",
  "amount_usd": 100.00,
  "payment_url": "https://zehapay.com/payment/K4mR7xP2nQ3sT4vW",
  "email": "[email protected]",
  "metadata": {"order_id": "12345"},
  "created_at": "2025-01-15T10:30:00+00:00",
  "cryptocurrency": "USDT",
  "blockchain_network": "POL",
  "wallet_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f42123",
  "expected_crypto_amount": 100.15,
  "required_confirmations": 30
}
waiting_for_confirmations

Payment detected on blockchain, waiting for required confirmations.

{
  "success": true,
  "payment_id": "K4mR7xP2nQ3sT4vW",
  "status": "waiting_for_confirmations",
  "amount": 100.00,
  "currency": "USD",
  "amount_usd": 100.00,
  "payment_url": "https://zehapay.com/payment/K4mR7xP2nQ3sT4vW",
  "email": "[email protected]",
  "metadata": {"order_id": "12345"},
  "created_at": "2025-01-15T10:30:00+00:00",
  "cryptocurrency": "USDT",
  "blockchain_network": "POL",
  "wallet_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f42123",
  "expected_crypto_amount": 100.15,
  "required_confirmations": 30,
  "paid_crypto_amount": 100.15,
  "transaction_hash": "0x8f5c2e1a3b4d6789c0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3",
  "confirmations": 12,
  "payment_detected_at": "2025-01-15T10:32:00+00:00"
}
completed

Payment confirmed with required confirmations.

{
  "success": true,
  "payment_id": "K4mR7xP2nQ3sT4vW",
  "status": "completed",
  "amount": 100.00,
  "currency": "USD",
  "amount_usd": 100.00,
  "payment_url": "https://zehapay.com/payment/K4mR7xP2nQ3sT4vW",
  "email": "[email protected]",
  "metadata": {"order_id": "12345"},
  "created_at": "2025-01-15T10:30:00+00:00",
  "cryptocurrency": "USDT",
  "blockchain_network": "POL",
  "wallet_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f42123",
  "expected_crypto_amount": 100.15,
  "required_confirmations": 30,
  "paid_crypto_amount": 100.15,
  "transaction_hash": "0x8f5c2e1a3b4d6789c0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3",
  "confirmations": 30,
  "payment_detected_at": "2025-01-15T10:32:00+00:00",
  "payment_confirmed_at": "2025-01-15T10:35:00+00:00"
}
underpaid

Customer paid less than required amount.

{
  "success": true,
  "payment_id": "A1B2C3D4E5F6G7H8",
  "status": "underpaid",
  "amount": 100.00,
  "currency": "USD",
  "amount_usd": 100.00,
  "payment_url": "https://zehapay.com/payment/A1B2C3D4E5F6G7H8",
  "email": "[email protected]",
  "metadata": {"order_id": "12345"},
  "created_at": "2025-01-15T10:30:00+00:00",
  "cryptocurrency": "ETH",
  "blockchain_network": "ETH",
  "wallet_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f42123",
  "expected_crypto_amount": 0.03125,
  "required_confirmations": 12,
  "paid_crypto_amount": 0.02800,
  "transaction_hash": "0xabc123def456789abc123def456789abc123def456789abc123def456789abcd",
  "confirmations": 12,
  "payment_detected_at": "2025-01-15T10:33:00+00:00",
  "payment_confirmed_at": "2025-01-15T10:35:00+00:00"
}
expired

Payment expired without receiving funds.

{
  "success": true,
  "payment_id": "X1Y2Z3A4B5C6D7E8",
  "status": "expired",
  "amount": 100.00,
  "currency": "USD",
  "amount_usd": 100.00,
  "payment_url": "https://zehapay.com/payment/X1Y2Z3A4B5C6D7E8",
  "email": "[email protected]",
  "metadata": {"order_id": "12345"},
  "created_at": "2025-01-15T10:30:00+00:00"
}

Webhooks

Webhooks notify your server when payment events occur. Configure your webhook URL in the dashboard under Settings.

Events

Event Description
payment.created Payment created via API
payment.processing Detected, waiting for confirmations
payment.completed Confirmed on blockchain
payment.underpaid Paid less than required
payment.expired Expired without funds

Request Headers

Header Value
Content-Type application/json
User-Agent ZehaPay-Webhook/1.0
X-Webhook-Signature HMAC-SHA256 signature
X-Webhook-Event Event type
X-Webhook-Timestamp Unix timestamp

Payload Examples

payment.created

Sent when a payment is created. Payload varies based on endpoint used.

Via /api/create-payment — Customer selects crypto later:

{
  "event": "payment.created",
  "timestamp": "2025-01-15T10:30:00+00:00",
  "payment": {
    "payment_id": "Q3ZKJC-HLRC79-FT5F2W",
    "status": "pending",
    "amount": 100.00,
    "currency": "USD",
    "amount_usd": 100.00,
    "payment_url": "https://zehapay.com/pay/Q3ZKJCHLRC79FT5F2W",
    "email": "[email protected]",
    "metadata": {
      "order_id": "ORD-12345"
    },
    "created_at": "2025-01-15T10:30:00+00:00"
  }
}

Via /api/create-crypto-payment — Crypto pre-selected:

{
  "event": "payment.created",
  "timestamp": "2025-01-15T10:30:00+00:00",
  "payment": {
    "payment_id": "Q3ZKJC-HLRC79-FT5F2W",
    "status": "awaiting_payment",
    "amount": 100.00,
    "currency": "USD",
    "amount_usd": 100.00,
    "payment_url": "https://zehapay.com/pay/Q3ZKJCHLRC79FT5F2W",
    "email": "[email protected]",
    "metadata": {
      "order_id": "ORD-12345"
    },
    "cryptocurrency": "USDT",
    "blockchain_network": "POL",
    "wallet_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f42123",
    "expected_crypto_amount": 100.15,
    "required_confirmations": 30,
    "created_at": "2025-01-15T10:30:00+00:00"
  }
}

payment.processing

Payment detected on blockchain, waiting for confirmations.

{
  "event": "payment.processing",
  "timestamp": "2025-01-15T10:32:00+00:00",
  "payment": {
    "payment_id": "Q3ZKJC-HLRC79-FT5F2W",
    "status": "waiting_for_confirmations",
    "amount": 100.00,
    "currency": "USD",
    "amount_usd": 100.00,
    "payment_url": "https://zehapay.com/pay/Q3ZKJCHLRC79FT5F2W",
    "email": "[email protected]",
    "metadata": {
      "order_id": "ORD-12345"
    },
    "cryptocurrency": "USDT",
    "blockchain_network": "POL",
    "wallet_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f42123",
    "expected_crypto_amount": 100.15,
    "required_confirmations": 30,
    "created_at": "2025-01-15T10:30:00+00:00"
  }
}

payment.completed

Payment confirmed with required confirmations.

{
  "event": "payment.completed",
  "timestamp": "2025-01-15T10:35:00+00:00",
  "payment": {
    "payment_id": "Q3ZKJC-HLRC79-FT5F2W",
    "status": "completed",
    "amount": 100.00,
    "currency": "USD",
    "amount_usd": 100.00,
    "payment_url": "https://zehapay.com/pay/Q3ZKJCHLRC79FT5F2W",
    "email": "[email protected]",
    "metadata": {
      "order_id": "ORD-12345"
    },
    "cryptocurrency": "USDT",
    "blockchain_network": "POL",
    "wallet_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f42123",
    "expected_crypto_amount": 100.15,
    "required_confirmations": 30,
    "paid_crypto_amount": 100.15,
    "transaction_hash": "0x8f5c2e1a3b4d6789c0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3",
    "confirmations": 30,
    "created_at": "2025-01-15T10:30:00+00:00",
    "payment_detected_at": "2025-01-15T10:32:00+00:00",
    "payment_confirmed_at": "2025-01-15T10:35:00+00:00"
  }
}

payment.underpaid

Customer paid less than required. Includes shortfall details.

{
  "event": "payment.underpaid",
  "timestamp": "2025-01-15T10:35:00+00:00",
  "payment": {
    "payment_id": "A1B2C3-D4E5F6-789012",
    "status": "underpaid",
    "amount": 100.00,
    "currency": "USD",
    "amount_usd": 100.00,
    "payment_url": "https://zehapay.com/pay/A1B2C3D4E5F6789012",
    "email": "[email protected]",
    "metadata": {
      "order_id": "ORD-12345"
    },
    "cryptocurrency": "ETH",
    "blockchain_network": "ETH",
    "wallet_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f42123",
    "expected_crypto_amount": 0.03125,
    "required_confirmations": 12,
    "paid_crypto_amount": 0.02800,
    "transaction_hash": "0xabc123def456789...",
    "confirmations": 12,
    "created_at": "2025-01-15T10:30:00+00:00",
    "payment_detected_at": "2025-01-15T10:33:00+00:00",
    "payment_confirmed_at": "2025-01-15T10:35:00+00:00"
  },
  "underpaid_details": {
    "expected_crypto": 0.03125,
    "received_crypto": 0.02800,
    "shortfall_crypto": 0.00325,
    "shortfall_percent": 10.40,
    "expected_usd": 100.00,
    "received_usd": 89.60,
    "shortfall_usd": 10.40,
    "crypto_rate_usd": 3200.00
  }
}

payment.expired

Payment expired without receiving funds.

{
  "event": "payment.expired",
  "timestamp": "2025-01-15T10:45:00+00:00",
  "payment": {
    "payment_id": "X1Y2Z3-A4B5C6-789012",
    "status": "expired",
    "amount": 100.00,
    "currency": "USD",
    "amount_usd": 100.00,
    "payment_url": "https://zehapay.com/pay/X1Y2Z3A4B5C6789012",
    "email": "[email protected]",
    "metadata": {
      "order_id": "ORD-12345"
    },
    "created_at": "2025-01-15T10:30:00+00:00"
  }
}

Signature Verification

Verify the X-Webhook-Signature header to ensure requests are from ZehaPay.

$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
$secret = 'your_webhook_secret';

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

if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    die('Invalid signature');
}

$data = json_decode($payload, true);

Best Practices

  • - Return 2xx status within 10 seconds
  • - Process webhooks asynchronously if needed
  • - Use payment_id as idempotency key to handle duplicates
  • - Webhooks retry 3 times with exponential backoff (5min, 15min, 30min)

Error Handling

ZehaPay uses standard HTTP response codes to indicate the success or failure of API requests.

2xx Success

Request was successful

4xx Client Error

Invalid request or authentication issue

5xx Server Error

Something went wrong on our end - please retry

Error Response Format 

{
  "success": false,
  "error": {
    "code": "invalid_api_key",
    "message": "The API key provided is invalid or has been revoked"
  }
}
Code Status Description
200 OK Request successful
400 Bad Request Invalid request parameters
401 Unauthorized Invalid or missing API key
404 Not Found Resource not found
429 Too Many Requests Rate limit exceeded
500 Server Error Server error - please retry

Need help? Contact our support team or check out more resources.

Go to Dashboard Back to Home