Building a secure integration
Where Ozow's security responsibility ends and yours begins: credentials, webhook endpoints, verifying notifications, and validating amounts.
On this page11 sections
Build with AI 5 packages
A build package is every page for one task, with the API operations they use. Copy the prompt into a coding assistant, or hand it the package itself: slim links to each page, full inlines all of them in one document.
- Take a paymentEverything needed to take a payment end to end with One API, from credentials through the hosted page to the webhook that confirms it, and the test cases that prove each outcome before you go live.
- Embed checkout in your own pageEverything needed to keep the customer on your site while they pay, as an iframe, a modal, or the Wallet SDK for Apple Pay and Google Pay, with the notification that actually confirms the payment.
- Take a recurring paymentEverything needed to collect from a customer on a schedule with One API, from the consent the customer gives once through to each collection and the webhook that reports it.
Security is a shared responsibility between Ozow and you as the merchant. Understanding where Ozow's responsibility ends and yours begins is essential to building an integration that is safe for your customers and your business.
The shared security model
Ozow secures the payment infrastructure. You secure how you integrate with it.
| Ozow is responsible for | You are responsible for |
|---|---|
| The security of the payment processing infrastructure | How you store and handle your API credentials |
| Encryption of payment data in transit and at rest within Ozow systems | The security of your callback and webhookWebhook A URL of yours that Ozow calls when something happens, rather than you polling to find out. The call carries no credential of yours and arrives at a public URL, so authenticate it before acting on it: a hash field on the Payments API, a Svix signature on One API. endpoints |
| The integrity and availability of Ozow APIs | Verifying that notifications genuinely came from Ozow |
| Fraud monitoring within the Ozow platform | Validating transaction details before crediting orders |
| Physical and network security of Ozow's environments | Access controls on your systems and Ozow Dashboard |
| Compliance with applicable payment regulations on Ozow's side | Monitoring your own integration for anomalous activity |
A secure Ozow integration is not only about calling the right endpoints, it is about what happens on your side of the connection too.
Your security responsibilities
Credentials and secrets
Your API credentials are the keys to your Ozow integration. If they are compromised, an attacker could initiate payments or payoutsPayout Money sent from a merchant to a bank account. Unlike a refund, a payout is not tied to a payment anyone made you, so you can pay anyone with a bank account. Payouts draw on your float rather than on your incoming payments, and they are not self-service: they need approval from Ozow and testing in staging first. on your behalf.
- Store all Ozow credentials, API keys, private keys, Client IDs, Client Secrets, and Payout API keys; in a secrets manager or environment variables. Never hardcode them or commit them to source control.
- Keep test and production credentials in strictly separate environments. Never use production credentials in a development or staging environment.
- Restrict access to production credentials to a named list of people and services. Access must be least-privilege.
- Have a documented process and a named owner for rotating credentials. Know what you would do if a key were compromised.
Callback and webhook endpoint security
Ozow communicates payment outcomes by sending notifications to a URL you specify. This endpoint is a critical part of your integration.
- Your callback and webhook URLs must be HTTPS only, using TLSTLS The encryption behind
https. Every call to Ozow uses it, which is what keeps a request unreadable in transit.Wikipedia 1.2 or later. - Your endpoint must not expose stack traces, internal errors, or verbose logs in its response to callers.
Verifying notifications
Receiving a notification is not the same as trusting it. You must verify that every notification genuinely came from Ozow before acting on it.
- For Payments API integrations: verify every incoming notification using the hash check before updating any order status.
- For One API integrations: validate the message signature on every incoming webhook before acting on it.
- Log and alert on verification failures rather than silently discarding them. A pattern of verification failures is a signal worth investigating.
- Never mark a payment as complete based on the browser redirectRedirect Sending the payer to the Ozow payment page to complete the payment, and returning them to your site afterwards. The alternative is embedding the checkout in your own page, where the payer never leaves it. alone. Always confirm status via the API or a verified webhook notification.
- Implement replay protection so that a previously processed transaction reference cannot be reprocessed to double-credit an order.
Important
Ozow may occasionally send duplicate notifications for the same transaction. Your system must handle this gracefully, processing the same transaction twice must not result in double-crediting an order.
Transaction integrity
Before crediting an order, validate that the payment details match what you originally requested.
- Verify that the amount, currency, and merchant reference in the notification match your original payment request.
- Handle duplicate notifications idempotentlyIdempotency A request is idempotent when sending it twice has the same effect as sending it once. It matters most where a retry after a timeout could otherwise take a payment twice.IETF draft, receiving the same notification twice must have no additional effect.
- Periodically reconcile your order records against Ozow's transaction records rather than relying solely on webhook delivery.
Payout-specific responsibilities
Payouts carry additional security requirements because they involve outgoing funds.
Authorisation
- For bulk payouts: Ozow recommends that the person who requests a bulk payout is different from the person who approves it. Ozow does not enforce this.
- For API payouts: access to the systems, credentials, and code that can trigger a payout must be restricted to a named list of people, with any changes requiring review.
- Your system must enforce a business-level authorisation step before calling Ozow's payout API. Being authenticated is not sufficient, there must be a deliberate approval within your own system before a payout is initiated.
Beneficiary handling
- Verify beneficiary bank details before the first payout to any new beneficiary.
- If you are not using stored beneficiary profiles, validate destination bank details on every payout request.
- Any change to stored beneficiary details must trigger a mandatory review or re-verification step before the next payout.
- Generate and persist a unique encryption key per payout request. Never reuse an encryption key across multiple payout requests.
- Enforce velocity and amount limits on payouts.
- Implement real-time alerting for anomalous payout activity, unusual amounts, unfamiliar beneficiaries, or off-hours activity are all signals worth acting on immediately.
Verification request handling
- Validate the access token on all incoming payout verification requests.
- Verify the hash on every verification request to confirm it genuinely originated from Ozow.
- Validate that the payout details in the verification request match a payout your system actually initiated: do not return a decryption key based on token and hash checks alone without confirming the payout is expected.
Payout status verification
- Confirm payout completion via the API, rather than assuming completion from the initial payout response.
- Verify the hash on every incoming payout status notification before trusting it.
Access and monitoring
- Apply least-privilege access for all roles with access to your Ozow merchant Dashboard.
- Monitor for abnormal patterns in your payinPayin A payment made by a consumer to a merchant. The direction most of this site is about: money coming in. Its counterpart is a payout, which sends money out and is not tied to any payment anyone made you. traffic, spikes in failed verifications or unusual volumes are worth investigating.
- Maintain an immutable audit trail of who requested and who approved every payout, and when.
- Reconcile your internal ledger against Ozow's payout records on a regular cadence.
Quick reference checklist
Use this checklist before going live with any Ozow integration.
Payin integrations
Payout integrations
Last updated