# Using the Ozow APIs

> Endpoints, parameters and schemas for the Ozow APIs.

Source: https://hub.ozow.com/api-reference/

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](https://hub.ozow.com/integration-methods.md).

## Which API to use

| API | Status | Use for |
|---|---|---|
| [One API](https://hub.ozow.com/api-reference/one-api.md) | Current | Payins, refunds, settlements and recurring payments |
| [Payouts API](https://hub.ozow.com/api-reference/payouts-api.md) | Current | Payouts |
| [Payments API](https://hub.ozow.com/api-reference/payments-api.md) | **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](https://hub.ozow.com/integration-methods/apis/deprecated-integrations/migrating-to-one-api.md).

## Base URLs

| API | Production | Staging |
|---|---|---|
| One API | `https://one.ozow.com` | `https://stagingone.ozow.com` |
| Payouts API | `https://payoutsapi.ozow.com/v1` | `https://stagingpayoutsapi.ozow.com/v1` |
| Payments API | `https://api.ozow.com` | `https://stagingapi.ozow.com` |

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](mailto: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.0 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 `ApiKey` header |
| Payments API | API key, then a bearer token | Send your API key to `/token`, then use the returned token on `/secure/*` operations. Some operations take the API key directly |

> 🚨 Production credentials are available to you in the [Ozow Dashboard](https://dash.ozow.com). 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](mailto:support@ozow.com). Keep credentials server-side, never
> in client code or a public repository. See [Building a secure
> integration](https://hub.ozow.com/getting-started/building-a-secure-integration.md).

## 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.

**Idempotency.** 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](https://hub.ozow.com/getting-started/quick-start.md) |
| Accept a payment | [Redirect to Ozow](https://hub.ozow.com/integration-methods/apis/payin/redirect-to-ozow.md) |
| Send money out | [Send a payout](https://hub.ozow.com/integration-methods/apis/payout/send-a-payout.md) |
| Refund a customer | [Refund a payment](https://hub.ozow.com/integration-methods/apis/refunds/refund-a-payment.md) |
| Reconcile settlements | [Reconcile settlements](https://hub.ozow.com/integration-methods/apis/settlements/reconcile-settlements.md) |
| Charge on a schedule | [Set up recurring payments](https://hub.ozow.com/integration-methods/apis/recurring-payments/set-up-recurring-payments.md) |
| Move off the Payments API | [Migrating to One API](https://hub.ozow.com/integration-methods/apis/deprecated-integrations/migrating-to-one-api.md) |