Integrate CoinAvio
into your platform.

GET https://api.coinavio.com/v1/account
Authorization: Bearer <apiKey>

{
  "merchant": { "id": "cm1…", "name": "Demo Store", "status": "ACTIVE", "feeBps": 0, "feePercent": "0.00" },
  "apiKey": { "test": false, "mode": "live" },
  "webhook": { "configured": false, "url": null },
  "currencies": [ { "currency": "USDT", "network": "BSC", "live": true, … } ]
}

Swipe within the code to read long lines.

curl -X POST "https://api.coinavio.com/v1/invoices" \
  -H "Authorization: Bearer $MERCHANT_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "priceAmount": "25.00",
    "orderId": "shop-17:1048",
    "description": "Balance top-up #1048",
    "successUrl": "https://panel.example.com/addfunds?payment=1048",
    "cancelUrl": "https://panel.example.com/addfunds",
    "callbackUrl": "https://platform.example.com/coinavio/webhook/shop-17",
    "buyerPaysFee": false
  }'

# 201 → { "id": "cmgq…", "orderId": "shop-17:1048", "status": "NEW", "testMode": false,
#         "price": { "amount": "25", "currency": "USD", "baseAmount": "25", … },
#         "checkoutUrl": "https://coinavio.com/pay/cmgq…", "expiresAt": "…", …, "warnings": [] }

Swipe within the code to read long lines.

"successUrl": "https://shop.example.com/",
"warnings": [
  { "code": "RETURN_URL_REPLACED", "field": "successUrl", "message": "…" }
]

Swipe within the code to read long lines.

<?php
// Same check as the reference verifier in the CoinAvio docs, plus $expectedMode:
// a merchant on a test key only accepts test events, a live key only live events.
function verify_coinavio_webhook($secret, $signature, $rawBody, $mode, $modeSignature, $expectedMode = 'live') {
    if (!$secret || $mode !== $expectedMode) return false;
    $pattern = '/^t=([0-9]+),v1=([a-fA-F0-9]{64})$/D';
    if (!is_string($signature) || !is_string($modeSignature) ||
        !preg_match($pattern, $signature, $a) ||
        !preg_match($pattern, $modeSignature, $b) || $a[1] !== $b[1]) return false;
    if (abs(microtime(true) * 1000 - (float) $a[1]) > 300000) return false;
    $legacy = hash_hmac('sha256', $a[1] . '.' . $rawBody, $secret);
    $bound = hash_hmac('sha256', $a[1] . '.' . $mode . '.' . $rawBody, $secret);
    if (!hash_equals($legacy, strtolower($a[2])) ||
        !hash_equals($bound, strtolower($b[2]))) return false;
    $event = json_decode($rawBody, true);
    return is_array($event) && is_string($event['type'] ?? null) &&
        strpos($event['type'], 'invoice.') === 0 &&
        ($event['data']['invoice']['testMode'] ?? null) === ($expectedMode === 'test');
}

// $tenant = the merchant site identified by your callbackUrl path.
$expectedMode = strpos($tenant['api_key'], 'ck_test_') === 0 ? 'test' : 'live';
$rawBody = file_get_contents('php://input');
if ($rawBody === false || !verify_coinavio_webhook(
    $tenant['webhook_secret'], $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '',
    $rawBody, $_SERVER['HTTP_X_COINAVIO_MODE'] ?? '',
    $_SERVER['HTTP_X_COINAVIO_MODE_SIGNATURE'] ?? '', $expectedMode
)) { http_response_code(400); exit; }
$event = json_decode($rawBody, true, 512, JSON_THROW_ON_ERROR);
// Dedupe on $event['id'], match the order, credit only PAID/OVERPAID, then return 200.
http_response_code(200);

Swipe within the code to read long lines.

import { createHmac, timingSafeEqual } from 'node:crypto';

// Same check as the reference verifier in the CoinAvio docs, plus expectedMode:
// a merchant on a test key only accepts test events, a live key only live events.
export function verifyWebhook(secret, signature, rawBody, mode, modeSignature, expectedMode = 'live') {
  if (!secret || mode !== expectedMode) return false;
  const pattern = /^t=([0-9]+),v1=([a-fA-F0-9]{64})$/;
  const legacy = typeof signature === 'string' && pattern.exec(signature);
  const signedMode = typeof modeSignature === 'string' && pattern.exec(modeSignature);
  if (!legacy || !signedMode || legacy[1] !== signedMode[1]) return false;
  const timestampMs = Number(legacy[1]);
  if (!Number.isSafeInteger(timestampMs) ||
      Math.abs(Date.now() - timestampMs) > 300_000) return false;
  const valid = (prefix, hex) => {
    const expected = createHmac('sha256', secret).update(prefix).update(rawBody).digest();
    return timingSafeEqual(expected, Buffer.from(hex, 'hex'));
  };
  if (!valid(legacy[1] + '.', legacy[2]) ||
      !valid(legacy[1] + '.' + mode + '.', signedMode[2])) return false;
  try {
    const event = JSON.parse(rawBody.toString('utf8'));
    return typeof event.type === 'string' && event.type.startsWith('invoice.') &&
      event.data?.invoice?.testMode === (expectedMode === 'test');
  } catch { return false; }
}

// rawBody must be the exact bytes (a Buffer), read BEFORE any JSON middleware.
// const expectedMode = tenant.apiKey.startsWith('ck_test_') ? 'test' : 'live';
// if (!verifyWebhook(tenant.webhookSecret, req.headers['x-webhook-signature'], rawBody,
//     req.headers['x-coinavio-mode'], req.headers['x-coinavio-mode-signature'], expectedMode)) {
//   res.writeHead(400); res.end(); return;
// }

Swipe within the code to read long lines.

GET https://api.coinavio.com/v1/invoices/by-order/shop-17%3A1048
Authorization: Bearer <apiKey>

Swipe within the code to read long lines.

<?php
// coinavio.php: one-file CoinAvio integration for a platform that serves many merchants.
// PHP 7.4+ with the curl, json and PDO extensions. Serve it over HTTPS only.
//
//   POST coinavio.php?action=pay&tenant=<id>      your add-funds form (field: amount, in USD)
//   POST coinavio.php?action=webhook&tenant=<id>  CoinAvio webhooks (sent to the callbackUrl)
//
// A tenant is one merchant site on your platform. Its API key and webhook secret are the
// two values the merchant pasted into your settings screen. Tables used below:
//   tenants(id, domain, api_key, webhook_secret, buyer_pays_fee)
//   payments(id, tenant_id, user_id, amount_usd, status, invoice_id)  status: pending|completed|hold|failed
//   users(id, balance_cents)
//   coinavio_events(event_id PRIMARY KEY)
declare(strict_types=1);

const COINAVIO_API = 'https://api.coinavio.com';
const CALLBACK_BASE = 'https://platform.example.com/coinavio.php';

function db(): PDO
{
    static $pdo = null;
    if ($pdo === null) {
        $pdo = new PDO((string) getenv('DB_DSN'), (string) getenv('DB_USER'), (string) getenv('DB_PASS'), [
            PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
            PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
        ]);
    }
    return $pdo;
}

function load_tenant(string $tenantId): array
{
    $stmt = db()->prepare('SELECT id, domain, api_key, webhook_secret, buyer_pays_fee FROM tenants WHERE id = ?');
    $stmt->execute([$tenantId]);
    $tenant = $stmt->fetch();
    if (!$tenant) {
        http_response_code(404);
        exit;
    }
    return $tenant;
}

// The key prefix tells you the mode: ck_test_... is test, ck_live_... is live.
function key_mode(string $apiKey): string
{
    return strpos($apiKey, 'ck_test_') === 0 ? 'test' : 'live';
}

// "25", "25.5" or "25.50" -> 2500, 2550, 2550. Returns null for anything else.
function usd_cents(string $amount): ?int
{
    if (!preg_match('/^([0-9]{1,15})(?:[.]([0-9]+))?$/D', $amount, $m)) {
        return null;
    }
    $fraction = rtrim($m[2] ?? '', '0');
    if (strlen($fraction) > 2) {
        return null;
    }
    return (int) $m[1] * 100 + (int) str_pad($fraction, 2, '0');
}

function coinavio_request(string $apiKey, string $method, string $path, ?array $body = null): array
{
    $headers = ['Authorization: Bearer ' . $apiKey, 'Accept: application/json'];
    $options = [CURLOPT_CUSTOMREQUEST => $method, CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 30];
    if ($body !== null) {
        $headers[] = 'Content-Type: application/json';
        $options[CURLOPT_POSTFIELDS] = json_encode($body, JSON_THROW_ON_ERROR);
    }
    $options[CURLOPT_HTTPHEADER] = $headers;
    $ch = curl_init(COINAVIO_API . $path);
    curl_setopt_array($ch, $options);
    $raw = curl_exec($ch);
    $status = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
    if (!is_string($raw)) {
        throw new RuntimeException('CoinAvio request failed: ' . curl_error($ch));
    }
    $data = json_decode($raw, true);
    if ($status < 200 || $status >= 300 || !is_array($data)) {
        $message = is_array($data) && isset($data['message']) ? json_encode($data['message']) : 'HTTP ' . $status;
        throw new RuntimeException('CoinAvio error: ' . $message);
    }
    return $data;
}

// Same check as the reference verifier in the CoinAvio docs, plus $expectedMode:
// a merchant on a test key only accepts test events, a live key only live events.
function verify_coinavio_webhook($secret, $signature, $rawBody, $mode, $modeSignature, $expectedMode = 'live') {
    if (!$secret || $mode !== $expectedMode) return false;
    $pattern = '/^t=([0-9]+),v1=([a-fA-F0-9]{64})$/D';
    if (!is_string($signature) || !is_string($modeSignature) ||
        !preg_match($pattern, $signature, $a) ||
        !preg_match($pattern, $modeSignature, $b) || $a[1] !== $b[1]) return false;
    if (abs(microtime(true) * 1000 - (float) $a[1]) > 300000) return false;
    $legacy = hash_hmac('sha256', $a[1] . '.' . $rawBody, $secret);
    $bound = hash_hmac('sha256', $a[1] . '.' . $mode . '.' . $rawBody, $secret);
    if (!hash_equals($legacy, strtolower($a[2])) ||
        !hash_equals($bound, strtolower($b[2]))) return false;
    $event = json_decode($rawBody, true);
    return is_array($event) && is_string($event['type'] ?? null) &&
        strpos($event['type'], 'invoice.') === 0 &&
        ($event['data']['invoice']['testMode'] ?? null) === ($expectedMode === 'test');
}

function start_payment(array $tenant): void
{
    session_start();
    $userId = (int) ($_SESSION['user_id'] ?? 0); // your signed-in user; add your usual CSRF check
    $amount = trim((string) ($_POST['amount'] ?? '')); // USD, already converted from the panel currency
    $cents = preg_match('/^[0-9]+([.][0-9]{1,2})?$/D', $amount) ? usd_cents($amount) : null;
    if ($userId <= 0 || $cents === null || $cents < 50) {
        http_response_code(422);
        exit('Enter an amount of at least 0.50 USD.');
    }
    $pdo = db();
    $pdo->prepare('INSERT INTO payments (tenant_id, user_id, amount_usd, status) VALUES (?, ?, ?, ?)')
        ->execute([$tenant['id'], $userId, $amount, 'pending']);
    $paymentId = (string) $pdo->lastInsertId();
    $returnUrl = 'https://' . $tenant['domain'] . '/addfunds'; // other domains are replaced (see warnings)
    $invoice = coinavio_request((string) $tenant['api_key'], 'POST', '/v1/invoices', [
        'priceAmount' => $amount,
        'orderId' => $tenant['id'] . ':' . $paymentId, // site prefix: no collisions between sites
        'description' => 'Balance top-up #' . $paymentId,
        'successUrl' => $returnUrl . '?payment=' . $paymentId,
        'cancelUrl' => $returnUrl,
        'callbackUrl' => CALLBACK_BASE . '?action=webhook&tenant=' . rawurlencode((string) $tenant['id']),
        'buyerPaysFee' => (bool) $tenant['buyer_pays_fee'],
    ]);
    $pdo->prepare('UPDATE payments SET invoice_id = ? WHERE id = ?')->execute([$invoice['id'], $paymentId]);
    foreach ($invoice['warnings'] ?? [] as $warning) {
        // For example RETURN_URL_REPLACED: the panel domain is not verified in the merchant's CoinAvio account.
        error_log('CoinAvio ' . $warning['code'] . ' for ' . $warning['field'] . ' (tenant ' . $tenant['id'] . ')');
    }
    header('Location: ' . $invoice['checkoutUrl'], true, 303);
    exit;
}

function handle_webhook(array $tenant): void
{
    $rawBody = file_get_contents('php://input'); // the exact bytes, before any JSON parsing
    if (!is_string($rawBody) || !verify_coinavio_webhook(
        (string) $tenant['webhook_secret'], $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '',
        $rawBody, $_SERVER['HTTP_X_COINAVIO_MODE'] ?? '',
        $_SERVER['HTTP_X_COINAVIO_MODE_SIGNATURE'] ?? '', key_mode((string) $tenant['api_key'])
    )) {
        http_response_code(400);
        exit;
    }
    $event = json_decode($rawBody, true, 512, JSON_THROW_ON_ERROR);
    $invoice = $event['data']['invoice'];
    $prefix = $tenant['id'] . ':';
    $orderId = (string) ($invoice['orderId'] ?? '');
    if (strpos($orderId, $prefix) !== 0) {
        http_response_code(200); // not a top-up created by this file (for example a payment link)
        exit;
    }
    $paymentId = substr($orderId, strlen($prefix));
    $pdo = db();
    try {
        $pdo->beginTransaction();
        try {
            // Each event id is processed once: the primary key rejects duplicates.
            $pdo->prepare('INSERT INTO coinavio_events (event_id) VALUES (?)')->execute([(string) $event['id']]);
        } catch (PDOException $e) {
            // SQLSTATE class 23 means this event id is already stored; anything else is a real error.
            if (substr((string) $e->getCode(), 0, 2) !== '23') {
                throw $e;
            }
            $pdo->rollBack();
            http_response_code(200); // duplicate delivery, already handled
            exit;
        }
        $stmt = $pdo->prepare('SELECT id, user_id, amount_usd, invoice_id FROM payments WHERE id = ? AND tenant_id = ?');
        $stmt->execute([$paymentId, $tenant['id']]);
        $payment = $stmt->fetch();
        if ($payment && ($payment['invoice_id'] === null || $payment['invoice_id'] === $invoice['id'])) {
            $type = (string) $event['type'];
            $status = (string) $invoice['status'];
            if (in_array($type, ['invoice.paid', 'invoice.overpaid'], true) && in_array($status, ['PAID', 'OVERPAID'], true)) {
                // Credit the USD amount you asked for, never the crypto amount.
                $credit = usd_cents((string) $invoice['price']['baseAmount']);
                $ok = $credit !== null && $credit === usd_cents((string) $payment['amount_usd']);
                // The status guard makes crediting happen at most once, whatever the event order.
                $claim = $pdo->prepare("UPDATE payments SET status = ?, invoice_id = ? WHERE id = ? AND status IN ('pending', 'hold')");
                $claim->execute([$ok ? 'completed' : 'hold', $invoice['id'], $payment['id']]);
                if ($ok && $claim->rowCount() === 1) {
                    $pdo->prepare('UPDATE users SET balance_cents = balance_cents + ? WHERE id = ?')
                        ->execute([$credit, $payment['user_id']]);
                }
            } elseif ($type === 'invoice.underpaid') {
                // Partial payment: hold for the merchant. If they accept it, invoice.paid follows.
                $pdo->prepare("UPDATE payments SET status = 'hold' WHERE id = ? AND status = 'pending'")
                    ->execute([$payment['id']]);
            } elseif (in_array($type, ['invoice.expired', 'invoice.cancelled'], true)) {
                $pdo->prepare("UPDATE payments SET status = 'failed' WHERE id = ? AND status = 'pending'")
                    ->execute([$payment['id']]);
            }
            // invoice.pending, invoice.confirming and informational events change nothing here.
        }
        $pdo->commit();
    } catch (Throwable $e) {
        if ($pdo->inTransaction()) {
            $pdo->rollBack();
        }
        error_log('CoinAvio webhook failed: ' . $e->getMessage());
        http_response_code(500); // CoinAvio retries the delivery
        exit;
    }
    http_response_code(200);
}

$tenant = load_tenant((string) ($_GET['tenant'] ?? ''));
$action = (string) ($_GET['action'] ?? '');
if ($_SERVER['REQUEST_METHOD'] === 'POST' && $action === 'pay') {
    start_payment($tenant);
} elseif ($_SERVER['REQUEST_METHOD'] === 'POST' && $action === 'webhook') {
    handle_webhook($tenant);
} else {
    http_response_code(404);
}

Swipe within the code to read long lines.