Skip to main content

Security Notes

Keep Secrets On Your Server​

  • The API key and the launch secret belong in your backend and your secret manager. Never ship them in a mobile app, a web page, a repository or a log line.
  • API keys are shown once and stored hashed by Pagamio. If a key or secret is lost or exposed, tell Pagamio at once so it can be rotated and revoked. See Onboarding.
  • Use separate credentials for sandbox and production.
  • Your app should only ever handle the widgetUrl (or a signed launch URL), never the credentials that produced it.

Treat Widget URLs And Tokens As Credentials​

  • A widgetUrl grants access to one customer's widget session until it expires. Do not log it, share it or reuse it for another customer. It carries the session token in the URL fragment, which browsers do not send to servers.
  • Launch tokens live about 60 seconds and are single-use. Issue one per customer action; do not pre-generate or cache them. Generate a unique jti every time.
  • Create a new session each time the customer opens the widget, and revoke it when the customer signs out.

Token And Session Lifetimes​

ItemLifetime
Launch tokenSign with exp = iat + 60 seconds. Accepted once. 30 seconds of clock skew is tolerated.
Widget sessionIdle timeout (default 15 minutes, extended on activity) and an absolute lifetime (default 60 minutes). Both are configured per partner.

Keep your server clocks synchronised (NTP). Clock drift is the most common cause of rejected launch tokens.

Origin And Redirect Allow-Lists​

  • Allowed origins control which sites may frame the widget (Content-Security-Policy: frame-ancestors) and which origin receives iframe bridge events. List exact origins (scheme, host and port), keep the list short, and leave it empty if you only use web-views.
  • return_url hosts control where a launch may send the customer. Pagamio only follows https URLs on listed hosts, so there is no open redirect. List only hostnames you control.
  • On the iframe bridge, check event.origin before acting on a message.

Transport​

  • HTTPS only, with a valid certificate, for every call in both directions: your calls to Pagamio, Pagamio's calls to your wallet API, and every page that hosts the widget.
  • Authenticate your wallet API. Pagamio sends Authorization: ApiKey <credential> on every wallet call; reject calls without it, and rotate the credential with Pagamio.
  • If your wallet API allow-lists source IPs, ask Pagamio for the current egress addresses.

Data Handling​

  • Pagamio does not accept identity numbers, dates of birth or bank details on any partner API.
  • Optional prefill attributes (firstName, surname, mobileNumber) are kept on the session only and are redacted from Pagamio's audit records.
  • Receipts (for example electricity tokens and voucher PINs) are encrypted at rest and returned only to the customer's session and to your API key. Treat them as secrets: do not log them.
  • Only send the customer attributes you need.

Rate Limits​

Server-to-server calls are limited per API key. Over the limit you receive 429 RATE_LIMITED with a Retry-After header. Use backoff, and avoid polling the transactions API faster than every few seconds; the bridge events tell you when to check.

Reporting A Security Issue​

Report suspected exposure of a key, secret or token to your Pagamio contact immediately, and do not include the secret itself in the report.

For general API security guidance see Security Best Practices.

Last updated: September 2026