API reference
The Kitepay API is a predictable REST API: JSON in, JSON out, standard verbs, no surprises. Every money movement is recorded as a balanced double-entry journal transaction and is visible through the reconciliation endpoint.
Authentication
Pass your secret key in the x-api-key header. Keys are shown once at signup and manageable in the dashboard; restricted keys can be scoped per resource. Dashboard sign-in uses your email and password.
curl https://kitepay.uk/v1/balance -H "x-api-key: sk_test_..."
Test cards
| Card | Result |
|---|---|
| 4000 0000 0000 0000 | Approves (code 00) |
| 4000 0000 0000 0051 | Insufficient funds (51) |
| 4000 0000 0000 0005 | Do not honor (05) |
| anything else | Invalid card (14) |
Errors
Failures return an error object with a stable code and human message. HTTP status mirrors the class of failure: 401 bad key, 402 declined, 403 permission, 400 validation.
{ "error": { "code": "permission_denied", "message": "this key lacks payouts:write" } }
Payments
POST/v1/payments authorizes a card, a saved payment_method, or a customer's default method. Send an Idempotency-Key header to make retries safe. Every authorization is risk-scored before funds move; elevated scores step up to 3-D Secure via next_action.url.
| Field | Description |
|---|---|
| amount | Integer, minor units (pence/cents) |
| currency | gbp (default), usd, eur — GBP settlement |
| card_number · customer · payment_method | One source of funds |
| transfer_to · application_fee | Marketplace split to another merchant |
| request_three_ds | Force a 3-D Secure challenge |
POST/v1/payments/:id/capture settles an authorization: fee is booked, the merchant balance is credited, one journal entry, sum zero.
curl -X POST https://kitepay.uk/v1/payments \
-H "x-api-key: sk_test_..." -H "Idempotency-Key: order-1041" \
-d '{"amount": 2500, "customer": "cus_..."}'
Customers & vault
POST/v1/customers creates a customer. POST/v1/customers/:id/payment_methods saves a card; the first becomes the default. Charge later with just the customer ID.
Refunds
POST/v1/refunds with payment and optional amount for partial refunds. Multi-currency refunds settle proportionally to the penny.
Payment links
POST/v1/payment_links → a reusable hosted page at /l/:id. Share it anywhere; every visit is a fresh risk-scored payment.
Checkout
POST/v1/checkout_sessions → a single-use hosted payment page at /pay/:id.
Invoices & VAT
POST/v1/invoices with line items and optional tax_rate (e.g. 20 for UK VAT). Subtotal, tax and total are computed and shown on the hosted page; the paid page becomes the receipt.
{"customer_name":"Croft Street Cafe","tax_rate":20,
"items":[{"description":"Consulting day","quantity":1,"unit_amount":10000}]}
Subscriptions
POST/v1/subscriptions with a plan plus a card, customer or saved method. Optional trial_days starts the subscription in trialing with no charge; the platform's billing worker converts it automatically. Renewals are merchant-initiated and 3DS-exempt. Failed renewals retry, then park as past_due.
Coupons
POST/v1/coupons with percent_off or amount_off and duration of once or forever. Pass coupon when creating a subscription.
Metered usage
Create a plan, set it metered, then report usage with POST/v1/subscriptions/:id/usage {"quantity": n}. Usage bills in arrears at period end: units × unit price, one charge, one journal entry.
Test clocks
POST/v1/subscriptions/:id/advance {"seconds": 1296000} fast-forwards a subscription's billing clock and immediately runs the billing worker — trials convert, renewals charge, dunning retries fire. Test a year of billing in a minute.
Webhooks
Every money event emits a signed webhook: payment.authorized, payment.captured, payment.declined, refund.succeeded, invoice.paid, subscription.billed, dispute.*, payout.paid. Verify the Kitepay-Signature header: hex HMAC-SHA256 of the raw body with your webhook secret. Failed deliveries retry on backoff (1m, 5m, 30m, 2h, 12h); inspect the trail at GET/v1/events.
Restricted keys
POST/v1/api_keys with per-resource permissions (read/write/none over payments, refunds, payouts, customers, subscriptions, invoices, checkout, disputes, account). Revoke any time.
Analytics
GET/v1/analytics — 30-day gross volume, fees, payment count, success rate, risk blocks, daily series and top customers, straight from the ledger of record.
Reports & reconciliation
GET/v1/reports/payments.csv?from=&to= and /v1/reports/payouts.csv for exports. GET/v1/reports/reconciliation recomputes the trial balance across every account and posting — the answer is always zero, and you can check whenever you like. A sentinel runs the same audit every minute; see kitepay.uk/status.