Using the Ozow APIs
Endpoints, parameters and schemas for the Ozow APIs.
On this page7 sections
Reference for every endpoint Ozow exposes: what it accepts, what it returns, and what it needs to authenticate.
For when to call an endpoint and how the pieces fit together, use the integration guides.
Which API to use
| API | Status | Use for |
|---|---|---|
| One API | Current | PayinsPayin 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., refunds, settlementsSettlement Ozow paying the money you have collected into your bank account. Payins arrive at Ozow first and are settled to you on a schedule, so what a customer paid you today and what has been settled to you today are different amounts. and recurring payments |
| Payouts API | Current | 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. |
| Payments API | Deprecated | Existing payin and refund integrations only. Supported, but not the target for new work |
The Payments API is deprecated. It remains supported and existing integrations keep working, but new features are released on the One API only and no new merchants are onboarded onto it. No end-of-life date has been set. See Migrating to One API.
Base URLs
| API | Production | Staging |
|---|---|---|
| One API | https:/ |
https:/ |
| Payouts API | https:/ |
https:/ |
| Payments API | https:/ |
https:/ |
Staging is fully isolated from production and has its own credentials.
Testing environment
Payin integrations can be tested directly in production. Any test transactions settle into your configured bank account. To test without moving real money, staging credentials are available on request: contact your account manager or support@ozow.com. Unlike payins, payouts must be integrated and tested in a staging environment before production access is granted.
Authentication
| API | Credential | How |
|---|---|---|
| One API | OAuth 2.0OAuth 2.0 The authorisation framework behind the token endpoint. Ozow uses the client credentials flow: your server exchanges a client ID and secret for a short-lived access token, and sends that token rather than the secret on every subsequent call.RFC 6749 client credentials | Exchange your client ID and secret at the token endpoint, then send Authorization: Bearer <token>. Scopes limit what a token can do |
| Payouts API | API key | Send the key in the Api header |
| Payments API | API key, then a bearer tokenBearer token An access token sent in the Authorization header as Authorization: Bearer <token>. Anyone holding the token can use it, which is why it belongs on your server and never in a browser or a mobile app.RFC 6750 |
Send your API key to /, then use the returned token on / operations. Some operations take the API key directly |
Production credentials are available to you in the Ozow Dashboard. Ozow will never send them to you and will never ask you for them: treat any such request as fraudulent and report it to support@ozow.com. Keep credentials server-side, never in client code or a public repository. See Building a secure integration.
Conventions
Paging. One API list operations take limit and offset, return links with self, first,
last, prev and next, and a meta object with totalPages and totalItems. Follow
links.next until it's absent rather than incrementing offset yourself.
Amounts. One API returns amounts as objects, { "currency": "ZAR", "value": 250.00 }, not
bare numbers. Read value, and check currency if you take payments in more than one.
Correlation IDs. One API operations accept an X-Correlation-ID header and return it in the
response. Send one and log it: it's the fastest way for Ozow Support to trace a specific call. If
you don't send one, Ozow generates it.
IdempotencyIdempotency 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. Where an operation supports an idempotency key, use it. A retried request with the same key won't repeat the action.
Copying field names
Field names are shown exactly as the API expects them. Copy them as written rather than retyping: a name that differs by a character or by its casing is a name the API doesn't recognise.
That includes known misspellings. Where a field name in a response is spelled unexpectedly, it's spelled that way in the API too, and using the corrected spelling will fail.
Specs and collections
Guides and reference
The reference tells you what an endpoint accepts and returns. The guides tell you when to call it and why.
| I want to | Guide |
|---|---|
| Get a payment working end to end | Quick start |
| Accept a payment | Redirect to Ozow |
| Send money out | Send a payout |
| Refund a customer | Refund a payment |
| Reconcile settlements | Reconcile settlements |
| Charge on a schedule | Set up recurring payments |
| Move off the Payments API | Migrating to One API |
Last updated