Authentication - Revtain

Pass your API key via the X-API-KEY header on all requests:

X-API-KEY: rev_dTviCg52T8gLPCjrrW4KA0NKf_f5pQgk

Keep this secret. Your API key can trigger charges. Never expose it in client-side code, public repos, or logs.

Onboarding Credentials

Revtain provisions your account and issues your credentials — typically the same business day. You receive three:

Credential	Format	Purpose
API Key (secret)	`rev_xxxxxxxxxxxxxxxxxxxxxxxx`	Authenticates all API requests. Can trigger charges — keep it server-side only.
Publishable Key	`rev_pk_xxxxxxxxxxxxxxxxxxxxxxxx`	Read-only key, safe to embed in client-side code. Used by the in-app payment wall. Cannot trigger charges.
Webhook Signing Secret	`whsec_xxxxxxxxxxxxxxxxxxxxxxxx`	Verifies inbound webhook signatures

The API key and webhook signing secret are sensitive — store them in environment variables, never in client-side code or repositories. The publishable key is designed to be public and is the only credential safe to ship in a browser.

What You Provide

Your payment gateway key (Stripe secret key, Checkout.com secret key, etc.)
A webhook URL (HTTPS endpoint to receive recovery notifications)

Optional Configuration

Field	Type	Default	Description
`billingCycleDay`	integer (1-31)	auto-detected	Day of month customers are billed. Optimises retry timing. If you don’t set it, Revtain infers it automatically from your first renewal failure — no action needed.
`timezone`	string	`UTC`	IANA timezone (e.g., `America/New_York`).
`dunningEnabled`	boolean	`true`	When `true`, Revtain sends a `recovery.failed` webhook to your endpoint after all retry strategies are exhausted. When `false`, no webhook is fired on failure — only `recovery.success` and `recovery.blocked` fire. Keep this `true` unless you are handling failure detection entirely on your own side.
`cardUpdateDomain`	string	—	Custom domain for branded card update page (e.g., `pay.yourdomain.com`).

Rate Limits

Endpoint	Limit
`/api/recovery/execute`	60 requests / minute / API key
`/api/recovery/paywall-status`	120 requests / minute / key
All others	No specific limit (fair-use applies)

Rate-limited requests return 429 Too Many Requests with a retryAfter field.