API documentation

Quickstart

Want to try it first? Create a test site and confirm a sample payment from the dashboard. No wallet addresses or funds needed. The steps below connect a live site.

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 to one site; rotate the key in your site settings 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": "buyer@example.com",
  "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": "buyer@example.com",
  "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 for the same site 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).

Reusing a key with a different request body returns 409 idempotency_key_reused. A retry that arrives while the first request is still being processed returns 409 idempotency_in_flight; wait a moment and retry.

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}"), where 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) {
  if (typeof header !== 'string') return false;
  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:
    if not header:
        return False
    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)
  return false if header.nil? || header.empty?
  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 is prepaid, in USDT: no card, no Stripe, no fiat onramp, no subscription. Every account gets 50 free payments every 30 days; beyond that, buy payment packs from /topup. For pack prices, see the pricing page. The notes below cover API-visible behavior.

What uses a payment

Confirmed payments only. Payments that expire unpaid, are cancelled, or run in test mode cost nothing. The 50 free payments renew every 30 days and are used first; each confirmed payment after that uses one of the payments you bought. Bought payments never expire.

Running out

When your free payments and bought payments are used up (counting payments still pending), POST /api/v1/payments/ returns 402 plan_limit_reached until you top up or your free payments renew. Payments already open still confirm and their webhooks still deliver. We email you the first time it happens in each 30-day window.

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.