Onboarding
Before you can open the widget, Pagamio and you exchange a small set of credentials and settings. This page lists both sides.
What Pagamio Issues
| Item | What it is | Used for |
|---|---|---|
| Partner code | A short lower-case identifier for your integration (for example acme). It appears in every widget URL: /w/{partnerCode}/. | Routing: it is part of every widget and launch URL. |
| API key | pk_<environment>_<keyId>_<secret>. Shown to you once; Pagamio stores only a hash. Carries scopes such as sessions:create, transactions:read and reconciliation:read. | Server-to-server calls: sessions, transactions, statements. |
| Launch secret | A shared HMAC secret and the expected iss value, agreed between you and Pagamio and exchanged over a secure channel. Only needed if you use the partner-initiated launch. | Signing launch tokens. |
| Environment URLs | Sandbox and production base URLs. | See Sandbox Testing. |
Sandbox and production credentials are separate. A sandbox key does not work in production.
Rotation
API keys and launch secrets can be rotated. For a launch secret, Pagamio can hold a second "staged" secret alongside the current one, so you can switch signing over without downtime: tokens signed with either secret are accepted during the overlap, and the kid header in each token (see kid derivation) tells Pagamio which one you used. Ask your Pagamio contact to schedule a rotation.
What You Provide
| Item | Details |
|---|---|
| Wallet API | A base URL and a credential for the wallet contract, in sandbox and production. Include the currency unit your API expects (cents by default; whole rand on request). |
| Hold lifetime | How long a hold stays valid. It must exceed the timing requirement. |
| Allowed origins | The exact origins (scheme, host and port, no path) that may frame the widget in an iframe, for example https://app.example.com. Leave empty for web-view only. |
return_url hosts | The https hostnames a launch return_url may point to. Anything else is ignored. |
| Branding | Display name, logo URL (https), a primary colour, an accent colour and the text colour used on the primary colour. An optional dark-mode primary and accent colour can also be supplied. Pagamio derives the shade scale from your primary colour. |
| Session lifetimes and rate limit | Optional. Typical defaults are a 15 minute idle timeout, a 60 minute absolute lifetime and 60 API requests per minute per API key; Pagamio configures these per partner. |
| Egress details | If your wallet API allow-lists source IPs, tell Pagamio so the correct addresses are shared. |
| Technical contacts | For rotation, incident and reconciliation queries. |
Onboarding Checklist
- Partner code, API key and (if applicable) launch secret received and stored in your secret manager.
- Wallet API reachable from Pagamio in sandbox, and meeting the timing requirement.
- Allowed origins and
return_urlhosts confirmed. - Branding supplied and checked in the sandbox widget.
- End-to-end sandbox purchase and a failed purchase (for example insufficient funds) both tested.
- Host bridge events handled in your app.
- Production URL, credentials and go-live date agreed.
Last updated: September 2026