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) | Friday payday window | Day of month customers are billed. Optimises retry timing. |
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) |
429 Too Many Requests with a retryAfter field.