API documentation

PayHook is a non-custodial crypto payment API. Your customer's funds settle directly to the wallet you control — PayHook watches the chain and POSTs you an HMAC-signed event when a payment confirms. This page covers the full integration in one read.

Quickstart

curl -X POST https://api.payhook.app/api/v1/payments/ \
  -H "X-API-Key: pk_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "amount_usd_cents": 5000,
    "network": "bsc",
    "currency": "usdt",
    "external_order_id": "order-123",
    "redirect_url": "https://merchant.com/orders/123/thanks"
  }'

Authentication

Every request carries an X-API-Key header with your PayHook secret key (format pk_<hex>). Keys are scoped per merchant; rotate at /api-keys if you suspect a leak — the old key 401s immediately.

Create a payment

Creates a payment and returns a hosted-checkout URL. PayHook picks an available address from your pool, locks it for the lifetime of the payment (default 30 minutes), and watches the chain for an inbound transfer of expected_crypto_amount. Returns 201 Created.

Request body

Example request

{
  "amount_usd_cents": 5000,
  "network": "bsc",
  "currency": "usdt",
  "external_order_id": "order-9837",
  "customer_email": "[email protected]",
  "redirect_url": "https://merchant.com/orders/9837/thanks",
  "metadata": { "sku": "GOLD-PLAN" }
}

Response body

Returned on create and on every retrieve. The same shape is replayed in the payment.* webhook event body.

Example response

{
  "payment_number": "PAY-2026-000123",
  "status": "pending",
  "network": "bsc",
  "currency": "usdt",
  "amount_usd_cents": 5000,
  "expected_crypto_amount": "50.000000",
  "actual_crypto_amount": null,
  "assigned_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f7E5a3",
  "tx_hash": "",
  "confirmations": 0,
  "external_order_id": "order-9837",
  "customer_email": "[email protected]",
  "redirect_url": "https://merchant.com/orders/9837/thanks",
  "metadata": { "sku": "GOLD-PLAN" },
  "payment_token": "a8f3b2c1...d7e9",
  "checkout_url": "https://app.payhook.app/pay/a8f3b2c1...d7e9",
  "expires_at": "2026-05-24T12:05:00Z",
  "confirmed_at": null,
  "created_at": "2026-05-24T11:35:00Z"
}

Errors

Retrieve a payment

Returns the same response shape as Create, with status, tx_hash, confirmations, actual_crypto_amount, and confirmed_at reflecting the latest on-chain state.

Cross-merchant lookups return 404 Not Found — a payment number you didn't create looks identical to one that doesn't exist.

Idempotency

Send Idempotency-Key: <opaque> on POST /api/v1/payments/ to make retries safe. A request with the same key from the same merchant within 24 hours returns the original payment instead of creating a duplicate. Use a UUID per logical operation (one per order, not one per HTTP attempt).

The replay reflects live status — if the original payment has confirmed since, the replay returns the confirmed row.

Webhooks

When a payment confirms, PayHook POSTs a JSON body to your endpoint with these headers:

Body shape:

{
  "event": "payment.confirmed",
  "payment_id": "PAY-20260514-ABC123",
  "external_order_id": "order-123",
  "amount": "50.000000",
  "currency": "USDT",
  "chain": "BNB Smart Chain",
  "tx_hash": "0x...",
  "confirmed_at": "2026-05-14T12:34:56+00:00"
}

Verify a signature

The signature is HMAC-SHA256(secret, "{timestamp}.{raw_body}") — the timestamp is the integer in the t= field of the header. Reject if it's more than 5 minutes off; that prevents replay of an intercepted event long after the fact.

Sample verifier in your language:

const crypto = require('crypto');

// Express handler — capture raw body via express.raw({ type: 'application/json' }).
function verifyPayhookSignature(rawBody, header, secret, toleranceSec = 300) {
  const parts = Object.fromEntries(
    header.split(',').map(p => p.split('=').map(s => s.trim()))
  );
  if (!parts.t || !parts.v1) return false;

  const ts = parseInt(parts.t, 10);
  if (Math.abs(Date.now() / 1000 - ts) > toleranceSec) return false;

  const signed = `${ts}.${rawBody}`;
  const expected = crypto.createHmac('sha256', secret).update(signed).digest('hex');

  try {
    return crypto.timingSafeEqual(
      Buffer.from(expected, 'hex'),
      Buffer.from(parts.v1, 'hex')
    );
  } catch {
    return false;
  }
}

import hmac, hashlib, time

def verify_payhook_signature(raw_body: bytes, header: str, secret: str,
                              tolerance_sec: int = 300) -> bool:
    parts = {}
    for piece in header.split(","):
        k, _, v = piece.partition("=")
        if k and v:
            parts[k.strip()] = v.strip()
    if "t" not in parts or "v1" not in parts:
        return False

    try:
        ts = int(parts["t"])
    except ValueError:
        return False
    if abs(int(time.time()) - ts) > tolerance_sec:
        return False

    signed = f"{ts}.".encode() + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts["v1"])

<?php
function verify_payhook_signature(string $rawBody, string $header,
                                  string $secret, int $toleranceSec = 300): bool {
    $parts = [];
    foreach (explode(',', $header) as $piece) {
        [$k, $v] = array_pad(explode('=', $piece, 2), 2, '');
        if ($k !== '' && $v !== '') $parts[trim($k)] = trim($v);
    }
    if (!isset($parts['t'], $parts['v1'])) return false;

    $ts = (int)$parts['t'];
    if (abs(time() - $ts) > $toleranceSec) return false;

    $signed   = $ts . '.' . $rawBody;
    $expected = hash_hmac('sha256', $signed, $secret);
    return hash_equals($expected, $parts['v1']);
}

require 'openssl'

def verify_payhook_signature(raw_body, header, secret, tolerance_sec: 300)
  parts = header.split(',').map { |p| p.split('=', 2).map(&:strip) }.to_h
  return false unless parts['t'] && parts['v1']

  ts = parts['t'].to_i
  return false if (Time.now.to_i - ts).abs > tolerance_sec

  signed   = "#{ts}.#{raw_body}"
  expected = OpenSSL::HMAC.hexdigest('sha256', secret, signed)
  # OpenSSL.fixed_length_secure_compare ships in stdlib (Ruby 2.5+); no Rack dep.
  expected.bytesize == parts['v1'].bytesize &&
    OpenSSL.fixed_length_secure_compare(expected, parts['v1'])
end

package payhook

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "strconv"
    "strings"
    "time"
)

func VerifySignature(rawBody []byte, header, secret string, tolerance time.Duration) bool {
    parts := map[string]string{}
    for _, p := range strings.Split(header, ",") {
        kv := strings.SplitN(p, "=", 2)
        if len(kv) == 2 {
            parts[strings.TrimSpace(kv[0])] = strings.TrimSpace(kv[1])
        }
    }
    ts, err := strconv.ParseInt(parts["t"], 10, 64)
    if err != nil || parts["v1"] == "" {
        return false
    }
    if diff := time.Since(time.Unix(ts, 0)); diff > tolerance || diff < -tolerance {
        return false
    }

    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write([]byte(strconv.FormatInt(ts, 10) + "."))
    mac.Write(rawBody)
    expected := hex.EncodeToString(mac.Sum(nil))
    return hmac.Equal([]byte(expected), []byte(parts["v1"]))
}

Billing behavior

PayHook bills via prepaid USDT — no card, no Stripe, no fiat onramp. You top up a balance from /topup; plan renewals and overage settlements debit from that balance. For plan tiers, quotas, and per-event rates, see the pricing page. The notes below cover API-visible behavior — when calls 402, when settlements happen, what insufficient balance means.

What counts toward quota

Confirmed payments only. Pending payments that expire unpaid don't count and don't trigger any fee. The counter is per billing period (30 days for monthly, 365 for yearly) and resets on renewal.

Overage

Once you exceed your plan's included quota, behavior depends on the allow_overage toggle on your /billing page.

• ON (default for Pro & Scale): additional payments charge per-event from your prepaid balance, settled in batches of 1,000 events — or every 24h, whichever fires first. Predictable batch transactions, not 1,000 individual ledger rows.
• OFF (default for Free): POST /api/v1/payments/ returns 402 plan_limit_reached until you upgrade or the period renews. Predictable cost, hard ceiling.

Mid-period plan changes

Switching plans mid-period settles any unsettled overage at the OLD plan's rate first (fair: you used those events under the old plan), then debits the new plan price and resets the period to now → +30d/365d. No proration in v1.

Renewal & insufficient balance

Subscriptions auto-renew at period_end. If your balance covers the renewal, we debit + extend. If not, you drop to the Free plan + receive an email; existing in-flight payments keep working, only new POST /payments/ calls hit the Free quota until you top up + upgrade.

Error reference

PayHook returns errors as JSON. Two shapes:

• Field validation errors: {"errors": {"field_name": ["message", ...]}}
• Service-level errors: {"error": "human message", "code": "MachineCode"} or {"detail": "..."}

Raw OpenAPI schema

For codegen and tooling, the OpenAPI 3.0 JSON spec for the public integration surface is at api.payhook.app/api/v1/schema/. The schema covers Create and Retrieve — dashboard-only operations (webhook setup, billing, branding, address pool, topups) are intentionally omitted; configure those at app.payhook.app.