Authentication
Protect API keys and understand when H2H request signatures are required.
Bearer API keys
Every merchant API request includes:
Authorization: Bearer <api-key>Create and revoke keys in Dashboard → Developers. A key belongs to one organization and can access only that organization's resources.
Use API keys only from trusted server-side code. Keep production and test keys separate, rotate credentials after suspected exposure, and revoke unused keys.
Use clear environment-variable names and validate them at process startup:
OMNIPAY_API_KEY=...
OMNIPAY_SIGNING_SECRET=... # H2H onlyH2H signing credentials
H2H adds proof that the method, path, query, and exact body bytes were not changed in transit:
Authorization: Bearer <api-key>
X-Omni-Timestamp: <unix-seconds>
X-Omni-Signature: v1=<base64url-hmac-sha256>A newly created API key has no signing secret. From the developer dashboard, choose Rotate H2H secret for the key and copy the returned secret immediately. It is shown once and encrypted at rest by OmniPay.
Rotating replaces the old signing secret immediately. Revoking an API key disables both bearer and HMAC authentication, and a revoked key cannot be rotated.
Which requests must be signed?
| Request | Bearer | H2H signature |
|---|---|---|
| Create redirect deposit | Required | Not used |
| Get redirect deposit | Required | Not used |
| Create H2H deposit | Required | Required |
| Get H2H deposit | Required | Required |
| Submit H2H payment transaction ID | Required | Required |
| Create/get withdrawal | Required | Not used |
OmniPay determines the GET requirement from the stored deposit mode. Sign H2H GET requests with an empty body.
Rotation without downtime
H2H secret rotation invalidates the previous secret immediately. To avoid failed requests:
- pause new H2H requests;
- rotate and copy the new secret from the dashboard;
- update the secret in every application instance;
- restart or reload all instances;
- send a signed status request as a smoke test;
- resume H2H traffic.
If an API key may be compromised, revoke it instead of rotating only its H2H secret.