Operate
Dashboard guide
Map operator workflows to the same objects used by your integration.
The merchant portal at zippypay.io is where operators configure the same objects your integration uses: business verification, payment ID, allowed checkout domains, API keys, and webhooks.
Go-live checklist
Complete every item before creating payment sessions in production. KYB approval alone is not enough — session create also requires an active business account, a receive payment ID, and registered checkout domains.
- KYB approved
- Business status ACTIVE
- Business Zippy payment ID created (e.g. acme.coffee)
- API key created
- All production checkout domains registered (Integrations → Allowed browser origins)
- successUrl / failureUrl origins match registered domains (if used)
- HTTPS webhook endpoint registered
Portal access
Sign in at https://zippypay.io. Before you can create API keys or register webhooks, complete business verification (KYB) and ensure your business account is active.
Session create prerequisites
| Name | Type | Description |
|---|---|---|
KYB approved | onboardingStatus = APPROVED | 403 business.compliance-not-approved if not met. |
Business active | status = ACTIVE | 403 business.not-active if suspended or inactive. |
Receive payment ID | configured | 403 business.payment-id-not-configured if missing. |
Business payment ID
Create your business Zippy payment ID (receive handle, e.g. acme.coffee) under business settings after KYB approval. Session create fails with 403 business.payment-id-not-configured if no active receive payment ID exists — this is enforced at session create on your server, not later during checkout.
Allowed browser origins
Register every browser origin where you embed @zippypay/checkout under Integrations → Allowed browser origins. This is portal configuration — not controlled by your API key.
This setting applies to checkout embedded in the browser. Session create on your server is authenticated with X-Api-Key — keep that key on your backend only.
What to register
Origins only — no path, query, or hash:
https://checkout.acme.comhttps://www.acme.com
Registration rules
| Name | Type | Description |
|---|---|---|
Scheme | HTTPS only | Production and staging. http://localhost:* and http://127.0.0.1:* allowed for local development only. |
Format | Origin only | No path, query, hash, or wildcards. |
Max per business | 10 | Register each domain you use. |
www vs apex | Separate origins | Register both if customers reach checkout on each. |
API keys
- Complete KYB, confirm business status is active, and create your payment ID.
- Open Developer → API Keys.
- Create a key with a descriptive name (for example "Production server").
- Copy the plaintext key (
zp_live_…) — it is shown once. - Revoke compromised keys immediately; create a replacement.
Webhooks
- Open Developer → Webhooks.
- Register an HTTPS receiver URL.
- Store the one-time signing secret (
whsec_…) in your secret manager. - Send a test delivery to validate connectivity and signature verification.
- Purge retired endpoints after cutting over to a new URL or secret.
All active endpoints receive every live payment session and transaction event.
Deliveries
Developer → Webhooks → Deliveries shows live delivery attempts: HTTP status, error summaries, and attempt history. Use manual resend to recover from transient receiver failures. See webhook deliveries for deduplication and response requirements.