Documentation Index
Fetch the complete documentation index at: /llms.txt
Use this file to discover all available pages before exploring further.
Every numeric limit of the Zahlo API in one place - currencies per payment method, amount ranges, subscription intervals and charge caps, checkout session expiry, checkout domains, webhook retries, rate limits, idempotency, metadata and list sizes.
error.code.
| Payment method | Currencies |
|---|---|
| Cards (Visa, Mastercard and others) | EUR; CAD, CHF, DKK, GBP, JPY, PLN, RON and USD on request |
| Apple Pay, Google Pay | EUR |
| SEPA Direct Debit (subscriptions) | EUR only |
GET /payment-methods returns the methods enabled for your account; use it instead of hard-coding this table. SEK and NOK are not supported.
| Limit | Value | Error code |
|---|---|---|
| Unit | integer amountMinor in the currency’s minor unit (JPY has no minor unit) | parameter_invalid |
| Minimum per payment | €1.00 (¥164); in other currencies, about the equivalent of €1.00 | amount_below_minimum |
| Maximum per payment | €15,000.00; in other currencies, about the equivalent | amount_above_maximum |
| Zero-total one-time checkout | not allowed (a 100% coupon on a one-time payment is rejected) | amount_below_minimum |
| Line items per Checkout Session | 1-100 lines, quantity 1-999 | parameter_invalid |
| Limit | Value |
|---|---|
| Billing interval | whole months, 1-36 (no daily or weekly intervals) |
| Amount per charge | 0.50 to 5,000.00 in the major unit (amount_exceeds_subscription_limit) |
| Failed card renewal | retried automatically up to 3 times, once a day |
| Plan or quantity change | takes effect at the next period boundary; no proration |
repeating coupon | counts charged periods; a coupon below the payment minimum is rejected (amount_below_minimum) |
100%-off forever coupon | rejected |
| SEPA Direct Debit | EUR only; a debit is processing for several banking days and counts as active meanwhile; a later return starts the failed-payment process |
| Limit | Value |
|---|---|
Expiry (expiresInSeconds) | 1,800-86,400 seconds (30 minutes to 24 hours); default 24 hours |
| What the customer sees | no countdown; an expired session shows “This checkout expired” with a link back to your site |
| Fulfilment | only on checkout.session.completed |
| Limit | Value | Error code |
|---|---|---|
| Return URLs | their host must be registered as a checkout domain | checkout_domain_not_registered |
localhost and http:// | Sandbox only (zk_test_ keys); live requires HTTPS | domain_invalid |
| New accounts | checkout may be unavailable for a short time while Zahlo enables it for your account; registering a checkout domain takes effect immediately | checkout_domain_pending |
| Apple Pay in embedded checkout | needs a real HTTPS host registered with applePay: true; a temporary tunnel host does not work | — |
| Limit | Value |
|---|---|
| Signature tolerance | reject when t is more than 300 seconds from your clock |
| Response | any 2xx within 10 seconds counts as delivered |
| Retries after a failure | 1 min, 5 min, 30 min, 2 h, 5 h, 10 h, 24 h, 24 h (about 2.8 days) |
| Endpoint disabled | after 3 days with no successful delivery; you are emailed, and you can re-enable it and retry the failed deliveries |
| Secret rotation | the previous secret keeps signing for 24 hours |
| Event retention | 30 days (GET /events) |
| Limit | Value | Error code |
|---|---|---|
| API requests | 600 per minute per IP address | rate_limit_error (429) |
| Payment-link checkouts | 10 per link per IP per hour, 300 per account per hour | attempt_limit (429) |
Idempotency-Key | kept for 24 hours per account and route | idempotency_key_reused, request_in_progress (409) |
| List page size | limit 1-100, default 20 | parameter_invalid |
| Metadata | up to 50 keys; key up to 40 characters; value up to 500 characters | parameter_invalid |
| Refund outcome | a pending refund can take up to one business day to become succeeded or failed | — |