# info.description
Non-custodial crypto payment monitoring delivered as HMAC-signed webhooks.

**Authentication.** Every request carries an `X-API-Key` header with your PayHook secret key (`pk_<hex>` format). Get yours from the dashboard at https://app.payhook.app/api-keys. Keep it server-side, never expose it to browsers, and rotate it from the dashboard if it leaks.

**Base URL.** All endpoints below are relative to `https://api.payhook.app/api/v1`.

**Webhooks.** PayHook POSTs an HMAC-SHA256-signed event to your endpoint when a payment confirms or expires. Register the URL, watch the delivery log, and replay failed deliveries from the dashboard. Signature-verification examples (Node, Python, PHP, Ruby, Go) live in the narrative docs at https://payhook.app/docs/#webhooks.

# paths./payments/.post.description
Creates a payment and returns a hosted-checkout URL the customer pays from any wallet. PayHook picks an available receive address from the merchant's pool, locks it for the lifetime of the payment, and watches the chain for an inbound transfer of `expected_crypto_amount`.

**Idempotency.** If you set `Idempotency-Key: <opaque-string>` on the request, retries within 24 hours with the same key will return the original payment instead of creating a duplicate. Recommended for any production integration that may retry on network errors.

# paths./payments/.post.parameters[].description
Opaque string (typically a UUID). 24h TTL.

# paths./payments/.post.responses.400.description
No address pool configured for this (network, currency).

# paths./payments/.post.responses.503.description
Every active address is currently held by another pending payment. Retry after a short delay.

# paths./payments/{payment_number}/.get.description
Look up a single payment by its `payment_number`. Returns the same fields as the create response, with `status`, `tx_hash`, `confirmations`, `actual_crypto_amount`, and `confirmed_at` reflecting the latest on-chain state. Useful for verifying a webhook event server-side before fulfilling the underlying order.

# paths./payments/stats/.get.description
`GET /api/v1/payments/stats/` — aggregated counts for the
authenticated merchant. Single query for the dashboard's stat cards.

# components.schemas.Payment.description
Authenticated merchant response — full payment row.

# components.schemas.Payment.properties.expected_crypto_amount.description
Exact on-chain amount the customer must send.

# components.schemas.Payment.properties.assigned_address.description
Address pulled from the merchant's pool. The single discriminator the chain watcher matches against.

# components.schemas.PaymentCreateRequest.description
Request body for `POST /api/v1/payments`.

# components.schemas._ErrorResponse.description
Schema-only — describes the {error, code} body the create endpoint
returns when the merchant hasn't configured an address pool yet.

# components.securitySchemes.ApiKeyAuth.description
Your PayHook secret API key (format: `pk_<hex>`). Look it up in the dashboard at https://app.payhook.app/api-keys. Required on every request — keep it server-side, never expose it to browsers or commit it to source control. Rotate via the dashboard if it leaks.

# tags[].description
Create a payment, then poll or wait for the signed webhook to confirm settlement. Retrieve any payment by its number to verify state server-side.