# Take a payment > Everything 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. Your system asks One API for a payment, sends the customer to Ozow's hosted page, and learns the outcome from a webhook, not from the redirect back. Implement the pages in the order above. **One API only.** The Payments API is a separate contract, receives no new features, and has its own package, `migrate-a-payin-to-one-api`. One API authenticates with a bearer token and signs each webhook with a Svix signature. It uses no hash at all, so computing one means you are on the wrong contract. **Pay by Bank is what this package takes a payment with.** It is enabled on every account by default and needs no opt-in, so it is the method a first integration meets. Card, vouchers, PayShap, crypto and buy now pay later are opt-ins that arrive on the same request once Ozow enables them, which is why there is one integration here rather than one per method. **The webhook is the outcome and the redirect is not.** A customer who closes the tab must still end up with the right order state. Verify the signature before acting on a delivery. Handle every status the statuses page lists. The test cases cover a successful payment, a cancellation, a failure, a duplicate notification and a status check against the API. Build against production. Staging has separate credentials and its own hostname. Payins can be tested in production. ## What this was built from - Ozow Hub, commit `e0b2a572` - `one-api` version 1.0, OpenAPI document: https://hub.ozow.com/api-reference/specs/one-api.yaml - Build against `https://one.ozow.com/v1` for `one-api` - 11 pages, 11 operations, inlined in full below - The same package as links: https://hub.ozow.com/bundles/take-a-payment.md --- # Implement against these Every field name, order and format below is exact. Copy them as written. --- # Quick start: accept your first payment > Accept your first Ozow payment with One API. Get a token, create a payment request, redirect the customer, and read the webhook that confirms it. Source: https://hub.ozow.com/getting-started/quick-start/ This guide walks you through accepting your first payment using Ozow. By the end you'll have a working payment flow that creates a payment request and redirects your customer to complete their payment. > ℹ️ **Note**: If you're looking for a no-code or plugin option, head to [Integration > methods](https://hub.ozow.com/integration-methods.md). This guide is for developers building > an API integration. ## Before you start Make sure you have the following in place before continuing: - An active Ozow merchant account - Your Client ID and Client Secret from the One API Clients section of the [Ozow Dashboard](https://dash.ozow.com) - Your site code from the Site section of the Dashboard If you haven't completed these steps yet, see [Prerequisites and onboarding](https://hub.ozow.com/getting-started/prerequisites-and-onboarding.md) first. ## The scenario The examples on this page use one ecommerce checkout: > Fynbos Supply Co. runs an online store. A customer has added a product to their cart and is ready > to check out. The total order value is R100. Fynbos Supply Co. wants to redirect the customer to > Ozow to complete the payment securely. ## Step 1: Obtain an access token One API uses OAuth 2.0 authentication. Before you can make any API calls you need to request an access token using your Client ID and Client Secret. Send a POST request to the token endpoint: ```endpoint POST https://one.ozow.com/v1/token Content-Type: application/x-www-form-urlencoded ``` **cURL** ```bash curl -X POST "https://one.ozow.com/v1/token" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "client_id=YOUR_CLIENT_ID" \ -d "client_secret=YOUR_CLIENT_SECRET" \ -d "scope=payments" \ -d "grant_type=client_credentials" ``` **C#** ```csharp var client = new HttpClient(); var content = new FormUrlEncodedContent( new[] { new KeyValuePair("client_id", "YOUR_CLIENT_ID"), new KeyValuePair("client_secret", "YOUR_CLIENT_SECRET"), new KeyValuePair("scope", "payments"), new KeyValuePair("grant_type", "client_credentials"), } ); var response = await client.PostAsync("https://one.ozow.com/v1/token", content); var result = await response.Content.ReadAsStringAsync(); Console.WriteLine(result); ``` **PHP** ```php "https://one.ozow.com/v1/token", CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_POSTFIELDS => http_build_query([ "client_id" => "YOUR_CLIENT_ID", "client_secret" => "YOUR_CLIENT_SECRET", "scope" => "payments", "grant_type" => "client_credentials", ]), CURLOPT_HTTPHEADER => ["Content-Type: application/x-www-form-urlencoded"], ]); $response = curl_exec($curl); curl_close($curl); echo $response; ?> ``` **JavaScript** ```javascript const response = await fetch("https://one.ozow.com/v1/token", { method: "POST", headers: { "Content-Type": "application/x-www-form-urlencoded" }, body: new URLSearchParams({ client_id: "YOUR_CLIENT_ID", client_secret: "YOUR_CLIENT_SECRET", scope: "payments", grant_type: "client_credentials", }), }); const data = await response.json(); console.log(data); ``` **Python** ```python import requests response = requests.post( "https://one.ozow.com/v1/token", data={ "client_id": "YOUR_CLIENT_ID", "client_secret": "YOUR_CLIENT_SECRET", "scope": "payments", "grant_type": "client_credentials", }, ) print(response.json()) ``` **Successful response** ```json { "access_token": "eyJhbGciOiJSUzI1NiJ9...", "token_type": "Bearer", "expires_in": "14400", "scope": "payments" } ``` Store the `access_token`, you'll need it in the next step. Tokens expire after the number of seconds in `expires_in`, which is 14400, four hours. Read that field rather than hard coding the number: a change to the lifetime reaches you in the response before it reaches this page. ## Step 2: Create a payment request Now that you have an access token, create a payment request for your customer's R100 order. ```endpoint POST https://one.ozow.com/v1/payments Authorization: Bearer YOUR_ACCESS_TOKEN Content-Type: application/json ``` **cURL** ```bash curl -X POST "https://one.ozow.com/v1/payments" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "siteCode": "YOUR_SITE_CODE", "amount": { "currency": "ZAR", "value": 100.00 }, "merchantReference": "ORDER-001", "beneficiaryReference": "ONLINESHOP002", "expireAt": "2026-12-31T23:59:59Z", "returnUrl": "https://yourstore.com/order-complete" }' ``` **C#** ```csharp var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue( "Bearer", "YOUR_ACCESS_TOKEN" ); var payload = new { siteCode = "YOUR_SITE_CODE", amount = new { currency = "ZAR", value = 100.00 }, merchantReference = "ORDER-001", beneficiaryReference = "ONLINESHOP002", expireAt = "2026-12-31T23:59:59Z", returnUrl = "https://yourstore.com/order-complete", }; var response = await client.PostAsync( "https://one.ozow.com/v1/payments", new StringContent(JsonSerializer.Serialize(payload), Encoding.UTF8, "application/json") ); var result = await response.Content.ReadAsStringAsync(); Console.WriteLine(result); ``` **PHP** ```php "https://one.ozow.com/v1/payments", CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode([ "siteCode" => "YOUR_SITE_CODE", "amount" => ["currency" => "ZAR", "value" => 100.00], "merchantReference" => "ORDER-001", "beneficiaryReference" => "ONLINESHOP002", "expireAt" => "2026-12-31T23:59:59Z", "returnUrl" => "https://yourstore.com/order-complete", ]), CURLOPT_HTTPHEADER => [ "Authorization: Bearer YOUR_ACCESS_TOKEN", "Content-Type: application/json", ], ]); $response = curl_exec($curl); curl_close($curl); echo $response; ?> ``` **JavaScript** ```javascript const response = await fetch("https://one.ozow.com/v1/payments", { method: "POST", headers: { "Authorization": "Bearer YOUR_ACCESS_TOKEN", "Content-Type": "application/json", }, body: JSON.stringify({ siteCode: "YOUR_SITE_CODE", amount: { currency: "ZAR", value: 100.00 }, merchantReference: "ORDER-001", beneficiaryReference: "ONLINESHOP002", expireAt: "2026-12-31T23:59:59Z", returnUrl: "https://yourstore.com/order-complete", }), }); const data = await response.json(); console.log(data); ``` **Python** ```python import requests response = requests.post( "https://one.ozow.com/v1/payments", headers={ "Authorization": "Bearer YOUR_ACCESS_TOKEN", "Content-Type": "application/json", }, json={ "siteCode": "YOUR_SITE_CODE", "amount": {"currency": "ZAR", "value": 100.00}, "merchantReference": "ORDER-001", "beneficiaryReference": "ONLINESHOP002", "expireAt": "2026-12-31T23:59:59Z", "returnUrl": "https://yourstore.com/order-complete", }, ) print(response.json()) ``` **Successful response** ```json { "links": { "self": "https://one.ozow.com/v1/payments/497f6eca-6276-4993-bfeb-53cbbbba6f08", "transactions": "https://one.ozow.com/v1/payments/497f6eca-6276-4993-bfeb-53cbbbba6f08/transactions" }, "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "status": "Created", "redirectUrl": "https://pay.ozow.com/497f6eca-6276-4993-bfeb-53cbbbba6f08/secure" } ``` ## Step 3: Redirect your customer Take the `redirectUrl` from the response and redirect your customer's browser to it. Ozow will handle the payment experience from here, your customer selects their preferred payment method and completes the payment on Ozow's secure hosted page. By default, Pay by Bank is available on your payment page from the moment your account is active. Additional payment methods; such as Card, Buy Now Pay Later, Crypto, and PayShap; are enabled by the Ozow team on request. Once activated, they appear automatically on your payment page with no additional integration work required on your side. Once the payment is complete, Ozow will redirect your customer back to the `returnUrl` you specified in the payment request. > ⚠️ **Important**: Do not use the redirect response alone to confirm payment status. Always verify > the outcome using a webhook or by checking the transaction status via the API. See Step 4. > ⚠️ **Important**: `returnUrl`, `notifyUrl` and a webhook URL must all be reachable from the > internet. `localhost` is rejected with a `403`, so a tunnel to your machine is what a local > integration needs rather than the address your browser uses. ## Step 4: Handle the outcome Ozow notifies you of the payment outcome in three ways: **Webhook notification**: Ozow sends an HTTP POST to your designated webhook URL when the transaction completes. This is the recommended way to confirm payment status. Set up your webhook endpoint in one of two ways: - **Via the Ozow Dashboard**: navigate to [One API Clients](https://dash.ozow.com/MerchantAdmin/OneAPI/Clients), select your client, and manage webhooks from there - **Via the API**: see the [webhook endpoints](https://hub.ozow.com/api-reference/one-api/tags/webhooks.md) Every webhook notification includes Svix signature headers. Always verify the signature before acting on any notification: | Header | Description | |---|---| | `svix-id` | Unique message identifier, the same if the webhook is resent after a failure | | `svix-timestamp` | Timestamp in seconds since epoch | | `svix-signature` | Base64 encoded signature | [Verify a webhook signature](https://hub.ozow.com/integration-methods/apis/payin/verify-a-webhook.md) has the five steps and a working verifier in four languages, with or without the Svix library. Retrieve your webhook secret with [Get Webhook Secret](https://hub.ozow.com/api-reference/one-api/get-webhooks-id-secret.md). > ⚠️ **Important**: Never process a webhook without first verifying its signature. Do not rely on > the redirect response alone to confirm payment status. For full webhook implementation details see [Redirect to Ozow](https://hub.ozow.com/integration-methods/apis/payin/redirect-to-ozow.md#step-4-handle-the-webhook-notification). **`notifyUrl`**: set `notifyUrl` on the payment request and Ozow also sends the standard Ozow notification, with the same payload and the same hash the Payments API sends on a payin. It is optional and fires only for payments where you set it, so it is there for an integration that already has a Payments API notification handler working. Point it at that handler and nothing about it has to change. > ⚠️ **Important**: If you set `notifyUrl` **and** configure a webhook, both fire for the same > payment. Make your handlers idempotent, keyed on the merchant reference or the transaction ID, or > one payment marks an order paid twice. **Transaction status check**: You can also query the transaction status directly via the API at any time: ```endpoint GET https://one.ozow.com/v1/payments/{id}/transactions Authorization: Bearer YOUR_ACCESS_TOKEN ``` A completed payment returns a transaction whose `status` is `Successful`. The full set is `Incomplete`, `Successful`, `Error`, `Pending` and `Refunded`, which is the transaction's own status rather than the four a webhook maps to; [Transaction and settlement statuses](https://hub.ozow.com/integration-methods/statuses.md) covers the difference. Compare the value without case. An id that matches no payment answers `200` with an empty result list, not a `404`. Check whether you got a transaction back rather than relying on the status code. ## What's next? You've accepted your first payment. Here's where to go from here: - **Set up webhooks**: [Redirect: One API](https://hub.ozow.com/integration-methods/apis/payin/redirect-to-ozow.md) covers webhook setup and verification in full - **Handle edge cases**: learn how to handle failed payments, cancellations, and timeouts - **Explore other integration paths**: [Integration methods](https://hub.ozow.com/integration-methods.md) covers embedded, direct, and no-code options - **Go live**: review the [Building a secure integration](https://hub.ozow.com/getting-started/building-a-secure-integration.md) checklist before switching to your production credentials --- # Redirect to Ozow > Build a redirect payin with One API. Create a payment request, send the customer to Ozow's hosted page, and confirm the result from the webhook. Source: https://hub.ozow.com/integration-methods/apis/payin/redirect-to-ozow/ This guide walks you through a redirect payin integration using One API. Your system creates a payment request, redirects the customer to Ozow's secure hosted payment page, and receives a webhook notification when the payment is complete. > ℹ️ This guide uses **One API**: Ozow's recommended API for all new integrations. It uses OAuth 2.0 > for authentication, and new payment methods and features are released here first. > > Already integrated? If your integration posts to `api.ozow.com` and builds a SHA512 hash, you're > on the Payments API: see [Redirect to Ozow](https://hub.ozow.com/integration-methods/apis/deprecated-integrations/redirect-to-ozow.md) under > Legacy integrations, or [Migrating to One API](https://hub.ozow.com/integration-methods/apis/deprecated-integrations/migrating-to-one-api.md). ## Before you start - You have completed [Prerequisites and onboarding](https://hub.ozow.com/getting-started/prerequisites-and-onboarding.md) - You have a Client ID and Client Secret from the One API Clients section of your [Ozow Dashboard](https://dash.ozow.com/MerchantAdmin/OneAPI/Clients) - You have your site code from the Site section of your Dashboard - Your webhook endpoint is set up and publicly accessible via HTTPS > ℹ️ **Note**: Only users with administrator privileges in the Ozow Dashboard can access the One API > Clients section. ## Environments | Environment | Token endpoint | API base URL | Dashboard | |---|---|---|---| | Production | `https://one.ozow.com/v1/token` | `https://one.ozow.com/v1` | [dash.ozow.com](https://dash.ozow.com) | | Staging | `https://stagingone.ozow.com/v1/token` | `https://stagingone.ozow.com/v1` | [stagingdash.ozow.com](https://stagingdash.ozow.com) | ## How redirect works ```mermaid sequenceDiagram participant C as Customer participant M as Your system participant O as One API participant P as Ozow payment page C->>M: Reaches checkout M->>O: POST /v1/payments O-->>M: Returns redirectUrl M->>C: Redirects customer to redirectUrl C->>P: Completes payment O-->>M: Sends webhook notification M->>M: Verifies webhook signature M-->>C: Updates order and redirects to returnUrl ``` --- ## Core integration ### Step 1: Obtain an access token One API uses OAuth 2.0 Client Credentials authentication. You need an access token before making any API calls. ```endpoint POST https://one.ozow.com/v1/token Content-Type: application/x-www-form-urlencoded ``` **cURL** ```bash curl -X POST "https://one.ozow.com/v1/token" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "client_id=YOUR_CLIENT_ID" \ -d "client_secret=YOUR_CLIENT_SECRET" \ -d "scope=payments" \ -d "grant_type=client_credentials" ``` **C#** ```csharp var client = new HttpClient(); var content = new FormUrlEncodedContent( new[] { new KeyValuePair("client_id", "YOUR_CLIENT_ID"), new KeyValuePair("client_secret", "YOUR_CLIENT_SECRET"), new KeyValuePair("scope", "payments"), new KeyValuePair("grant_type", "client_credentials"), } ); var response = await client.PostAsync("https://one.ozow.com/v1/token", content); var result = await response.Content.ReadAsStringAsync(); ``` **PHP** ```php "https://one.ozow.com/v1/token", CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_POSTFIELDS => http_build_query([ "client_id" => "YOUR_CLIENT_ID", "client_secret" => "YOUR_CLIENT_SECRET", "scope" => "payments", "grant_type" => "client_credentials", ]), CURLOPT_HTTPHEADER => ["Content-Type: application/x-www-form-urlencoded"], ]); $response = curl_exec($curl); curl_close($curl); echo $response; ?> ``` **JavaScript** ```javascript const response = await fetch("https://one.ozow.com/v1/token", { method: "POST", headers: { "Content-Type": "application/x-www-form-urlencoded" }, body: new URLSearchParams({ client_id: "YOUR_CLIENT_ID", client_secret: "YOUR_CLIENT_SECRET", scope: "payments", grant_type: "client_credentials", }), }); const data = await response.json(); ``` **Python** ```python import requests response = requests.post( "https://one.ozow.com/v1/token", data={ "client_id": "YOUR_CLIENT_ID", "client_secret": "YOUR_CLIENT_SECRET", "scope": "payments", "grant_type": "client_credentials", }, ) data = response.json() ``` **Successful response** ```json { "access_token": "mF_9.B5f-4.1JqM", "token_type": "Bearer", "expires_in": "14400", "scope": "payments" } ``` Store the `access_token` and include it in the `Authorization` header of all subsequent requests: ```http Authorization: Bearer YOUR_ACCESS_TOKEN ``` Tokens expire after the number of seconds in `expires_in`, which is 14400, four hours. Read that field rather than hard coding the number: a change to the lifetime reaches you in the response before it reaches this page. If authentication fails, the API returns `401 Unauthorized`. --- ### Step 2: Create a payment request Create a payment request for your customer's order. ```endpoint POST https://one.ozow.com/v1/payments Authorization: Bearer YOUR_ACCESS_TOKEN Content-Type: application/json ``` **cURL** ```bash curl -X POST "https://one.ozow.com/v1/payments" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "siteCode": "YOUR_SITE_CODE", "amount": { "currency": "ZAR", "value": 100.00 }, "merchantReference": "ORDER-001", "beneficiaryReference": "ONLINESHOP002", "expireAt": "2026-12-31T23:59:59Z", "returnUrl": "https://yourstore.com/order-complete" }' ``` **C#** ```csharp var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue( "Bearer", "YOUR_ACCESS_TOKEN" ); var payload = new { siteCode = "YOUR_SITE_CODE", amount = new { currency = "ZAR", value = 100.00 }, merchantReference = "ORDER-001", beneficiaryReference = "ONLINESHOP002", expireAt = "2026-12-31T23:59:59Z", returnUrl = "https://yourstore.com/order-complete", }; var response = await client.PostAsync( "https://one.ozow.com/v1/payments", new StringContent(JsonSerializer.Serialize(payload), Encoding.UTF8, "application/json") ); var result = await response.Content.ReadAsStringAsync(); ``` **PHP** ```php "https://one.ozow.com/v1/payments", CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode([ "siteCode" => "YOUR_SITE_CODE", "amount" => ["currency" => "ZAR", "value" => 100.00], "merchantReference" => "ORDER-001", "beneficiaryReference" => "ONLINESHOP002", "expireAt" => "2026-12-31T23:59:59Z", "returnUrl" => "https://yourstore.com/order-complete", ]), CURLOPT_HTTPHEADER => [ "Authorization: Bearer YOUR_ACCESS_TOKEN", "Content-Type: application/json", ], ]); $response = curl_exec($curl); curl_close($curl); echo $response; ?> ``` **JavaScript** ```javascript const response = await fetch("https://one.ozow.com/v1/payments", { method: "POST", headers: { "Authorization": "Bearer YOUR_ACCESS_TOKEN", "Content-Type": "application/json", }, body: JSON.stringify({ siteCode: "YOUR_SITE_CODE", amount: { currency: "ZAR", value: 100.00 }, merchantReference: "ORDER-001", beneficiaryReference: "ONLINESHOP002", expireAt: "2026-12-31T23:59:59Z", returnUrl: "https://yourstore.com/order-complete", }), }); const data = await response.json(); ``` **Python** ```python import requests response = requests.post( "https://one.ozow.com/v1/payments", headers={ "Authorization": "Bearer YOUR_ACCESS_TOKEN", "Content-Type": "application/json", }, json={ "siteCode": "YOUR_SITE_CODE", "amount": {"currency": "ZAR", "value": 100.00}, "merchantReference": "ORDER-001", "beneficiaryReference": "ONLINESHOP002", "expireAt": "2026-12-31T23:59:59Z", "returnUrl": "https://yourstore.com/order-complete", }, ) data = response.json() ``` **Key request fields** | Field | Type | Required | Description | |---|---|---|---| | `siteCode` | string | Yes | Your Ozow site code | | `amount.currency` | string | Yes | Must be `ZAR` | | `amount.value` | number | Yes | Payment amount | | `merchantReference` | string | Yes | Your internal order reference | | `beneficiaryReference` | string | Usually | The reference that appears on your bank statement for the payment. Letters and numbers only | | `expireAt` | string | Yes | Payment request expiry in RFC 3339 format | | `returnUrl` | string | Yes | URL to redirect the customer to after payment | > ⚠️ **Important**: Send `beneficiaryReference`. The contract marks it optional because a site can be > configured either way, and most are configured to require it. Leaving it out of a site that wants > it answers `400` with `Error occurred creating merchant request (Parameter 'Bank reference > missing')`, which does not name the field it means. For the full list of request fields see [Create a payment](https://hub.ozow.com/api-reference/one-api/post-payments.md). **Successful response** ```json { "links": { "self": "https://one.ozow.com/v1/payments/497f6eca-6276-4993-bfeb-53cbbbba6f08", "cancel": "https://one.ozow.com/v1/payments/497f6eca-6276-4993-bfeb-53cbbbba6f08/cancel", "transactions": "https://one.ozow.com/v1/payments/497f6eca-6276-4993-bfeb-53cbbbba6f08/transactions" }, "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "status": "Created", "redirectUrl": "https://pay.ozow.com/497f6eca-6276-4993-bfeb-53cbbbba6f08/secure" } ``` --- ### Step 3: Redirect the customer Redirect your customer's browser to the `redirectUrl` from the response. Ozow displays the payment page where the customer selects their preferred payment method and completes the payment. **Send them to the URL you were given, and do not build one.** Its shape is Ozow's to change, and a URL assembled from the payment id is a URL that stops working without notice. `status` on the response is `Created`. Compare it without case. Once the customer completes or cancels the payment, Ozow redirects them back to your `returnUrl`. > ℹ️ **Note**: Pay by Bank is available by default. Additional payment methods such as Capitec Pay, > Buy Now Pay Later, and PayShap Request are enabled by Ozow on request. Once activated, they appear > automatically on the payment page with no additional integration work required. > ⚠️ **Important**: Do not use the customer's return to your `returnUrl` as confirmation that a > payment was successful. Always confirm payment status via a verified webhook notification or an > API status check. --- ### Step 4: Handle the webhook notification Ozow sends a webhook notification to your endpoint when a transaction completes. One API uses [Svix](https://www.svix.com/) to deliver webhooks. **There are two ways to be told, and you choose them independently.** | | Webhooks | `notifyUrl` | |---|---|---| | How you turn it on | The Ozow Dashboard or the webhook endpoints | Set `notifyUrl` on the payment request | | What arrives | The events below, signed with Svix headers | The same notification the Payments API sends on a payin, with the same payload and the same hash | | When it fires | Every transaction | Every payment where you set `notifyUrl` | Webhooks are the recommended path and the rest of this step covers them. `notifyUrl` is optional and exists so that an integration already handling the Payments API notification keeps working: point it at your existing handler and the payload and hash are the ones it already verifies. > ⚠️ **Important**: If you configure both, **both fire for the same payment**. Your handlers must > be idempotent, keyed on the merchant reference or the transaction ID, or one payment marks an > order paid twice. If you set neither, nothing is delivered and you must poll [Get Transactions](https://hub.ozow.com/api-reference/one-api/get-payments-id-transactions.md) instead, which is slower and which Step 5 covers. **Setting up your webhook endpoint** Set up your webhook endpoint in one of two ways: - **Via the Ozow Dashboard**: navigate to [One API Clients](https://dash.ozow.com/MerchantAdmin/OneAPI/Clients), select your client, and manage webhooks from there - **Via the API**: [List Webhook Subscriptions](https://hub.ozow.com/api-reference/one-api/get-webhooks.md) to see what you already have, then [Create Webhook Subscription](https://hub.ozow.com/api-reference/one-api/post-webhooks.md) for what you do not > ⚠️ **Important**: List before you create. Creating a subscription that duplicates one you already > have delivers every event twice, and the second delivery is indistinguishable from the first, so > a handler that is not idempotent processes the same payment again. A deploy script that creates a > subscription on every run is the usual way this happens. **Available webhook events** | Event | Description | |---|---| | [`transaction.complete`](https://hub.ozow.com/api-reference/one-api/webhooks/transaction-complete.md) | A transaction has completed: check the `status` field to determine if it was successful or resulted in an error | | [`refund.complete`](https://hub.ozow.com/api-reference/one-api/webhooks/refund-complete.md) | A refund has completed: check the `status` field for the refund result | | [`subscription.authorization.success`](https://hub.ozow.com/api-reference/one-api/webhooks/subscription-authorization-success.md) | A customer approved a subscription consent ⚠️ Beta, subject to change | | [`subscription.authorization.failed`](https://hub.ozow.com/api-reference/one-api/webhooks/subscription-authorization-failed.md) | A consent was not approved ⚠️ Beta, subject to change | | [`subscription.transaction.success`](https://hub.ozow.com/api-reference/one-api/webhooks/subscription-transaction-success.md) | An individual collection succeeded ⚠️ Beta, subject to change | | [`subscription.transaction.failed`](https://hub.ozow.com/api-reference/one-api/webhooks/subscription-transaction-failed.md) | An individual collection failed ⚠️ Beta, subject to change | | [`subscription.completed`](https://hub.ozow.com/api-reference/one-api/webhooks/subscription-completed.md) | A subscription took all its scheduled occurrences ⚠️ Beta, subject to change | | [`subscription.canceled`](https://hub.ozow.com/api-reference/one-api/webhooks/subscription-canceled.md) | A subscription was cancelled ⚠️ Beta, subject to change. One `l`, unlike `Cancelled` elsewhere | | [`subscription.expired`](https://hub.ozow.com/api-reference/one-api/webhooks/subscription-expired.md) | An authorisation lapsed before the subscription became active ⚠️ Beta, subject to change | Subscribe to the name exactly as written. An event name the service does not know is rejected, so a subscription to something close is a subscription that never fires. **Message types** When setting up your webhook subscription you can choose how much data is included in each notification: | Message type | What it includes | |---|---| | `thin` | `id`, `status` and `reason` | | `full` | The transaction's fields, in the same shape the Payments API notification uses | Choose `full` if you need transaction details in the webhook payload. Choose `thin` if you only need the status and will query the API for details separately. > ⚠️ **Important**: `full` is implemented for `transaction.complete` and `refund.complete` only. A > subscription event registered as `full` delivers nothing. **What arrives** Every delivery has the same [envelope](https://hub.ozow.com/api-reference/one-api/schemas/webhook-envelope.md). `data` is [`WebhookEventData`](https://hub.ozow.com/api-reference/one-api/schemas/webhook-event-data.md) when the subscription asked for `thin`, [`TransactionCompleteFullData`](https://hub.ozow.com/api-reference/one-api/schemas/transaction-complete-full-data.md) for a `full` subscription to `transaction.complete`, and [`RefundCompleteFullData`](https://hub.ozow.com/api-reference/one-api/schemas/refund-complete-full-data.md) for a `full` subscription to `refund.complete`. Every value in a `full` payload is a string, the amount and the flags included. ```json { "type": "transaction.complete", "timestamp": "2026-03-14T09:30:00Z", "data": { "id": "00000000-0000-0000-0000-000000000000", "status": "Successful", "reason": null } } ``` `id` is the transaction, refund or subscription the event is about. `reason` carries the status message and is null when there is nothing to say. **The `status` values for `transaction.complete`** These are not the transaction statuses on the [statuses page](https://hub.ozow.com/integration-methods/statuses.md): the webhook maps them down to four. | `status` | Sent when the transaction is | |---|---| | `Successful` | `Complete` | | `Incomplete` | `Created` | | `Pending` | `Pending` or `PendingInvestigation` | | `Error` | anything else, including `Cancelled`, `Abandoned`, `Voided` and `Unknown` | **A cancelled payment arrives as `Error`, not as `Cancelled`.** `reason` tells you which it was. Switch on these four and read `reason` for the detail; do not expect the status names the transaction itself carries. For `refund.complete`, `status` is `Pending`, `Failed`, `Complete`, `Submitted`, `Cancelled`, `Returned` or `Invalid`. Those are the `thin` values. A `full` subscription carries the refund's own status in `Status`, unmapped, so `PendingInvestigation` and `Error` arrive as themselves rather than as `Pending` and `Failed`. Handle both if you are on `full`. **Verifying the webhook signature** Every webhook notification includes Svix signature headers. You must verify the signature before acting on any notification. | Header | Description | |---|---| | `svix-id` | Unique message identifier, the same if the webhook is resent after a failure | | `svix-timestamp` | Timestamp in seconds since epoch | | `svix-signature` | Base64 encoded signature | [Verify a webhook signature](https://hub.ozow.com/integration-methods/apis/payin/verify-a-webhook.md) has the five steps of the check and a working verifier in `csharp`, `php`, `python` and `javascript`, with or without the Svix library. To retrieve the secret for your webhook, use [Get Webhook Secret](https://hub.ozow.com/api-reference/one-api/get-webhooks-id-secret.md). > ⚠️ **Important**: Never process a webhook notification without first verifying its signature. Log > and alert on verification failures: do not silently discard them. --- ### Step 5: Confirm the transaction outcome After verifying the webhook, check the transaction status and update your order. ```mermaid flowchart LR A[Receive webhook] --> B{Verify signature} B -->|Invalid| C[Log and alert - do not process] B -->|Valid| D{Check transaction status} D -->|Complete| E[Credit order and fulfil] D -->|Cancelled| F[Return customer to checkout] D -->|Error| G[Do not credit - investigate] ``` You can also check transaction status directly via the API at any time: ```endpoint GET https://one.ozow.com/v1/payments/{id}/transactions Authorization: Bearer YOUR_ACCESS_TOKEN ``` Replace `{id}` with the payment ID returned in Step 2. > ℹ️ **Note**: Handle duplicate webhook notifications idempotently. Ozow may send the same > notification more than once. Processing the same notification twice must not result in > double-crediting an order. --- ### Step 6: Cancel a payment If your customer abandons checkout or you need to cancel an order before the customer completes payment, you can cancel the payment request using the cancel link returned in the payment response. ```endpoint POST https://one.ozow.com/v1/payments/{id}/cancel Authorization: Bearer YOUR_ACCESS_TOKEN ``` A successfully cancelled payment will no longer be accessible to the customer via the `redirectUrl`. If the customer attempts to use the link after cancellation they will see an error. > ⚠️ **Important**: You can only cancel a payment that has not yet been completed. Do not attempt to > cancel a payment with a `complete` status: use the refunds flow instead. See the [One API > reference](https://hub.ozow.com/api-reference/one-api.md) for details. --- ## Optional features ### Standalone button A standalone button lets you surface a specific Ozow payment method as a dedicated button on your checkout page. Instead of showing a generic payment page where the customer selects their payment method, a standalone button takes the customer directly to a specific payment method; for example Capitec Pay, Buy Now Pay Later, or PayShap. Adding a standalone button to your checkout removes an extra step for the customer, increases awareness of specific payment methods, and can improve conversion rates. > ⚠️ **Important**: Do not display a standalone button for a payment method until you have received > confirmation from Ozow that your account has been enabled for that payment method. > ℹ️ **Digital wallets**: Apple Pay and Google Pay cannot be offered as standalone buttons using > this method. If you want to offer these as dedicated payment options at checkout, use the [Wallet > SDK](https://hub.ozow.com/integration-methods/apis/payin/embedded-wallet.md). **Implementation** Include the `institutionId` field in your payment request. When a valid `institutionId` is included, the customer is taken directly to that payment method. The `institutionId` for each payment method is available on the relevant [Payment products](https://hub.ozow.com/payment-products.md) page. ```json { "siteCode": "YOUR_SITE_CODE", "region": "ZA", "amount": { "currency": "ZAR", "value": 100.00 }, "merchantReference": "ORDER-001", "expireAt": "2026-12-31T23:59:59Z", "returnUrl": "https://yourstore.com/order-complete", "institutionId": "YOUR_INSTITUTION_ID" } ``` --- ### Customer Identity Verification If your business operates in a high-risk industry, you are required to implement Customer Identity Verification before going live with Bank API payment methods. To implement it in One API, pass the `payer.identity` object in the payment request: ```json { "siteCode": "YOUR_SITE_CODE", "amount": { "currency": "ZAR", "value": 100.00 }, "merchantReference": "ORDER-001", "expireAt": "2026-12-31T23:59:59Z", "returnUrl": "https://yourstore.com/order-complete", "payer": { "id": "CUSTOMER-123", "name": "Firstname Lastname", "identity": { "type": "said", "country": "ZA", "identifier": "0000000000000" } } } ``` **Identity fields** | Field | Type | Description | |---|---|---| | `payer.identity.type` | string | `said` for South African ID, `passport` for foreign passport | | `payer.identity.country` | string | ISO 3166 Alpha-2 country code, `ZA` for South Africa | | `payer.identity.identifier` | string | The verified ID or passport number | For full details on Customer Identity Verification requirements see [Customer Identity Verification](https://hub.ozow.com/integration-methods/apis/payin/identity-verification.md). --- ## Next steps - Review the [Building a secure integration](https://hub.ozow.com/getting-started/building-a-secure-integration.md) checklist before going live - Test your integration using [Payin test cases](https://hub.ozow.com/integration-methods/testing/payin-test-cases-one-api.md) - Switch your base URL from staging to production when you are ready to go live - See the [One API reference](https://hub.ozow.com/api-reference/one-api.md) for the full technical specification --- # Verify a webhook signature > The signature on a One API webhook, the five steps that check it, and a working implementation in four languages. Source: https://hub.ozow.com/integration-methods/apis/payin/verify-a-webhook/ Your webhook URL is public. Anyone who finds it can post a `transaction.complete` to it claiming a payment succeeded, and the only thing separating that from a real delivery is the signature. Check it before you read a single field of the body. This page covers the **One API** webhook signature. The Payments API notification is authenticated differently, with a `Hash` field over the payload: see the [hash calculator](https://hub.ozow.com/integration-methods/apis/deprecated-integrations/hash-calculator.md) for that one. > ⚠️ **Important**: Verify against the exact bytes you received. The signature covers the body > byte for byte, and a framework that parses the request as JSON and hands you the object has > already thrown those bytes away: serialising it back reorders keys and changes whitespace, and > nothing matches. Reach for the raw body explicitly. In Express that is `express.raw()`, in > ASP.NET Core `EnableBuffering` and reading the stream yourself, in Flask `request.get_data()`, > in Laravel `$request->getContent()`. ## Use the library where you can Ozow delivers webhooks through [Svix](https://www.svix.com/), and Svix publishes a verification library for most languages. It gets the constant-time comparison, the replay window and the signature list right, and it is the shortest path to a correct handler. ```javascript // svix 2.x. `verify` throws on a bad signature and returns nothing. import { Webhook } from "svix"; const webhook = new Webhook(process.env.OZOW_WEBHOOK_SECRET); webhook.verify(rawBody, { "svix-id": headers["svix-id"], "svix-timestamp": headers["svix-timestamp"], "svix-signature": headers["svix-signature"], }); const event = JSON.parse(rawBody); ``` > ⚠️ **Pin the major version, and read its signature before you upgrade**: `verify` returned the > parsed body on `svix` 1.x and returns nothing on 2.x. A handler that keeps `const event = > webhook.verify(...)` across that upgrade reads `undefined`, fails after it has already replied > `200`, and looks from our side like a delivery that succeeded. The rest of this page is what that library does, for when you would rather not add one. ## The algorithm Every delivery carries three headers: | Header | What it holds | |---|---| | `svix-id` | The message identifier, unchanged across retries of the same event | | `svix-timestamp` | When the delivery was signed, in seconds since the epoch | | `svix-signature` | One or more signatures, space separated, each written `v1,` | Five steps, and all five are load bearing: 1. **Require all three headers.** A delivery missing any of them is not one of ours. 2. **Check the timestamp is within five minutes of now**, in either direction. Without this, a signature captured once stays valid forever and a recorded delivery can be replayed at will. 3. **Turn the secret into key bytes.** The secret from [Get Webhook Secret](https://hub.ozow.com/api-reference/one-api/get-webhooks-id-secret.md) arrives as `whsec_` followed by Base64. Strip the prefix and Base64-decode the rest. The key is those raw bytes, not the string. 4. **Build the signed string and take its HMAC.** The string is the message id, the timestamp and the raw body joined by full stops: `{svix-id}.{svix-timestamp}.{body}`. HMAC-SHA256 it with the key bytes and Base64-encode the digest. 5. **Compare against every `v1` signature in the header**, with a constant-time comparison. The header can carry more than one while a secret is being rotated, and a match on any of them is a pass. Ignore any entry whose version is not `v1`. ## A verifier Each of these returns true only if the delivery is genuine, current and intact. None of them needs a dependency beyond the standard library. **C#** ```csharp using System.Security.Cryptography; using System.Text; const int ToleranceSeconds = 300; static bool IsFromOzow( string secret, string svixId, string svixTimestamp, string svixSignature, string rawBody ) { if (!long.TryParse(svixTimestamp, out var sent)) return false; if (Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeSeconds() - sent) > ToleranceSeconds) return false; var key = Convert.FromBase64String( secret.StartsWith("whsec_", StringComparison.Ordinal) ? secret["whsec_".Length..] : secret ); using var hmac = new HMACSHA256(key); var digest = hmac.ComputeHash(Encoding.UTF8.GetBytes($"{svixId}.{sent}.{rawBody}")); var expected = Encoding.UTF8.GetBytes(Convert.ToBase64String(digest)); foreach (var candidate in svixSignature.Split(' ')) { var parts = candidate.Split(',', 2); if (parts.Length != 2 || parts[0] != "v1") continue; // Returns false on a length mismatch rather than throwing, and takes the // same time whether the first byte differs or the last one does. if (CryptographicOperations.FixedTimeEquals(Encoding.UTF8.GetBytes(parts[1]), expected)) return true; } return false; } ``` **PHP** ```php TOLERANCE_SECONDS) { return false; } $key = base64_decode( str_starts_with($secret, "whsec_") ? substr($secret, 6) : $secret, true, ); if ($key === false) { return false; } $expected = base64_encode( hash_hmac("sha256", "{$svixId}.{$sent}.{$rawBody}", $key, true), ); foreach (explode(" ", $svixSignature) as $candidate) { [$version, $signature] = array_pad( explode(",", $candidate, 2), 2, null, ); if ($version !== "v1" || $signature === null) { continue; } // hash_equals, never ===. A plain comparison returns early on the first // differing byte and leaks how much of a guess was right. if (hash_equals($expected, $signature)) { return true; } } return false; } ``` **JavaScript** ```javascript import { createHmac, timingSafeEqual } from "node:crypto"; const TOLERANCE_SECONDS = 300; /** `rawBody` is a Buffer, straight off the request. Never a re-serialised object. */ function isFromOzow(secret, headers, rawBody) { const id = headers["svix-id"]; const timestamp = headers["svix-timestamp"]; const signature = headers["svix-signature"]; if (!id || !timestamp || !signature) return false; const sent = Number(timestamp); if (!Number.isInteger(sent)) return false; if (Math.abs(Date.now() / 1000 - sent) > TOLERANCE_SECONDS) return false; const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64"); const expected = Buffer.from( createHmac("sha256", key) .update(`${id}.${sent}.`) .update(rawBody) .digest("base64"), ); return signature.split(" ").some((candidate) => { const [version, value] = candidate.split(","); if (version !== "v1" || !value) return false; const given = Buffer.from(value); // timingSafeEqual throws on a length mismatch, so the lengths are checked first. return given.length === expected.length && timingSafeEqual(given, expected); }); } ``` **Python** ```python import base64 import hashlib import hmac import time TOLERANCE_SECONDS = 300 def is_from_ozow( secret: str, svix_id: str, svix_timestamp: str, svix_signature: str, raw_body: bytes, ) -> bool: try: sent = int(svix_timestamp) except ValueError: return False if abs(time.time() - sent) > TOLERANCE_SECONDS: return False key = base64.b64decode(secret.removeprefix("whsec_")) signed = f"{svix_id}.{sent}.".encode() + raw_body expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode() for candidate in svix_signature.split(" "): version, _, signature = candidate.partition(",") if version != "v1": continue if hmac.compare_digest(expected, signature): return True return False ``` ## What goes wrong The first two announce themselves the moment you test. The last three pass every test you are likely to write and fail in production, which is why they are worth reading twice. | Mistake | What happens | |---|---| | **The secret used as a string** | The key is the Base64-decoded bytes after `whsec_`. Using the characters gives a digest that never matches anything. | | **The body parsed before it is verified** | Re-serialising changes the bytes. Nothing matches, on every delivery. | | **No timestamp check** | Every signature stays valid forever. One captured delivery can be replayed for as long as the secret lives. | | **`==` instead of a constant-time compare** | The comparison returns as soon as two bytes differ, and how long it took says how much of a guess was right. | | **Only the first signature checked** | `svix-signature` carries both the old and the new signature while a secret is rotated. A verifier that reads one of them starts rejecting real deliveries mid-rotation. | ## Check your verifier Start offline. Svix publishes a signature you can check against without sending anything, which separates a wrong implementation from a wrong endpoint before either can confuse the other: ```text secret whsec_plJ3nmyCDGBKInavdOK15jsl body {"event_type":"ping","data":{"success":true}} svix-id msg_loFOjxBNrRLzqYUf timestamp 1731705121 signature v1,rAvfW3dJ/X/qxhsaXPOyyCGmRKsaKWcsNccKXlIktD0= ``` Feed those five values to your verifier and it must produce that signature. The timestamp is from 2024, so a verifier that checks the replay window rejects the delivery even when the signature is right: check the signature it computed rather than the answer it returned, or hold the clock at `1731705121` for the test. Then send yourself a real delivery and confirm all four of these, in this order: 1. **An untouched delivery passes.** Anything else and the rest of the list means nothing. 2. **One changed byte of the body fails.** Change a digit of the amount and replay it. 3. **One changed character of `svix-signature` fails.** 4. **The same delivery replayed an hour later fails.** If it passes, step 2 of the algorithm is missing. A verifier that rejects a delivery must log it and alert. A signature that does not match is either a bug of ours or somebody probing your endpoint, and both are worth a person looking at them. Never discard one quietly. --- # Payin test cases > The payments to run before you go live with Ozow, what each one delivers, and a handler that survives all of them. Source: https://hub.ozow.com/integration-methods/testing/payin-test-cases-one-api/ These test cases are recommended but not mandatory for go-live. Run at least the core ones before you accept real payments. The optional ones apply only if you have built the feature they test. Building on the Payments API instead? Use [Payin test cases: Payments API](https://hub.ozow.com/integration-methods/apis/deprecated-integrations/payin-test-cases-payments-api.md); the statuses and the field names are different. > ℹ️ **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). ## What arrives, and what it says A One API payment tells you its outcome on a [`transaction.complete`](https://hub.ozow.com/api-reference/one-api/webhooks/transaction-complete.md) webhook, and also on the standard Ozow notification when you set `notifyUrl` on the payment request. Configure both and both fire, which is what Test 5 exists for. The webhook carries [one envelope](https://hub.ozow.com/api-reference/one-api/schemas/webhook-envelope.md) whatever happened, and `data.status` is one of four values: | `data.status` | The transaction was | |---|---| | `Successful` | completed | | `Incomplete` | created and not taken further | | `Pending` | pending, or under investigation | | `Error` | anything else, including cancelled, abandoned and voided | **There is no `Cancelled` to test for.** A cancellation arrives as `Error`, and `data.reason` says which kind of failure it was. A handler that switches on `Cancelled` never runs that branch. ## A handler that passes every test below The tests are all the same handler seen from different angles: verify, then read the status, then update the order once. This is that handler, written against `svix` 2.x. ```javascript import { Webhook } from "svix"; // From Get Webhook Secret. Keep it out of source control. const webhook = new Webhook(process.env.OZOW_WEBHOOK_SECRET); app.post( "/ozow/webhook", express.raw({ type: "application/json" }), (req, res) => { try { // Verify against the raw body. Parsing first and re-serialising changes // the bytes and the signature will not match. Test 4. webhook.verify(req.body, { "svix-id": req.headers["svix-id"], "svix-timestamp": req.headers["svix-timestamp"], "svix-signature": req.headers["svix-signature"], }); } catch { // Rejected, logged, and never acted on. return res.status(400).send("invalid signature"); } // `verify` returns nothing on svix 2.x: it throws on a bad signature and // that is the whole result. Parse after it, never before. On svix 1.x it // returned the parsed body, so a handler carried over from that version // reads `undefined` here and fails after it has already acknowledged. const event = JSON.parse(req.body); // Acknowledge first. Ozow retries anything that is not a 2xx, and a slow // database is not a reason to be sent the same event again. res.sendStatus(200); const { type, data } = event; if (type !== "transaction.complete") return; // The same event can arrive more than once, and a payment can also notify // twice when `notifyUrl` is set alongside the webhook. Test 5. if (!claimOnce(data.id)) return; switch (data.status) { case "Successful": fulfilOrder(data.id); break; case "Pending": // Not an outcome. Leave the order alone and wait for the next event. break; case "Incomplete": case "Error": // Everything that is not a payment: cancelled, abandoned, voided, failed. failOrder(data.id, data.reason); break; default: // A value this code has never seen. Do not guess what it means. alertOps(`unknown status ${data.status} on ${data.id}`); } }, ); ``` `claimOnce` is whatever makes the update happen once in your system: a unique constraint on the transaction id, a row lock, or a conditional write. Deciding by "have I seen this id" in memory does not survive two instances. > ⚠️ **Important**: Update the order from this handler, never from the browser returning to your > success URL. A customer who closes the tab still has to end up with the right order state. --- ## Core test cases ### Test 1: Successful payment Verify that your integration handles a completed payment end to end. **Steps** 1. Create a payment with [`POST /payments`](https://hub.ozow.com/api-reference/one-api/post-payments.md) 2. Complete the payment on the Ozow payment page with a valid payment method 3. Verify that your endpoint receives the webhook 4. Verify that the Svix signature validates 5. Verify that the order is updated 6. Verify that the customer reaches your success URL **Expected outcomes** - `type` is `transaction.complete` and `data.status` is `Successful` - Order credited and fulfilled once - Customer redirected to the success URL --- ### Test 2: Cancelled payment Verify that a cancellation does not credit the order. **Steps** 1. Create a payment 2. Cancel it on the Ozow payment page 3. Verify that your endpoint receives the webhook 4. Verify that the order is not credited 5. Verify that the customer reaches your cancel URL **Expected outcomes** - `data.status` is **`Error`**, not `Cancelled`, with the detail in `data.reason` - Order not credited - Customer redirected to the cancel URL --- ### Test 3: Failed payment Verify that a failure does not credit the order. **Steps** 1. Create a payment 2. Attempt a payment that fails 3. Verify that your endpoint receives the webhook 4. Verify that the order is not credited 5. Verify that the customer reaches your error URL **Expected outcomes** - `data.status` is `Error`, with the reason in `data.reason` - Order not credited - Customer redirected to the error URL --- ### Test 4: Signature verification Verify that verification actually rejects something. **Steps** 1. Complete a successful test payment and keep the delivery 2. Verify it with your implementation and confirm it passes 3. Change one byte of the body, or one character of `svix-signature`, and replay it 4. Confirm the tampered delivery fails verification and is not processed **Expected outcomes** - The genuine delivery passes - The tampered delivery is rejected, logged, and updates nothing - Verification runs against the raw body, not a re-serialised object --- ### Test 5: The same outcome twice Verify that one payment updates one order once. > ℹ️ **Note**: Ozow retries a delivery your endpoint did not acknowledge, and a payment with both a > webhook and `notifyUrl` reports twice by design. Both look like a duplicate to your handler. **Steps** 1. Complete a successful test payment 2. Deliver the same event to your endpoint a second time 3. If you have set `notifyUrl` as well, confirm what that notification does to the same order **Expected outcomes** - The second delivery is recognised and changes nothing - The order is credited once - Nothing throws --- ### Test 6: Transaction status check Verify that you can ask, rather than wait. **Steps** 1. Complete a test payment and note the payment id 2. Call [`GET /payments/{id}/transactions`](https://hub.ozow.com/api-reference/one-api/get-payments-id-transactions.md) 3. Compare the status with the outcome you were sent **Expected outcomes** - The call returns the transaction - Its status matches the payment's outcome > ℹ️ **Note**: This endpoint returns the transaction's own status, which is the full set on the > [statuses page](https://hub.ozow.com/integration-methods/statuses.md), not the four the webhook maps to. A payment the webhook reports > as `Complete` reads `Successful` here. Compare without case. --- ## Optional test cases Run these only if you have built the feature. ### Test 7: Standalone button Verify that a button opens the payment method it names. **Steps** 1. Build the standalone button with the correct `institutionId` 2. Create a payment with that field set 3. Verify that the Ozow payment page opens on that payment method **Expected outcomes** - The named payment method is shown - The customer is routed to it without choosing again --- ### Test 8: Customer Identity Verification Run this only if your business is in a high-risk industry and Customer Identity Verification is required. **Steps** 1. Create a payment with a verified customer identity in `payer.identity` 2. Verify that the page offers only payment methods linked to that identity 3. Verify that unlinked payment methods are hidden 4. Create a payment with no identity and verify which methods are offered **Expected outcomes** - Only linked payment methods are offered when an identity is passed - The behaviour without an identity is what you expect for your account --- # Background Context for the above. Nothing here is implemented against. --- # How Ozow works > How Ozow connects you to South African banks and payment methods, and the two directions money moves: payins from customers, payouts to recipients. Source: https://hub.ozow.com/getting-started/ Ozow is a payment infrastructure layer that connects merchants to multiple payment methods and banking rails. Instead of building separate integrations for each bank or payment method, you integrate with Ozow to gain access to the full suite of Ozow payment products. ## The two directions of money movement Every Ozow integration moves money in one of two directions. **Payin**: a customer pays you. The customer initiates the payment, Ozow processes it, and you receive the funds. This covers checkout and any other payment collection. **Payout**: you send funds to a recipient. Your system initiates the transfer, Ozow processes it, and the recipient receives the funds in their bank account. This covers disbursements, refunds to bank accounts, and bulk payments. The distinction runs through everything: different APIs, different credentials, different approval processes, and a different structure in these docs. Work out which direction you need before you start. The [Integration methods](https://hub.ozow.com/integration-methods.md) section is organised around it. ## One integration, every way to pay Payment methods are enabled on your Ozow account, not in your code. Pay by Bank is enabled by default. Other methods you opt into (card, PayShap Request, voucher, buy now pay later, crypto) are enabled by Ozow on your account, and they then appear on the Ozow payment page automatically. You don't build a new integration or call a different endpoint for each one. This means you can go live with Pay by Bank and add methods later as a commercial decision rather than a development project. ## The core payment flows ### Payin ```mermaid sequenceDiagram participant C as Customer participant M as Your system participant O as Ozow C->>M: Reaches checkout M->>O: Creates payment request O-->>M: Returns payment URL M->>C: Sends customer to Ozow C->>O: Completes payment O-->>M: Notifies your webhook of the outcome M->>O: Verifies the status M-->>C: Updates the order ``` Two things to notice. The payment request is created by **your server**, never by the customer's browser. And the outcome arrives on **your webhook**, not in the customer's redirect back to your site; the customer landing on your success page is not proof of payment. See [Building a secure integration](https://hub.ozow.com/getting-started/building-a-secure-integration.md). ### Payout There is no customer-facing step. The whole flow happens between your backend and Ozow. ```mermaid sequenceDiagram participant M as Your system participant O as Ozow participant R as Recipient bank M->>O: Checks payout availability M->>O: Sends payout request O->>M: Calls your verification webhook M-->>O: Confirms the payout O->>R: Submits the payout to the bank R-->>O: Confirms the outcome O-->>M: Notifies your webhook of the final status ``` Before Ozow moves any money, it calls back to your system to confirm the payout is genuine. If that call fails or can't be reached, the payout does not proceed. That's deliberate, and it's why payout integrations require testing and sign-off before they go live. ## Getting paid: transactions and settlements A completed transaction is not money in your bank account. These are two separate stages with two separate status vocabularies. ```mermaid flowchart LR A["Customer pays"] --> B["Transaction completes"] B --> C["Included in a settlement"] C --> D["Funds in your bank account"] ``` The transaction status tells you whether the customer's payment succeeded. The settlement status tells you whether the money has actually reached you. Settlement happens on a delay that depends on the payment method. Use transaction status to fulfil orders. Use settlement status to reconcile your bank account. See [Transaction and settlement statuses](https://hub.ozow.com/integration-methods/statuses.md). ## Paying out: your float Money leaving Ozow doesn't come out of your incoming payments. It comes from a **float**: a balance you pre-fund by transferring money to Ozow. Both payouts and refunds draw on the float. If it's empty, they won't process. Payins don't need a float at all, so if you're only collecting payments you can ignore this entirely. See [Float top-up](https://hub.ozow.com/payment-products/settlements-and-float/float-top-up.md). ## Environments Ozow provides separate staging and production environments. They're completely isolated, and staging credentials are different from your production credentials. Testing requirements differ by direction. Payin integrations can go straight to production. We recommend working through the [payin test cases](https://hub.ozow.com/integration-methods/testing/payin-test-cases-one-api.md), but you don't need to submit anything. Payout integrations require mandatory staging testing and formal sign-off from Ozow before they're enabled in production. **Getting your credentials:** - **Production credentials** are available to you directly in the [Ozow Dashboard](https://dash.ozow.com). Ozow will never send them to you. - **Staging credentials** are issued on request. Ask your account manager or contact [support@ozow.com](mailto:support@ozow.com). > 🚨 Ozow will never share your production credentials with you, and will never ask you for them. If > anyone contacts you offering to send production credentials, or asking you to share yours, treat > it as fraudulent and report it to [support@ozow.com](mailto:support@ozow.com). ## Where to go next How you integrate depends on how much control you want over the payment experience and how much you want to build, from no-code payment requests through to a full API integration. Head to [Integration methods: overview](https://hub.ozow.com/integration-methods.md) to choose the right path. --- # Prerequisites and onboarding > What to have in place before you write any code: a merchant account, Dashboard access, your credentials, and payout eligibility if you need it. Source: https://hub.ozow.com/getting-started/prerequisites-and-onboarding/ Before you start integrating Ozow, make sure you have everything in place. This page covers what you need before writing a single line of code. ## 1. Register as an Ozow merchant You need an active Ozow merchant account before you can integrate. If you don't have one yet, [join our merchant family](https://ozow.com/merchants) or speak to your account manager to get set up. If you signed up through a commercial manager or already have an account, you can skip this step and log in to the [Ozow Dashboard](https://dash.ozow.com) directly. If you need assistance with your account, contact [support@ozow.com](mailto:support@ozow.com) or reach out to your account manager. ## 2. Access the Ozow Dashboard Once your merchant account is active, you can log in to your [Ozow Dashboard](https://dash.ozow.com). The Dashboard is where you'll find everything you need to begin your integration. ## 3. Retrieve your credentials Which credentials you need depends on the API you are integrating against. Collect the row for yours and ignore the rest. | | One API | Payments API | Payouts API | |---|---|---|---| | Client ID and Client Secret | **Yes** | No | No | | API key | No | Yes | Yes, a **different** key | | Private key | No | Yes, to sign the hash | Yes, to sign the hash | | Where to find them | One API Clients | Merchant Details and Site | Issued once payouts are approved | **On One API, the Client ID and Client Secret are all you need.** You exchange them for an access token. There is no API key to send and no hash to compute. **On the Payments API and the Payouts API you need both keys, and they do different things.** The API key goes in the `ApiKey` header. The private key is never sent: you use it to compute the `hashCheck` field on the request, and again to verify the hash on a notification. **The Payouts API takes its own API key, not the one the Payments API takes.** Sending the Payments API key to a payout endpoint is rejected. Your **site code** identifies which of your sites a request belongs to and is in the Site section of the Dashboard. Every path needs one. It is not a secret. > ℹ️ **One API clients and payout API keys are scoped per site or per merchant.** A key issued for > one site does not work for another, so check which you have been given before you assume it covers > your whole account. > ⚠️ **Security note**: Keep your credentials secure at all times. Never expose them in client-side > code, public repositories, or logs. Ozow does not publish credentials publicly and will never ask > you to share them in an unsecured channel. ## 4. Understand your project setup When you log in to the Ozow Dashboard, you'll see your merchant account. Within your account, you can have one or more sites; each representing a separate website, merchant, or integration point. Each site has its own unique site code, and your site code and API credentials work together to identify which site a payment belongs to. Payment requests and transactions are always tied to a specific site, so it's important to use the correct site code for the integration you're building. ```mermaid graph TD A[Ozow Dashboard] --> B[Site 1\nsite code: ABC-001] A --> C[Site 2\nsite code: ABC-002] A --> D[Site 3\nsite code: ABC-003] B --> E[Payments & transactions\ntied to Site 1] C --> F[Payments & transactions\ntied to Site 2] D --> G[Payments & transactions\ntied to Site 3] ``` ## 5. Integrating payouts? Check your eligibility first If you intend to integrate payouts, you must be approved by Ozow's onboarding team before you can begin. Payout credentials are not issued until this approval is in place; you will not be able to start a payout integration without them. Contact your account manager or [support@ozow.com](mailto:support@ozow.com) to request payout eligibility. > ℹ️ **Note**: Payin credentials are issued automatically as part of standard merchant onboarding. > Payout credentials require a separate approval process before they are issued. ## 6. Choose your integration path Once your credentials are in place, you're ready to choose how you'll integrate. Head to [choose your integration](https://hub.ozow.com/integration-methods.md) to understand your options and choose the right path for your use case. If you're new to Ozow and want to get to your first payment as quickly as possible, go straight to the [quick start guide](https://hub.ozow.com/getting-started/quick-start.md). --- # Pay by Bank > The payer authorises the payment directly from their bank account. Source: https://hub.ozow.com/payment-products/payin/pay-by-bank/ Pay by Bank lets your customer pay you directly from their bank account. No card, no registration, no stored details; they authorise the payment with their bank and the money moves from their account to yours. It's Ozow's core payment method and the one enabled on your account by default. It reaches the roughly 47 million South Africans with a bank account, including the large share who have no credit card or prefer not to use one online. The other thing that sets it apart: once a Pay by Bank payment is confirmed, it's irrevocable. There's no chargeback mechanism the way there is with card. ## How your customer pays 1. Your customer chooses to pay by bank at checkout and selects their bank. 2. They authorise the payment, either by signing in through Ozow's secure payment page, or by approving it in their own banking app, depending on the bank. 3. Ozow confirms the payment. 4. Your customer returns to your site. Step 2 is where the experience differs, and that's what the bank API methods below are about. ### Bank API payments Ozow has direct API integrations with a number of South African banks. Where one exists, your customer authorises the payment inside their own bank's app or channel rather than entering internet banking details on the Ozow page. That's a better experience and a more reliable one. The customer authenticates with their bank the way they normally do, often biometrically, and the outcome comes back from the bank directly, so you get a definitive answer rather than an inferred one. | Bank APIs | Bank | |---|---| | Absa Pay | Absa | | Capitec Pay | Capitec | | FNB Payment Requests | FNB and RMB | | Nedbank Direct EFT | Nedbank | Customers whose bank doesn't have a direct integration still pay through Pay by Bank, they just sign in through the Ozow payment page instead. ## Enabling Pay by Bank Pay by Bank is enabled by default on your Ozow account. If you're integrated for payins, you already have it. The individual bank API methods are enabled separately. Speak to your account manager about which ones you want on your account. > ⚠️ If you operate in a high-risk industry, **Customer Identity Verification** is mandatory for Pay > by Bank and for several of the bank API methods. It changes what you build, so read [Customer > Identity Verification](https://hub.ozow.com/integration-methods/apis/payin/identity-verification.md) > before you start rather than after. ## Things to know **Pay by Bank payments are irrevocable.** Once confirmed, the funds are yours. There's no chargeback process, which is the biggest practical difference between Pay by Bank and card. You can still issue a [refund](https://hub.ozow.com/payment-products/refunds.md); that's your decision, not something a customer can force through their bank. **Your customer needs internet or app banking.** A bank account alone isn't enough; they need to be able to authorise a payment digitally. **The experience depends on their bank, not on you.** You enable the methods, but which flow a given customer sees is determined by who they bank with. Design your checkout so it reads sensibly either way. **Settlement.** For how and when Pay by Bank payments are settled to you, see [Settlements](https://hub.ozow.com/payment-products/settlements-and-float/settlements.md). ## Integrating Pay by Bank Pay by Bank works with every Ozow integration method, and nothing bank-specific is required; it's enabled by default and appears on the Ozow payment page. - [Redirect to Ozow](https://hub.ozow.com/integration-methods/apis/payin/redirect-to-ozow.md) - [Embedded iframe](https://hub.ozow.com/integration-methods/apis/payin/embedded-iframe.md) - [Embedded modal](https://hub.ozow.com/integration-methods/apis/payin/embedded-modal.md) - [No code payment requests](https://hub.ozow.com/integration-methods/no-code/payment-requests.md) - [Plugins and platforms](https://hub.ozow.com/integration-methods/plugins-and-platforms.md) **Standalone bank buttons.** To show your own "Pay with Capitec Pay" or "Pay with Absa Pay" buttons and send customers straight to that bank, pass the relevant `institutionId`. Each bank method has its own. See [Standalone payment buttons](https://hub.ozow.com/integration-methods/apis/payin.md#standalone-payment-buttons). **Bank icons** for those buttons are in [Brand assets](https://hub.ozow.com/payment-products/brand-assets.md). --- # Choosing a checkout experience > Where your customer pays decides how much you build and whether you take on PCI DSS scope. Compare redirect, embedded and server to server. Source: https://hub.ozow.com/integration-methods/apis/payin/ If you're building a payin integration with our APIs, your first decision is where the customer actually pays. That affects how much you build, whether the customer leaves your site, and whether you take on PCI DSS scope. > ℹ️ **If you're not sure, use [Redirect to Ozow](https://hub.ozow.com/integration-methods/apis/payin/redirect-to-ozow.md).** It's the fastest to build, > it supports every payment method we offer, and Ozow carries the PCI DSS scope. Moving to an > embedded experience later is a real piece of work rather than a switch: the embedded guides are > Payments API integrations, so the endpoint you post to, the credentials you send and the way you > verify the notification all change. ## The three approaches | | Redirect to Ozow | Embedded | Server-to-server | |---|---|---|---| | **Customer leaves your site** | Yes | No | No | | **Who renders the payment form** | Ozow | Ozow | You | | **Your PCI DSS scope** | None | None | Full | | **Payment methods** | Enabled by Ozow on your account | Enabled by Ozow on your account | Enabled by Ozow on your account | | **Available today** | Yes | Yes | No | | **Build effort** | Lowest | Moderate | Highest | All three use the same underlying model: you create a payment request from your server, the customer authorises it, and Ozow notifies your server of the outcome. What changes is where the authorisation happens, and, between redirect and embedded, which API you build it against. ## One integration, every payment method Payment methods are enabled on your Ozow account, not in your code. **Pay by Bank is enabled by default.** Any other methods you opt into, card, PayShap request, voucher, buy now pay later, crypto; are enabled by Ozow on your account. Once enabled, they appear on the Ozow payment page automatically. You don't build a new integration, call a different endpoint, or ship code for each one. This means you can start with Pay by Bank, go live, and add methods later as a commercial decision rather than a development project. Two things to know: - **[Standalone buttons](#standalone-payment-buttons) are optional extra work.** They're recommended for conversion, but each one is a per-method build rather than something enabled on your account. - **Apple Pay and Google Pay ride along with card**: they don't have their own `institutionId`. Once card and wallet payments are enabled on your account, they appear on the Ozow payment page automatically; on the default selection screen and on the card payment screen, for customers whose device and browser support them. To render them directly on your own checkout page instead, use the [embedded wallet](https://hub.ozow.com/integration-methods/apis/payin/embedded-wallet.md). To opt into a payment method, speak to your Ozow account manager. See [Prerequisites and onboarding](https://hub.ozow.com/getting-started/prerequisites-and-onboarding.md). ## Redirect to Ozow You create a payment request server-side and send the customer to the URL Ozow returns. They complete the payment on an Ozow-hosted page, then return to your site. **Choose redirect if:** - You want the shortest path to a working integration - You want every enabled payment method available without extra work - You don't want payment details touching your infrastructure - You're integrating a backend system, an invoicing flow, or anything without a browser checkout of its own **Look elsewhere if:** keeping the customer on your own domain throughout is a hard requirement. → [Redirect to Ozow](https://hub.ozow.com/integration-methods/apis/payin/redirect-to-ozow.md) ### Standalone payment buttons By default, the Ozow payment page asks the customer to choose how they want to pay. If you'd rather show your own buttons; "Pay with Capitec Pay", "Pay with card"; and send the customer straight to that method, pass the relevant `institutionId` when you create the payment request. The customer skips the selection screen. This works with both redirect and embedded checkouts. The identifier for each one is in [Payment method identifiers](https://hub.ozow.com/integration-methods/apis/payin/payment-method-ids.md), where the **Standalone button** column marks the methods you can put your own button behind. > ℹ️ There's no `institutionId` for Apple Pay or Google Pay, and you don't need one. Once card and > wallet payments are enabled on your account, the wallet buttons appear alongside card entry; both > on the default selection screen and on the card payment screen. If you want a standalone card > button, use the **Card** `institutionId` and the wallet buttons come with it. To render them on > your own checkout page instead, use the [embedded wallet](https://hub.ozow.com/integration-methods/apis/payin/embedded-wallet.md). > ⚠️ If you replace the Ozow selection screen entirely with your own buttons, newly enabled payment > methods won't appear until you add a button for them. Worth keeping in mind if you plan to add > methods over time. > ℹ️ Several bank methods require **Customer Identity Verification** if you operate in a high-risk > industry. Check [Customer Identity Verification](https://hub.ozow.com/integration-methods/apis/payin/identity-verification.md) before > building standalone buttons for them. ## Embedded The customer never leaves your page. Ozow still renders the payment form, so you take on no PCI DSS scope; you're hosting it inside your own layout. **All three are Payments API integrations**, unlike the redirect above, which is One API. The payment request, the credentials and the notification check are the Payments API's throughout. There are three variants. | | iframe | Modal | Embedded wallet | |---|---|---|---| | **What the customer sees** | Ozow checkout inside a container on your page | Ozow checkout in an overlay above your page | Apple Pay, Google Pay and card, in an iframe on your page | | **Container element needed** | Yes | No | No | | **Payment methods** | All enabled on your account | All enabled on your account | Apple Pay, Google Pay, card | | **Requires** | Ozow SDK and jQuery | Ozow SDK and jQuery | Ozow Wallet SDK | | **Additional setup** | None | None | Card and wallet payments enabled on your account, Apple Pay domain verification, CSP allowances | **Choose iframe** if you want the payment form to sit inline in your checkout page as part of the layout. → [Embedded iframe](https://hub.ozow.com/integration-methods/apis/payin/embedded-iframe.md) **Choose modal** if you'd rather trigger checkout from a button and have it appear over your page. Same SDK, no container markup to manage. → [Embedded Modal](https://hub.ozow.com/integration-methods/apis/payin/embedded-modal.md) **Choose the embedded wallet** if you want Apple Pay, Google Pay and card payments rendered directly on your own checkout page rather than on an Ozow screen. Card and wallet payments must be enabled on your account by Ozow first. It covers those three methods only; if you also need Pay by Bank or anything else, combine it with redirect or one of the other embedded options. → [Embedded Wallet](https://hub.ozow.com/integration-methods/apis/payin/embedded-wallet.md) > ⚠️ The iframe and modal checkouts require jQuery on the page and must be loaded through the Ozow > SDK. Don't build your own iframe around a payment URL, it won't behave correctly and it isn't > supported. ## Server-to-server You collect the customer's payment details on your own page and post them to Ozow from your server. Ozow renders nothing. > ⚠️ **Not available yet.** Because you'd be handling raw payment details, you'll need to be PCI DSS compliant to use this. If you're evaluating it, speak to your Ozow account manager early; compliance is usually the longest part of the project. ## Native mobile apps Ozow doesn't provide a native iOS or Android SDK. For payments inside a mobile app, use [Redirect to Ozow](https://hub.ozow.com/integration-methods/apis/payin/redirect-to-ozow.md) and open the payment URL in a system browser or web view. > ⚠️ The embedded wallet SDK is a web SDK. It is not supported inside native mobile applications. ## What every approach still needs Whichever you pick, these don't change: - **Create the payment request from your server**, never from the browser. Your API credentials must never reach client-side code. - **Treat the webhook as the source of truth**, not the customer's browser returning to your success page. See [Building a secure integration](https://hub.ozow.com/getting-started/building-a-secure-integration.md). - **Handle every status**, not just success and failure. See [Transaction and settlement statuses](https://hub.ozow.com/integration-methods/statuses.md). ## Still deciding? - Building a normal online checkout and want it working quickly → **Redirect** - Customers must not leave your domain → **Embedded iframe** or **Modal** - You want Apple Pay and Google Pay on your own page → **Embedded wallet** - You want your own branded button per bank or method → **Redirect or Embedded, with standalone buttons** - You're PCI DSS compliant and want full control of the form → **Server-to-server**, when it's released --- # Payment method identifiers > The UUID for each payment method Ozow supports, for the fields that take one. Source: https://hub.ozow.com/integration-methods/apis/payin/payment-method-ids/ Ozow identifies each payment method by a UUID. The same identifier works across the APIs, under different field names: `institutionId` on One API, `SelectedBankId` on the Payments API. Send one to take a customer straight to that method, skipping the screen where they choose. Leave the field out and the customer chooses on the Ozow payment page, which is what most integrations do. **Standalone button** marks the ones you can put your own button behind, as [Choose a checkout experience](https://hub.ozow.com/integration-methods/apis/payin.md) describes. The rest identify a bank within Pay by Bank rather than a method a customer would recognise as its own button. | Payment method | Identifier | Standalone button | |---|---|---| | Absa | `3284A0AD-BA78-4838-8C2B-102981286A2B` | Deprecated | | Absa Pay | `8F0B5AD2-2A44-4FF2-B052-D4E1E426587D` | Yes | | African Bank | `33A0840B-0CF4-4B8C-86E0-EC6C4BE8C60E` | Yes | | Bidvest Bank Grow | `E022DFC8-FF4A-4425-A074-C65D07E8F09C` | Yes | | Buy Now Pay Later | `643C3DCF-9FC3-47BB-A11A-A390B5680E2F` | Yes | | Capitec Pay | `913999FA-3A32-4E3D-82F0-A1DF7E9E4F7B` | Yes | | Card | `3B1ED354-46E8-465D-9213-8C7A8E5663CE` | Yes | | Crypto | `43FDB792-3B88-4D36-A13D-42B7661E9F76` | Yes | | FNB | `4816019C-3314-4C80-8B6B-B2CD16DCC4EC` | Yes | | FNB Pay | `23D34554-5727-4BE9-9276-9DDD20431E2B` | Yes | | GoTyme Bank | `28FCC8FA-985B-480B-82FD-7D09BC19C9D0` | Deprecated | | Investec | `4B45BE85-B616-4BD1-9027-F8FCF8F9AF7B` | Yes | | Nedbank | `D3889DF6-CDAC-4861-9D64-2B100FB7ED07` | Yes | | Nedbank Direct EFT | `8FD134F9-4D3F-4F54-9B1F-0AE2E356CF24` | Yes | | PayShap Request | `EEC08676-46EB-4F80-AF56-CAA5A6623880` | Yes | | Standard Bank | `AD7D8DA4-1723-4066-94BB-6662D845E483` | Yes | | Voucher | `42F71BF8-0E09-43D5-A6EB-4F7370CB5B20` | Yes | > ℹ️ **Note**: Not every identifier is enabled on every account. Pay by Bank is available by > default; Capitec Pay, Buy Now Pay Later, card, crypto and PayShap Request are enabled by > Ozow on request. Sending an identifier your account is not enabled for will result in an error. ## Where these are used | API | Field | Where | |---|---|---| | One API | `institutionId` | `POST /payments`, at the top level of the request | | One API | `details.institutionId` | `POST /payments/{id}/transactions`, when `paymentType` is `ozowredirect` | | One API | `institutionId` | Inside a bank account object: a refund's `paidTo`, a settlement's `bank`, and a redirect's `beneficiary` and `verifiedBankAccount` | | Payments API | `SelectedBankId` | [Redirect to Ozow](https://hub.ozow.com/integration-methods/apis/deprecated-integrations/redirect-to-ozow.md), on the payment request | > ⚠️ **Important**: Field names are case sensitive, and a name that differs by a character > is a name the API does not recognise. The rejection does not say which field was wrong, > so copy the names from the reference page for the operation you are calling rather than > retyping them. Bank availability changes. Banks go down for infrastructure work and updates, and Ozow notifies you where it can, so treat a bank being reachable as something to handle rather than assume. --- # Transaction and settlement statuses > Every payin, payout, refund and settlement status, which are final, and what to do about each. Source: https://hub.ozow.com/integration-methods/statuses/ Every payment through Ozow moves through a series of statuses. This page lists all of them, tells you which ones are final, and tells you what to do about each. > 🚨 **Read this first.** `Pending` and `Complete` appear on a payin, on a settlement and on a > refund. `Complete` on a payin is a customer's payment succeeding, on a settlement it is the > payment out to you confirmed by Ozow's bank, and on a refund it is your customer having their > money back. Refunds spell theirs as integers rather than strings. A status value on its own tells > you nothing. Always check which object it belongs to before you act on it. ## How the lifecycles relate A payment has more than one lifecycle. The transaction completing and the money reaching your bank account are two separate events with two separate status vocabularies. ```mermaid flowchart TB subgraph in["Money in"] direction LR A["Customer
pays"] --> B["Payin
Complete"] B --> C["Settlement
Complete"] C --> D["Your bank
account"] end subgraph out["Money out"] direction LR T["Your bank
account"] -. "top up" .-> E["Your
float"] E --> F["PayoutComplete"] E --> H["Refund"] F --> G["Recipient's
bank account"] H --> G end in ~~~ out ``` **A completed transaction is not settled money.** A payin status of `Complete` means the customer's payment succeeded and the funds *will* be settled to you. The settlement status tells you whether that has actually happened. Don't use payin status to reconcile your bank account. Every other final payin status settles nothing. **Refunds and payouts draw on your float, not on the original transaction.** A refund needs a funded float balance even though it's returning money the customer already paid, because that money has already been settled to you. See [Float top-up](https://hub.ozow.com/payment-products/settlements-and-float/float-top-up.md). ## Look up a status [Status decoder](https://hub.ozow.com/integration-methods/statuses/), a tool on this page. The tables below list every status in full. ## How to read a status ### Final vs non-final A **final** status will not change on its own. A **non-final** status will be followed by another update, and you must wait for it rather than acting. Getting this wrong is the most common integration bug in payments. Never release goods, mark an order paid, or notify a customer on a non-final status. > ⚠️ One exception: payin `PendingInvestigation` is final in the sense that no automatic update is > coming, but Ozow Support can change it to `Complete` or `Error` after a manual check. Treat it as > needing human action, not as a settled outcome. ### Status and sub-status Payouts return a status and, in most cases, a sub-status. **Branch on the sub-status whenever one is present.** **The API sends the code, not the name.** `subStatus` on a payout status response is a number, so `405` is what arrives where this page says `PayoutProcessingError_InvalidAccountNumber`. Both are listed. The name is for reading; the code is what your `switch` matches. This matters because a parent status can be non-final while the sub-status under it is final. `PayoutReceived` is non-final, but `Payout_ValidationFailed` beneath it is a final failure. If you only read the parent status, you will wait forever for a payout that has already failed. ### Never infer status from the browser redirect The customer's browser returning to your success page is not proof of payment. Statuses arrive on your notification or webhook URL, and you can query them with the status check API. See [Building a secure integration](https://hub.ozow.com/getting-started/building-a-secure-integration.md). --- ## Payin statuses ```mermaid stateDiagram-v2 direction LR state "Not paid" as NotPaid { Cancelled Abandoned Voided Error } [*] --> Created Created --> PendingInvestigation Created --> Pending Created --> Complete Created --> NotPaid PendingInvestigation --> Complete PendingInvestigation --> NotPaid Pending --> Complete Pending --> NotPaid ``` Which of the four unpaid outcomes you can get depends on where the payment was when it stopped. `Voided` follows only `Created`. From `Pending` the only unpaid outcome is `Error`, and from `PendingInvestigation` it is `Cancelled`, `Abandoned` or `Error`. **Non-final:** `Created`, `Pending` **Final:** `Complete`, `PendingInvestigation`, `Cancelled`, `Abandoned`, `Voided`, `Error` **The `One API` column is the value `GET /payments/{id}/transactions` returns for that status.** | Status | One API | Final? | Settles? | What it means | What to do | |---|---|---|---|---|---| | `Created` | `Incomplete` | No | No | The transaction has been created and the customer has opened the payment page, but hasn't completed it. | Wait for a final status. | | `Complete` | `Successful` | Yes | **Yes** | The payment succeeded and the funds will be settled to you. | Nothing. Fulfil the order. | | `Cancelled` | `Error` | Yes | No | The transaction was cancelled: either the customer pressed cancel, or the payment failed Ozow's verification with the bank. `StatusMessage` says which. | Nothing. If they still want to pay, ask them to start a new transaction. | | `Abandoned` | `Error` | Yes | No | The customer started the transaction but didn't finish it, typically they closed the Ozow payment page. | Nothing. If they still want to pay, ask them to start a new transaction. | | `Voided` | `Error` | Yes | No | The transaction was invalidated and won't be processed. Happens when the customer changes bank partway through the Ozow flow, or when the saved profile they chose is deleted, deactivated or fails to load. | Nothing. A new transaction will have been created for the method they switched to. **No notification is sent for a voided transaction**, so find these by polling rather than by waiting. | | `Error` | `Error` | Yes | No | An error occurred while the transaction was being processed. Not caused by anything the customer did. | Ask the customer to retry the transaction. | | `Pending` | `Pending` | No | No | The payment still has to be verified. The outcome follows once it has been. | Wait for the update on your notification URL. Do not release anything on it. | | `PendingInvestigation` | `Pending` | Yes | No | Ozow could not complete its verification with the bank, so the payment has to be checked manually against your bank statement. | Check your bank statement. If the funds arrived, contact Ozow Support with proof of payment to have the status updated to `Complete`. If they didn't, contact Support to have it set to `Error`. | > ℹ️ `Pending` is non-final: an update follows. Handle it as "wait", never as an outcome. It means > neither that the payment failed nor that it succeeded. > ⚠️ Refunding a transaction does not change its status. If you need to know whether a transaction > has been refunded, check the refund records rather than relying on the transaction status. > ℹ️ Settlement timing depends on the payment method. --- ## Payout statuses ```mermaid stateDiagram-v2 direction LR state "Ended without paying" as Ended { PayoutProcessingError PayoutReturned } [*] --> PayoutReceived PayoutReceived --> Verification Verification --> SubmittedForProcessing SubmittedForProcessing --> PayoutComplete PayoutComplete --> PayoutReturned Verification --> Ended SubmittedForProcessing --> Ended Verification --> PayoutPendingInvestigation SubmittedForProcessing --> PayoutPendingInvestigation PayoutPendingInvestigation --> PayoutComplete PayoutPendingInvestigation --> Ended ``` The happy path is `PayoutReceived` → `Verification` → `SubmittedForProcessing` → `PayoutComplete`. `Verification` can also reach `PayoutComplete` directly, so a payout that never appears in `SubmittedForProcessing` has not skipped a step. `PayoutProcessingError` and `PayoutReturned` are grouped because nothing follows either of them. > ⚠️ **`PayoutComplete` is not final, though it almost never changes.** A completed payout moves > to `PayoutReturned` if the destination bank sends the money back, which is a rare event rather > than one to plan a flow around. Keep handling status updates for a payout you have already marked > paid, and you will hear about it on the day it happens. The only two statuses nothing follows are > `PayoutProcessingError` and `PayoutReturned`. **Payout timing:** with `isRtc` set to `true` the payout is instant. With `isRtc` set to `false` it takes 1-2 business days. > ⚠️ Branch on the **sub-status**, not the parent status. `PayoutReceived`, `Verification` and > `PayoutPendingInvestigation` are all non-final while carrying sub-statuses that are final > failures. ### PayoutReceived | Sub-status | Code | Final? | What it means | What to do | |---|---|---|---|---| | None | None | No | The payout request has been received. | Wait for a final status. | | `Payout_Unclassified` | 100 | Yes | No sub-status could be determined. The payout has failed. | Rare edge case. Treat as a failure and investigate. | | `Payout_ValidationFailed` | 101 | Yes | Request validation failed. | Check the `ErrorMessage` field for the reason, correct the request, then resubmit. | ### Verification | Sub-status | Code | Final? | What it means | What to do | |---|---|---|---|---| | None | None | No | The payout is being verified. | Wait for a final status. | | `Verification_Pending` | 201 | No | Ozow is waiting for a response from your verification webhook. | Wait for a final status. | | `Verification_Success` | 203 | No | Your webhook verified the payout successfully. Processing continues. | Wait for a final status. | | `Verification_Failed` | 202 | Yes | Your verification webhook returned a response that failed verification. | Check why your webhook rejected it, then resubmit the payout. | | `Verification_Error` | 204 | Yes | Ozow couldn't reach your verification webhook. | Check that your webhook is reachable. If you've changed its URL, confirm Ozow has the new one. Then resubmit. | | `Verification_AccountNumberDecryptionFailed` | 205 | Yes | The key returned by your webhook failed to decrypt the account number. | Check your webhook's key handling, then resubmit the payout. | | `Verification_Success_Awaiting_Funds` | 206 | No | The payout verified, but your float balance is too low to cover it. | Top up your float. The payout continues on its own once the funds are there. Do not resubmit. | | `Verification_Success_Awaiting_Submission` | 207 | No | The payout verified and is queued for submission. | Wait for a final status. | ### SubmittedForProcessing | Sub-status | Code | Final? | What it means | What to do | |---|---|---|---|---| | None | None | No | The payout is being processed. | Wait for a final status. | | `SubmittedForProcessing_PayoutAddedToBatch` | 301 | No | The payout has been added to a batch. | Wait for a final status. | | `SubmittedForProcessing_PayoutSubmittedToBank` | 302 | No | The batch has been processed and submitted to the bank. | Wait for a final status. | | `SubmittedForProcessing_PayoutSubmittedToPpi` | 303 | No | The payout has been submitted for processing. | Wait for a final status. | ### PayoutComplete | Sub-status | Code | Final? | What it means | What to do | |---|---|---|---|---| | None | None | No | The payout completed successfully. | Release whatever the payout was for, and keep handling updates: this can still become `PayoutReturned`. | ### PayoutProcessingError | Sub-status | Code | Final? | What it means | What to do | |---|---|---|---|---| | None | None | Yes | An error occurred while processing the payout. | Resubmit the payout. | | `PayoutProcessingError_PayoutRejected` | 401 | Yes | The bank rejected the payout. | Resubmit the payout. | | `PayoutProcessingError_PayoutCancelled` | 402 | Yes | Ozow stopped the payout before it was paid. | Check the `ErrorMessage` field, then resubmit. | | `PayoutProcessingError_Insufficient_Balance` | 403 | Yes | Your float balance was too low to cover the payout. | **Top up your float. Do not resubmit**: see the warning below. | | `PayoutProcessingError_PayoutInternalError` | 404 | Yes | An internal error occurred during processing. | Resubmit the payout. | | `PayoutProcessingError_InvalidAccountNumber` | 405 | Yes | The account number is invalid. | Correct the account number, then resubmit. | > 🚨 **On `PayoutProcessingError_Insufficient_Balance` you must not resubmit.** Top up your float > instead. Once the float is allocated, the payout processes automatically. Resubmitting risks > paying the recipient twice. ### PayoutReturned | Sub-status | Code | Final? | What it means | What to do | |---|---|---|---|---| | None | None | Yes | The payout couldn't be paid into the recipient's account. | Resubmit the payout. | | `PayoutReturned_Unpaid` | 9001 | Yes | The destination bank rejected the payment. | Check that the destination account is still active, then resubmit. | ### PayoutPendingInvestigation | Sub-status | Code | Final? | What it means | What to do | |---|---|---|---|---| | None | None | No | The payout is under investigation. | Wait for a final status. | | `PayoutPendingInvestigation_AmountMismatch` | 601 | Yes | The payout failed because the amounts didn't match. | Check the payout details, then resubmit. | > ⚠️ **A payout cannot be cancelled once it is submitted.** Check the request before you send it: > the account number, the amount and the reference are all final from that point. --- ## Refund statuses A refund returns money to a customer for a payin you've already received. Refunds draw on your float balance, not on the original transaction; the funds from that transaction have already been settled to you. > ⚠️ Refund statuses are returned as **integers**, not strings. This is different from payin, payout > and settlement statuses, which are returned as text. > ⚠️ **The numeric values are not in lifecycle order.** A refund progresses `0` → `2` → `1`. Don't > treat a higher value as further along, and don't use greater-than comparisons to test progress. ```mermaid stateDiagram-v2 [*] --> Pending: 0 Pending --> Submitted: 2 Pending --> Cancelled: 4 Submitted --> Complete: 1 Submitted --> Failed: 3 Submitted --> Returned: 5 ``` This is the path a refund takes. Three further statuses sit outside it, `Invalid` (-1), `PendingInvestigation` (-2) and `Error` (-3). Each one has a row below. Handle them wherever they turn up rather than by position. **Non-final:** `Pending` (0), `Submitted` (2), `PendingInvestigation` (-2) **Final:** `Complete` (1), `Failed` (3), `Cancelled` (4), `Returned` (5), `Invalid` (-1), `Error` (-3) **The negative values are real.** `Invalid`, `PendingInvestigation` and `Error` are returned by the API alongside the six above. Switch on all nine, or give your default branch something safe to do. | Value | Status | Final? | What it means | What to do | |---|---|---|---|---| | `0` | `Pending` | No | The refund request has been submitted and accepted, but not yet processed. | Wait for a final status. | | `2` | `Submitted` | No | The refund has been assigned to a batch and is being processed. | Wait for a final status. | | `1` | `Complete` | Yes | The refund was paid successfully. The customer has their money. | Nothing. | | `3` | `Failed` | Yes | The refund payment failed. | Check that your float is funded, then submit a new refund. | | `4` | `Cancelled` | Yes | The refund was cancelled before it was submitted for processing. | Nothing. If the customer is still owed a refund, submit a new one. | | `5` | `Returned` | Yes | The refund was paid and came back. The destination account did not accept the credit, or the destination bank could not apply it. | Confirm the account details with the customer before you try again. Resubmitting the same details without checking returns the money a second time. | | `-1` | `Invalid` | Yes | The refund could not be accepted as submitted. | Check the refund details against the original transaction, then submit a corrected refund. | | `-2` | `PendingInvestigation` | No | The refund is being checked manually. | Wait. Ozow reports this as `Pending` on a `thin` webhook, so a handler reading the webhook rather than the API will not see this value. | | `-3` | `Error` | Yes | The refund failed because of an error rather than a rejection. | Ozow reports this as `Failed` on a `thin` webhook. Treat it as a failure and submit a new refund. | > ⚠️ **On `Returned`, do not resubmit the same details without checking them.** The money came back > from the destination, so sending it again the same way returns it again. Confirm the account with > the customer first. > ℹ️ Refunds require a funded float. If your float is empty, refunds will not process. See [Float top-up](https://hub.ozow.com/payment-products/settlements-and-float/float-top-up.md). > ℹ️ **Refund status is the source of truth for whether a customer has been refunded.** The original > payin transaction keeps the status it had, so don't use transaction status to check refund state. --- ## Settlement statuses A settlement is the transfer of your collected funds into your bank account. Settlement statuses tell you where that transfer is, and they are **not** the same thing as the status of the transactions inside it. ```mermaid stateDiagram-v2 direction LR [*] --> Pending Pending --> Submitted Submitted --> Complete Submitted --> PendingInvestigation PendingInvestigation --> Complete ``` **Non-final:** `Pending`, `Submitted`, `PendingInvestigation` **Final:** `Complete` **A settlement has four statuses, and none of them is a payin status.** | Status | Final? | What it means | What to do | |---|---|---|---| | `Pending` | No | The settlement has been created. The payment out to you has not started. | Wait. If it stays here for an extended period, email [support@ozow.com](mailto:support@ozow.com). | | `Submitted` | No | The settlement has been submitted to Ozow's bank. It might not have reached yours yet. | Wait. If it stays here for an extended period, email [support@ozow.com](mailto:support@ozow.com). | | `Complete` | Yes | Ozow has submitted the payment and confirmed with Ozow's bank that it went out. Your own bank still has to clear it. | Reconcile against your bank statement rather than against this status. `Complete` is Ozow's leg finished; the clearing leg is your bank's and can lag it. | | `PendingInvestigation` | No | The settlement is being checked manually. | Wait. If it stays here for an extended period, email [support@ozow.com](mailto:support@ozow.com) with your settlement reference. | Settlement timing depends on the payment method the funds came in through. --- ## Which statuses mean money moved Only these mean money moved: - **Payin:** `Complete`, and only `Complete` settles - **Payout:** `PayoutComplete`, which can still become `PayoutReturned` if the bank sends it back - **Refund:** `Complete` (`1`), the integer and not the string - **Settlement:** `Complete`, which is the payment out confirmed by Ozow's bank, with your own bank still to clear it Everything else is either in progress or a failure. In particular: - `Pending`, `Created`, `Verification`, `SubmittedForProcessing` and `PayoutReceived` are **in progress**. Wait. - A payin `PendingInvestigation` needs a human. It is not a success. - A payin `Complete` is not settled money. Check the settlement status for that. --- # Building a secure integration > Where Ozow's security responsibility ends and yours begins: credentials, webhook endpoints, verifying notifications, and validating amounts. Source: https://hub.ozow.com/getting-started/building-a-secure-integration/ 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 webhook 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 payouts 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 TLS 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 redirect 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 idempotently, 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 payin 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 - [ ] API credentials are stored securely and never hardcoded or committed to source control - [ ] Test and production credentials are in strictly separate environments - [ ] Production credentials are restricted to a named list of people and services - [ ] Credential rotation process is documented with a named owner - [ ] Callback URL is HTTPS only with TLS 1.2 or later - [ ] Callback endpoint does not expose internal errors or stack traces - [ ] Every notification is verified using hash check (Payments API) or message signature (One API) before being trusted - [ ] Verification failures are logged and alerted on - [ ] Payment status is confirmed via API, not the browser redirect alone - [ ] Replay protection is in place for transaction references - [ ] Amount, currency, and merchant reference are validated against the original request before crediting - [ ] Duplicate notifications are handled idempotently - [ ] Order records are periodically reconciled against Ozow transaction records - [ ] Dashboard access follows least-privilege - [ ] Monitoring is in place for anomalous payin traffic ### Payout integrations - [ ] Payout API key is stored securely and never hardcoded or committed to source control - [ ] Test and production payout credentials are in strictly separate environments - [ ] Access to payout-triggering systems and code is restricted to a named list - [ ] Bulk payout requestor and approver are different people (recommended, not enforced by Ozow) - [ ] Business-level authorisation step is enforced before calling the payout API - [ ] Beneficiary bank details are verified before the first payout to any new beneficiary - [ ] A unique encryption key is generated and persisted per payout request - [ ] Velocity and amount limits are enforced on payouts - [ ] Real-time alerting is in place for anomalous payout activity - [ ] Incoming verification requests are validated on token, hash, and expected payout details - [ ] Payout completion is confirmed via API, not assumed from the initial response - [ ] Payout status notifications are verified by hash before being trusted - [ ] An immutable audit trail exists for every payout - [ ] Internal ledger is reconciled against Ozow payout records regularly --- # The contract The operations those pages declare, as the specification defines them. --- # List Transactions for Payment > GET `/payments/{id}/transactions` > Part of the One API reference. Source: https://hub.ozow.com/api-reference/one-api/get-payments-id-transactions/ Server: `https://one.ozow.com/v1` (Production) Other environments: `https://stagingone.ozow.com/v1` (Staging) List the transactions associated with the payment request with the specified `id`. An `id` matching no payment answers 200 with an empty result list rather than 404, so check whether a transaction came back rather than reading the status code. ## Authentication - `Authentication` (oauth2) - Scopes: `payments` ## Path parameters - `id` (string, required) - The unique identifier of the payment. ## Query parameters - `limit` (integer) - The maximum number of items to return. - `offset` (integer) - The number of items to discard in this paging operation. - `fromDate` (string, required) - The date from which to filter, inclusive. Whole days only, so any time sent with it is discarded. - `toDate` (string, required) - The date to filter up to, inclusive. Whole days only, so any time sent with it is discarded. ## Header parameters - `Idempotency-Key` (string) - The unique key idempotency key as per the following [IETF Draft](https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/) - `X-Correlation-ID` (string) - Optional correlation id for the request, if not supplied a new one will be generated and passed onto all underlying requests and returned as a header. ## Responses ### 200 OK. - Header `X-Correlation-ID`: The correlation id for the request that was processed. - `links` (object) - Standard [JSON API pagination links](https://jsonapi.org/format/#fetching-pagination). Each link repeats the query that produced the collection and carries its own `limit` and `offset`. Follow the link rather than building the next URI. The example below is the second of three pages. - `results` (array of Transaction) - `meta` (object) ### 400 Bad Request - Header `X-Correlation-ID`: The correlation id for the request that was processed. - `id` (string, uuid, required) - a unique identifier for this particular occurrence of the problem. - `links` (object, nullable) - Present on an authentication or authorisation failure, and null otherwise. - `about` (string, uri) - A link that leads to further details about this particular occurrence of the problem. When derefenced, this URI SHOULD return a human-readable description of the error. - `type` (string, uri) - A link that identifies the type of error that this particular error is an instance of. This URI SHOULD be dereferencable to a human-readable explanation of the general error. - `code` (string, required) - An application-specific error code, expressed as a string value. Key on this rather than on `title` or `detail`, which are written for a person. A rejection at the transport level uses the status name, one of `BadRequest`, `Unauthorized`, `Forbidden`, `NotFound`, `NotAllowed`, `Conflict`, `UnsupportedMediaType`, `BadGateway` or `InternalServerError`. An operation refusing a request on its own rules returns a code of its own. - `title` (string, required) - A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization. - `detail` (string, required) - A human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized. - `source` (object, nullable) - Where in the request the problem was found. All three keys are present whenever `source` is, with the ones that do not apply set to null. `source` itself is null where the failure is not about a part of the request. - `pointer` (string, json-pointer, nullable) - a JSON Pointer [RFC6901](https://tools.ietf.org/html/rfc6901) to the value in the request document that caused the error [e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute]. This MUST point to a value in the request document that exists; if it doesn’t, the client SHOULD simply ignore the pointer. - `parameter` (string, nullable) - A string indicating which URI query parameter caused the error. - `header` (string, nullable) - A string indicating the name of a single request header which caused the error. - `meta` (object, nullable) - A [meta object](https://jsonapi.org/format/#document-meta) containing non-standard meta-information about the error. Null where the request carried no `X-Correlation-ID`, and on an authentication failure, which does not echo it. - `correlationId` (string) - The `X-Correlation-ID` sent with the request, echoed back so it can be quoted to support. Absent when the request carried no correlation header. ### 401 Unauthorized - Header `X-Correlation-ID`: The correlation id for the request that was processed. `Error`, the same schema listed in full earlier in this document. Its own page: https://hub.ozow.com/api-reference/one-api/schemas/error.md ### 500 Internal Server Error. - Header `X-Correlation-ID`: The correlation id for the request that was processed. `Error`, the same schema listed in full earlier in this document. Its own page: https://hub.ozow.com/api-reference/one-api/schemas/error.md Example (The request failed on the Ozow side): ```json { "id": "9e0d5a83-6b24-4c19-8f7a-2d1b3e6c0a97", "links": null, "code": "InternalServerError", "title": "Internal Server Error", "detail": "Error occurred while processing request.", "source": { "pointer": "/data", "parameter": null, "header": null }, "meta": { "correlationId": "497f6eca-6276-4993-bfeb-53cbbbba6f08" } } ``` --- # List Webhook Subscriptions > GET `/webhooks` > Part of the One API reference. Source: https://hub.ozow.com/api-reference/one-api/get-webhooks/ Server: `https://one.ozow.com/v1` (Production) Other environments: `https://stagingone.ozow.com/v1` (Staging) Retrieve a list of active webhook subscriptions. ## Authentication - `Authentication` (oauth2) - Scopes: `webhooks` ## Query parameters - `limit` (integer) - The maximum number of items to return. - `offset` (integer) - The number of items to discard in this paging operation. ## Header parameters - `X-Forwarded-For` (string) - The IP address of the end-consumer. - `X-Correlation-ID` (string) - Optional correlation id for the request, if not supplied a new one will be generated and passed onto all underlying requests and returned as a header. ## Responses ### 200 OK - Header `X-Correlation-ID`: The correlation id for the request that was processed. - `links` (object) - Standard [JSON API pagination links](https://jsonapi.org/format/#fetching-pagination). Each link repeats the query that produced the collection and carries its own `limit` and `offset`. Follow the link rather than building the next URI. The example below is the second of three pages. - `results` (array of WebhookResponse) - `meta` (object) ### 400 Bad Request. - Header `X-Correlation-ID`: The correlation id for the request that was processed. - `id` (string, uuid, required) - a unique identifier for this particular occurrence of the problem. - `links` (object, nullable) - Present on an authentication or authorisation failure, and null otherwise. - `about` (string, uri) - A link that leads to further details about this particular occurrence of the problem. When derefenced, this URI SHOULD return a human-readable description of the error. - `type` (string, uri) - A link that identifies the type of error that this particular error is an instance of. This URI SHOULD be dereferencable to a human-readable explanation of the general error. - `code` (string, required) - An application-specific error code, expressed as a string value. Key on this rather than on `title` or `detail`, which are written for a person. A rejection at the transport level uses the status name, one of `BadRequest`, `Unauthorized`, `Forbidden`, `NotFound`, `NotAllowed`, `Conflict`, `UnsupportedMediaType`, `BadGateway` or `InternalServerError`. An operation refusing a request on its own rules returns a code of its own. - `title` (string, required) - A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization. - `detail` (string, required) - A human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized. - `source` (object, nullable) - Where in the request the problem was found. All three keys are present whenever `source` is, with the ones that do not apply set to null. `source` itself is null where the failure is not about a part of the request. - `pointer` (string, json-pointer, nullable) - a JSON Pointer [RFC6901](https://tools.ietf.org/html/rfc6901) to the value in the request document that caused the error [e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute]. This MUST point to a value in the request document that exists; if it doesn’t, the client SHOULD simply ignore the pointer. - `parameter` (string, nullable) - A string indicating which URI query parameter caused the error. - `header` (string, nullable) - A string indicating the name of a single request header which caused the error. - `meta` (object, nullable) - A [meta object](https://jsonapi.org/format/#document-meta) containing non-standard meta-information about the error. Null where the request carried no `X-Correlation-ID`, and on an authentication failure, which does not echo it. - `correlationId` (string) - The `X-Correlation-ID` sent with the request, echoed back so it can be quoted to support. Absent when the request carried no correlation header. Example (A field in the request body did not validate): ```json { "id": "3a6c9e01-5f2b-4d8a-9c47-1e0b7d5a2f83", "links": null, "code": "BadRequest", "title": "Bad Request", "detail": "amount: Amount must be greater than 0", "source": { "pointer": "/amount", "parameter": null, "header": null }, "meta": { "correlationId": "497f6eca-6276-4993-bfeb-53cbbbba6f08" } } ``` ### 401 Unauthorised. - Header `X-Correlation-ID`: The correlation id for the request that was processed. `Error`, the same schema listed in full earlier in this document. Its own page: https://hub.ozow.com/api-reference/one-api/schemas/error.md Example (No usable access token on the request): ```json { "id": "1cecc2b7-1c29-418a-b26a-bf7546926083", "links": { "about": "https://ozow.stoplight.io/docs/one-api/zi18vomr0jm8c-generate-authentication-token", "type": "https://tools.ietf.org/html/rfc7235#section-3.1" }, "code": "Unauthorized", "title": "Unauthorized Request", "detail": "Authorization header is missing or invalid.", "source": { "pointer": null, "parameter": null, "header": "Authorization" }, "meta": null } ``` ### 403 Forbidden. - Header `X-Correlation-ID`: The correlation id for the request that was processed. `Error`, the same schema listed in full earlier in this document. Its own page: https://hub.ozow.com/api-reference/one-api/schemas/error.md Example (The token is valid but lacks the scope the operation needs): ```json { "id": "c47a2e08-9b31-4f6d-85a0-7e2c1d9f3b56", "links": { "about": "https://ozow.stoplight.io/docs/one-api/zi18vomr0jm8c-generate-authentication-token", "type": "https://tools.ietf.org/html/rfc7235#section-3.1" }, "code": "Forbidden", "title": "Forbidden Request", "detail": "Request is forbidden, most likely scope does not match required scope to perform requested action.", "source": { "pointer": null, "parameter": null, "header": "Authorization" }, "meta": { "correlationId": "497f6eca-6276-4993-bfeb-53cbbbba6f08" } } ``` ### 500 Internal Server Error. - Header `X-Correlation-ID`: The correlation id for the request that was processed. `Error`, the same schema listed in full earlier in this document. Its own page: https://hub.ozow.com/api-reference/one-api/schemas/error.md Example (The request failed on the Ozow side): ```json { "id": "9e0d5a83-6b24-4c19-8f7a-2d1b3e6c0a97", "links": null, "code": "InternalServerError", "title": "Internal Server Error", "detail": "Error occurred while processing request.", "source": { "pointer": "/data", "parameter": null, "header": null }, "meta": { "correlationId": "497f6eca-6276-4993-bfeb-53cbbbba6f08" } } ``` --- # Get Webhook Secret > GET `/webhooks/{id}/secret` > Part of the One API reference. Source: https://hub.ozow.com/api-reference/one-api/get-webhooks-id-secret/ Server: `https://one.ozow.com/v1` (Production) Other environments: `https://stagingone.ozow.com/v1` (Staging) Retrieves the secret for the webhook. ## Authentication - `Authentication` (oauth2) - Scopes: `webhooks` ## Path parameters - `id` (string, required) - The unique identifier of the webhook subscription. ## Header parameters - `X-Correlation-ID` (string) - Optional correlation id for the request, if not supplied a new one will be generated and passed onto all underlying requests and returned as a header. ## Responses ### 200 OK - Header `X-Correlation-ID`: The correlation id for the request that was processed. - `secret` (string, required) - The secret key of the webhook to be used when validating the webhook signature. ### 400 Bad Request. - Header `X-Correlation-ID`: The correlation id for the request that was processed. - `id` (string, uuid, required) - a unique identifier for this particular occurrence of the problem. - `links` (object, nullable) - Present on an authentication or authorisation failure, and null otherwise. - `about` (string, uri) - A link that leads to further details about this particular occurrence of the problem. When derefenced, this URI SHOULD return a human-readable description of the error. - `type` (string, uri) - A link that identifies the type of error that this particular error is an instance of. This URI SHOULD be dereferencable to a human-readable explanation of the general error. - `code` (string, required) - An application-specific error code, expressed as a string value. Key on this rather than on `title` or `detail`, which are written for a person. A rejection at the transport level uses the status name, one of `BadRequest`, `Unauthorized`, `Forbidden`, `NotFound`, `NotAllowed`, `Conflict`, `UnsupportedMediaType`, `BadGateway` or `InternalServerError`. An operation refusing a request on its own rules returns a code of its own. - `title` (string, required) - A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization. - `detail` (string, required) - A human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized. - `source` (object, nullable) - Where in the request the problem was found. All three keys are present whenever `source` is, with the ones that do not apply set to null. `source` itself is null where the failure is not about a part of the request. - `pointer` (string, json-pointer, nullable) - a JSON Pointer [RFC6901](https://tools.ietf.org/html/rfc6901) to the value in the request document that caused the error [e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute]. This MUST point to a value in the request document that exists; if it doesn’t, the client SHOULD simply ignore the pointer. - `parameter` (string, nullable) - A string indicating which URI query parameter caused the error. - `header` (string, nullable) - A string indicating the name of a single request header which caused the error. - `meta` (object, nullable) - A [meta object](https://jsonapi.org/format/#document-meta) containing non-standard meta-information about the error. Null where the request carried no `X-Correlation-ID`, and on an authentication failure, which does not echo it. - `correlationId` (string) - The `X-Correlation-ID` sent with the request, echoed back so it can be quoted to support. Absent when the request carried no correlation header. Example (A field in the request body did not validate): ```json { "id": "3a6c9e01-5f2b-4d8a-9c47-1e0b7d5a2f83", "links": null, "code": "BadRequest", "title": "Bad Request", "detail": "amount: Amount must be greater than 0", "source": { "pointer": "/amount", "parameter": null, "header": null }, "meta": { "correlationId": "497f6eca-6276-4993-bfeb-53cbbbba6f08" } } ``` ### 401 Unauthorised. - Header `X-Correlation-ID`: The correlation id for the request that was processed. `Error`, the same schema listed in full earlier in this document. Its own page: https://hub.ozow.com/api-reference/one-api/schemas/error.md Example (No usable access token on the request): ```json { "id": "1cecc2b7-1c29-418a-b26a-bf7546926083", "links": { "about": "https://ozow.stoplight.io/docs/one-api/zi18vomr0jm8c-generate-authentication-token", "type": "https://tools.ietf.org/html/rfc7235#section-3.1" }, "code": "Unauthorized", "title": "Unauthorized Request", "detail": "Authorization header is missing or invalid.", "source": { "pointer": null, "parameter": null, "header": "Authorization" }, "meta": null } ``` ### 403 Forbidden. - Header `X-Correlation-ID`: The correlation id for the request that was processed. `Error`, the same schema listed in full earlier in this document. Its own page: https://hub.ozow.com/api-reference/one-api/schemas/error.md Example (The token is valid but lacks the scope the operation needs): ```json { "id": "c47a2e08-9b31-4f6d-85a0-7e2c1d9f3b56", "links": { "about": "https://ozow.stoplight.io/docs/one-api/zi18vomr0jm8c-generate-authentication-token", "type": "https://tools.ietf.org/html/rfc7235#section-3.1" }, "code": "Forbidden", "title": "Forbidden Request", "detail": "Request is forbidden, most likely scope does not match required scope to perform requested action.", "source": { "pointer": null, "parameter": null, "header": "Authorization" }, "meta": { "correlationId": "497f6eca-6276-4993-bfeb-53cbbbba6f08" } } ``` ### 500 Internal Server Error. - Header `X-Correlation-ID`: The correlation id for the request that was processed. `Error`, the same schema listed in full earlier in this document. Its own page: https://hub.ozow.com/api-reference/one-api/schemas/error.md Example (The request failed on the Ozow side): ```json { "id": "9e0d5a83-6b24-4c19-8f7a-2d1b3e6c0a97", "links": null, "code": "InternalServerError", "title": "Internal Server Error", "detail": "Error occurred while processing request.", "source": { "pointer": "/data", "parameter": null, "header": null }, "meta": { "correlationId": "497f6eca-6276-4993-bfeb-53cbbbba6f08" } } ``` --- # Request Payment > POST `/payments` > Part of the One API reference. Source: https://hub.ozow.com/api-reference/one-api/post-payments/ Server: `https://one.ozow.com/v1` (Production) Other environments: `https://stagingone.ozow.com/v1` (Staging) Create a payment request with the specified channel and transaction details. ## Authentication - `Authentication` (oauth2) - Scopes: `payments` ## Header parameters - `Idempotency-Key` (string) - The unique key idempotency key as per the following [IETF Draft](https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/) - `X-Correlation-ID` (string) - Optional correlation id for the request, if not supplied a new one will be generated and passed onto all underlying requests and returned as a header. ## Request body - `siteCode` (string, required, max length 50) - The merchant site code in use for this payment. Site codes are available on the Ozow dashboard. - `region` (string, min length 2, max length 2) - ISO 3166-Alpha-2 code for the originating country of the payment. Must be "ZA" for South Africa. If region is not specified IP geolocation will be used to determine the applicable region. - `amount` (object, required) - The currency and amount of the payment request. - `variableAmount` (object) - If the payment amount can be changed by the payer, the variable amounts need to be passed in. - `merchantReference` (string, required, max length 50) - The merchant's reference for the transaction. It is pre-populated in the payer's own reference field at their bank, shortened by banks that limit it, so it is not an internal-only value. - `beneficiaryReference` (string, max length 20, pattern ^[A-Za-z0-9]*$) - The reference that appears on the merchant's bank statement for the payment. Letters and numbers only. Rejected as missing unless the site is configured to let the payer supply the reference. A site prefix, where one is configured, counts towards the 20 characters. - `payerReference` (string, max length 20) - `payer` (object) - Information on the payer used for identification and fraud purposes. - `returnUrl` (string, uri) - The URI that Ozow needs to redirect back to once the payment has reached a conclusion. Must be reachable from the internet. `localhost` is rejected with a 403, so a local integration needs a tunnel rather than the address the browser uses. - `notifyUrl` (string, uri) - Optional notify URL to send notifications of the status of the payment. The recommendation is to use webhooks instead of this method which are configurable via the webhooks endpoints of the API or via the Ozow Dashboard. Must be reachable from the internet. `localhost` is rejected with a 403, so a local integration needs a tunnel rather than the address the browser uses. - `expireAt` (string, date-time, required) - The date and time the payment request should expire at and make the payment link unusable - `institutionId` (string, uuid) - The institution to send the payer straight to, skipping the payment method selection screen. The identifier for each payment method is on that method's page under Payment products. ## Responses ### 200 OK - Header `X-Correlation-ID`: The correlation id for the request that was processed. - `links` (object, required) - The relevant links to the this payment. - `id` (string, uuid, required) - The identifier for the payment request. - `status` (PaymentStatus, required, one of "Created", "Expired") - The status of the payment. - `reason` (string) - The payment status reason. - `redirectUrl` (string, uri) - The url to redirect a consumer to. A redirect url will be provided should a payment require further client interaction. ### 201 Created - Header `X-Correlation-ID`: The correlation id for the request that was processed. - Header `Location`: The unique URI for this resource. `PaymentResponse`, the same schema listed in full earlier in this document. Its own page: https://hub.ozow.com/api-reference/one-api/schemas/payment-response.md ### 400 Bad Request. - Header `X-Correlation-ID`: The correlation id for the request that was processed. - `id` (string, uuid, required) - a unique identifier for this particular occurrence of the problem. - `links` (object, nullable) - Present on an authentication or authorisation failure, and null otherwise. - `about` (string, uri) - A link that leads to further details about this particular occurrence of the problem. When derefenced, this URI SHOULD return a human-readable description of the error. - `type` (string, uri) - A link that identifies the type of error that this particular error is an instance of. This URI SHOULD be dereferencable to a human-readable explanation of the general error. - `code` (string, required) - An application-specific error code, expressed as a string value. Key on this rather than on `title` or `detail`, which are written for a person. A rejection at the transport level uses the status name, one of `BadRequest`, `Unauthorized`, `Forbidden`, `NotFound`, `NotAllowed`, `Conflict`, `UnsupportedMediaType`, `BadGateway` or `InternalServerError`. An operation refusing a request on its own rules returns a code of its own. - `title` (string, required) - A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization. - `detail` (string, required) - A human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized. - `source` (object, nullable) - Where in the request the problem was found. All three keys are present whenever `source` is, with the ones that do not apply set to null. `source` itself is null where the failure is not about a part of the request. - `pointer` (string, json-pointer, nullable) - a JSON Pointer [RFC6901](https://tools.ietf.org/html/rfc6901) to the value in the request document that caused the error [e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute]. This MUST point to a value in the request document that exists; if it doesn’t, the client SHOULD simply ignore the pointer. - `parameter` (string, nullable) - A string indicating which URI query parameter caused the error. - `header` (string, nullable) - A string indicating the name of a single request header which caused the error. - `meta` (object, nullable) - A [meta object](https://jsonapi.org/format/#document-meta) containing non-standard meta-information about the error. Null where the request carried no `X-Correlation-ID`, and on an authentication failure, which does not echo it. - `correlationId` (string) - The `X-Correlation-ID` sent with the request, echoed back so it can be quoted to support. Absent when the request carried no correlation header. Example (A field in the request body did not validate): ```json { "id": "3a6c9e01-5f2b-4d8a-9c47-1e0b7d5a2f83", "links": null, "code": "BadRequest", "title": "Bad Request", "detail": "amount: Amount must be greater than 0", "source": { "pointer": "/amount", "parameter": null, "header": null }, "meta": { "correlationId": "497f6eca-6276-4993-bfeb-53cbbbba6f08" } } ``` ### 401 Unauthorised. - Header `X-Correlation-ID`: The correlation id for the request that was processed. `Error`, the same schema listed in full earlier in this document. Its own page: https://hub.ozow.com/api-reference/one-api/schemas/error.md Example (No usable access token on the request): ```json { "id": "1cecc2b7-1c29-418a-b26a-bf7546926083", "links": { "about": "https://ozow.stoplight.io/docs/one-api/zi18vomr0jm8c-generate-authentication-token", "type": "https://tools.ietf.org/html/rfc7235#section-3.1" }, "code": "Unauthorized", "title": "Unauthorized Request", "detail": "Authorization header is missing or invalid.", "source": { "pointer": null, "parameter": null, "header": "Authorization" }, "meta": null } ``` ### 403 Forbidden. - Header `X-Correlation-ID`: The correlation id for the request that was processed. `Error`, the same schema listed in full earlier in this document. Its own page: https://hub.ozow.com/api-reference/one-api/schemas/error.md Example (The token is valid but lacks the scope the operation needs): ```json { "id": "c47a2e08-9b31-4f6d-85a0-7e2c1d9f3b56", "links": { "about": "https://ozow.stoplight.io/docs/one-api/zi18vomr0jm8c-generate-authentication-token", "type": "https://tools.ietf.org/html/rfc7235#section-3.1" }, "code": "Forbidden", "title": "Forbidden Request", "detail": "Request is forbidden, most likely scope does not match required scope to perform requested action.", "source": { "pointer": null, "parameter": null, "header": "Authorization" }, "meta": { "correlationId": "497f6eca-6276-4993-bfeb-53cbbbba6f08" } } ``` ### 409 Conflict. - Header `X-Correlation-ID`: The correlation id for the request that was processed. `Error`, the same schema listed in full earlier in this document. Its own page: https://hub.ozow.com/api-reference/one-api/schemas/error.md Example (The idempotency key was reused with a different body): ```json { "id": "2f8b6d40-1c7e-49a5-b03f-8d5a2e1c9704", "links": null, "code": "Conflict", "title": "Conflict", "detail": "Idempotency key and request data do not match a previous request.", "source": { "pointer": null, "parameter": null, "header": "Idempotency-Key" }, "meta": { "correlationId": "497f6eca-6276-4993-bfeb-53cbbbba6f08" } } ``` ### 500 Internal Server Error. - Header `X-Correlation-ID`: The correlation id for the request that was processed. `Error`, the same schema listed in full earlier in this document. Its own page: https://hub.ozow.com/api-reference/one-api/schemas/error.md Example (The request failed on the Ozow side): ```json { "id": "9e0d5a83-6b24-4c19-8f7a-2d1b3e6c0a97", "links": null, "code": "InternalServerError", "title": "Internal Server Error", "detail": "Error occurred while processing request.", "source": { "pointer": "/data", "parameter": null, "header": null }, "meta": { "correlationId": "497f6eca-6276-4993-bfeb-53cbbbba6f08" } } ``` --- # Cancel Payment Request > POST `/payments/{id}/cancel` > Part of the One API reference. Source: https://hub.ozow.com/api-reference/one-api/post-payments-id-cancel/ Server: `https://one.ozow.com/v1` (Production) Other environments: `https://stagingone.ozow.com/v1` (Staging) Cancels the payment request with the specified `id`. ## Authentication - `Authentication` (oauth2) - Scopes: `payments` ## Path parameters - `id` (string, required) - The unique identifier of the payment. ## Header parameters - `Idempotency-Key` (string) - The unique key idempotency key as per the following [IETF Draft](https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/) - `X-Correlation-ID` (string) - Optional correlation id for the request, if not supplied a new one will be generated and passed onto all underlying requests and returned as a header. ## Responses ### 200 OK. The payment has been cancelled. - Header `X-Correlation-ID`: The correlation id for the request that was processed. ### 201 Created. The payment has been cancelled - Header `X-Correlation-ID`: The correlation id for the request that was processed. ### 403 Forbidden. - Header `X-Correlation-ID`: The correlation id for the request that was processed. - `id` (string, uuid, required) - a unique identifier for this particular occurrence of the problem. - `links` (object, nullable) - Present on an authentication or authorisation failure, and null otherwise. - `about` (string, uri) - A link that leads to further details about this particular occurrence of the problem. When derefenced, this URI SHOULD return a human-readable description of the error. - `type` (string, uri) - A link that identifies the type of error that this particular error is an instance of. This URI SHOULD be dereferencable to a human-readable explanation of the general error. - `code` (string, required) - An application-specific error code, expressed as a string value. Key on this rather than on `title` or `detail`, which are written for a person. A rejection at the transport level uses the status name, one of `BadRequest`, `Unauthorized`, `Forbidden`, `NotFound`, `NotAllowed`, `Conflict`, `UnsupportedMediaType`, `BadGateway` or `InternalServerError`. An operation refusing a request on its own rules returns a code of its own. - `title` (string, required) - A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization. - `detail` (string, required) - A human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized. - `source` (object, nullable) - Where in the request the problem was found. All three keys are present whenever `source` is, with the ones that do not apply set to null. `source` itself is null where the failure is not about a part of the request. - `pointer` (string, json-pointer, nullable) - a JSON Pointer [RFC6901](https://tools.ietf.org/html/rfc6901) to the value in the request document that caused the error [e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute]. This MUST point to a value in the request document that exists; if it doesn’t, the client SHOULD simply ignore the pointer. - `parameter` (string, nullable) - A string indicating which URI query parameter caused the error. - `header` (string, nullable) - A string indicating the name of a single request header which caused the error. - `meta` (object, nullable) - A [meta object](https://jsonapi.org/format/#document-meta) containing non-standard meta-information about the error. Null where the request carried no `X-Correlation-ID`, and on an authentication failure, which does not echo it. - `correlationId` (string) - The `X-Correlation-ID` sent with the request, echoed back so it can be quoted to support. Absent when the request carried no correlation header. Example (The token is valid but lacks the scope the operation needs): ```json { "id": "c47a2e08-9b31-4f6d-85a0-7e2c1d9f3b56", "links": { "about": "https://ozow.stoplight.io/docs/one-api/zi18vomr0jm8c-generate-authentication-token", "type": "https://tools.ietf.org/html/rfc7235#section-3.1" }, "code": "Forbidden", "title": "Forbidden Request", "detail": "Request is forbidden, most likely scope does not match required scope to perform requested action.", "source": { "pointer": null, "parameter": null, "header": "Authorization" }, "meta": { "correlationId": "497f6eca-6276-4993-bfeb-53cbbbba6f08" } } ``` ### 404 Not found. The item with the specified identifier could not be found, or this resource is not allowed for the resource identifier. - Header `X-Correlation-ID`: The correlation id for the request that was processed. `Error`, the same schema listed in full earlier in this document. Its own page: https://hub.ozow.com/api-reference/one-api/schemas/error.md Example (No resource with that identifier): ```json { "id": "5b9e3c17-4a8d-42f0-9e61-3c7b0f2a8d15", "links": null, "code": "NotFound", "title": "Not Found", "detail": "The requested resource was not found.", "source": { "pointer": "/data", "parameter": "/v1/payments/497f6eca-6276-4993-bfeb-53cbbbba6f08", "header": null }, "meta": { "correlationId": "497f6eca-6276-4993-bfeb-53cbbbba6f08" } } ``` ### 500 Internal Server Error. - Header `X-Correlation-ID`: The correlation id for the request that was processed. `Error`, the same schema listed in full earlier in this document. Its own page: https://hub.ozow.com/api-reference/one-api/schemas/error.md Example (The request failed on the Ozow side): ```json { "id": "9e0d5a83-6b24-4c19-8f7a-2d1b3e6c0a97", "links": null, "code": "InternalServerError", "title": "Internal Server Error", "detail": "Error occurred while processing request.", "source": { "pointer": "/data", "parameter": null, "header": null }, "meta": { "correlationId": "497f6eca-6276-4993-bfeb-53cbbbba6f08" } } ``` --- # Generate Authentication Token > POST `/token` > Part of the One API reference. Source: https://hub.ozow.com/api-reference/one-api/post-token/ Server: `https://one.ozow.com/v1` (Production) Other environments: `https://stagingone.ozow.com/v1` (Staging) Retrieve an authentication token as per the [OpenAuth 2.0 Client Credential Flow](https://datatracker.ietf.org/doc/html/rfc6749#section-4.4). ## Authentication This operation takes no credentials. ## Header parameters - `X-Correlation-ID` (string) - Optional correlation id for the request, if not supplied a new one will be generated and passed onto all underlying requests and returned as a header. ## Request body - `client_id` (string, required) - The unique client id provided to the merchant during credential exchange. - `client_secret` (string, required) - The secret provided to the merchant during credential exchange. - `scope` (string, required) - The scope of permissions required. Can be just one or a list of space-delimited, case-sensitive strings. - `grant_type` (string, required) - Must be _client_credentials_. ## Responses ### 200 Succesfull response as per [RFC 6749](https://datatracker.ietf.org/doc/html/rfc6749#section-5.1) - Header `X-Correlation-ID`: The correlation id for the request that was processed. - `access_token` (string, required) - The access token issued by the authorization server. - `token_type` (string, required) - Must be `bearer` as in [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750). - `expires_in` (string, required) - The lifetime in seconds of the access token. For example, the value "3600" denotes that the access token will expire in one hour from the time the response was generated. - `scope` (string) - OPTIONAL, if identical to the scope requested by the client; otherwise, REQUIRED. ### 400 Bad Request. - Header `X-Correlation-ID`: The correlation id for the request that was processed. - `id` (string, uuid, required) - a unique identifier for this particular occurrence of the problem. - `links` (object, nullable) - Present on an authentication or authorisation failure, and null otherwise. - `about` (string, uri) - A link that leads to further details about this particular occurrence of the problem. When derefenced, this URI SHOULD return a human-readable description of the error. - `type` (string, uri) - A link that identifies the type of error that this particular error is an instance of. This URI SHOULD be dereferencable to a human-readable explanation of the general error. - `code` (string, required) - An application-specific error code, expressed as a string value. Key on this rather than on `title` or `detail`, which are written for a person. A rejection at the transport level uses the status name, one of `BadRequest`, `Unauthorized`, `Forbidden`, `NotFound`, `NotAllowed`, `Conflict`, `UnsupportedMediaType`, `BadGateway` or `InternalServerError`. An operation refusing a request on its own rules returns a code of its own. - `title` (string, required) - A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization. - `detail` (string, required) - A human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized. - `source` (object, nullable) - Where in the request the problem was found. All three keys are present whenever `source` is, with the ones that do not apply set to null. `source` itself is null where the failure is not about a part of the request. - `pointer` (string, json-pointer, nullable) - a JSON Pointer [RFC6901](https://tools.ietf.org/html/rfc6901) to the value in the request document that caused the error [e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute]. This MUST point to a value in the request document that exists; if it doesn’t, the client SHOULD simply ignore the pointer. - `parameter` (string, nullable) - A string indicating which URI query parameter caused the error. - `header` (string, nullable) - A string indicating the name of a single request header which caused the error. - `meta` (object, nullable) - A [meta object](https://jsonapi.org/format/#document-meta) containing non-standard meta-information about the error. Null where the request carried no `X-Correlation-ID`, and on an authentication failure, which does not echo it. - `correlationId` (string) - The `X-Correlation-ID` sent with the request, echoed back so it can be quoted to support. Absent when the request carried no correlation header. Example (A field in the request body did not validate): ```json { "id": "3a6c9e01-5f2b-4d8a-9c47-1e0b7d5a2f83", "links": null, "code": "BadRequest", "title": "Bad Request", "detail": "amount: Amount must be greater than 0", "source": { "pointer": "/amount", "parameter": null, "header": null }, "meta": { "correlationId": "497f6eca-6276-4993-bfeb-53cbbbba6f08" } } ``` ### 401 Unauthorised. A scope in `scope` is not one this client is allowed. Scopes are granted per client, so a client can authenticate and still be refused a scope. - Header `X-Correlation-ID`: The correlation id for the request that was processed. `Error`, the same schema listed in full earlier in this document. Its own page: https://hub.ozow.com/api-reference/one-api/schemas/error.md Example (A requested scope is not granted to this client): ```json { "id": "4f7c0d2b-8a15-4e93-b06d-7c2e9f1a5b48", "links": { "about": "https://ozow.stoplight.io/docs/one-api/zi18vomr0jm8c-generate-authentication-token", "type": "https://tools.ietf.org/html/rfc7235#section-3.1" }, "code": "Unauthorized", "title": "Unauthorized Request", "detail": "Consumer does not have access to requested scope", "source": { "pointer": null, "parameter": null, "header": "Authorization" }, "meta": null } ``` ### 404 Not found. No client matches `client_id`, or the client has been deactivated. - Header `X-Correlation-ID`: The correlation id for the request that was processed. `Error`, the same schema listed in full earlier in this document. Its own page: https://hub.ozow.com/api-reference/one-api/schemas/error.md Example (The client id does not resolve): ```json { "id": "cccb6fb8-505e-4ff9-90b5-815ecf42424e", "links": null, "code": "NotFound", "title": "Not Found", "detail": "Consumer could not be found for client id YOUR_CLIENT_ID.", "source": { "pointer": "/data/clientId", "parameter": "/v1/token", "header": null }, "meta": { "correlationId": "497f6eca-6276-4993-bfeb-53cbbbba6f08" } } ``` ### 500 Internal Server Error. - Header `X-Correlation-ID`: The correlation id for the request that was processed. `Error`, the same schema listed in full earlier in this document. Its own page: https://hub.ozow.com/api-reference/one-api/schemas/error.md Example (The request failed on the Ozow side): ```json { "id": "9e0d5a83-6b24-4c19-8f7a-2d1b3e6c0a97", "links": null, "code": "InternalServerError", "title": "Internal Server Error", "detail": "Error occurred while processing request.", "source": { "pointer": "/data", "parameter": null, "header": null }, "meta": { "correlationId": "497f6eca-6276-4993-bfeb-53cbbbba6f08" } } ``` --- # Create Webhook Subscription > POST `/webhooks` > Part of the One API reference. Source: https://hub.ozow.com/api-reference/one-api/post-webhooks/ Server: `https://one.ozow.com/v1` (Production) Other environments: `https://stagingone.ozow.com/v1` (Staging) Create a webhook subscription. ## Authentication - `Authentication` (oauth2) - Scopes: `webhooks` ## Header parameters - `Idempotency-Key` (string) - The unique key idempotency key as per the following [IETF Draft](https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/) - `X-Correlation-ID` (string) - Optional correlation id for the request, if not supplied a new one will be generated and passed onto all underlying requests and returned as a header. ## Request body - `endpoint` (string, uri, required) - The uri of the webhook receiver. Must be reachable from the internet. `localhost` is rejected with a 403, so a local integration needs a tunnel rather than the address the browser uses. - `eventType` (any, required, one of "transaction.complete", "refund.complete") - The type of event the webhook subscribes to. - `messageType` (any, one of "thin", "full") - Defaults to `thin`. Specify `full` to receive a larger payload with as much detail as possible. ## Responses ### 200 OK. The request has been accepted. - Header `X-Correlation-ID`: The correlation id for the request that was processed. - `id` (string, uuid, required) - The unique identifier of the webhook. - `endpoint` (string, uri, required) - The uri of the webhook receiver. - `eventType` (any, required, one of "transaction.complete", "refund.complete") - The type of event the webhook subscribes to. - `messageType` (any, required, one of "thin", "full") - Defaults to `thin`. Specify `full` to receive a larger payload with as much detail as possible. ### 201 Created. The request has been accepted. - Header `X-Correlation-ID`: The correlation id for the request that was processed. `WebhookResponse`, the same schema listed in full earlier in this document. Its own page: https://hub.ozow.com/api-reference/one-api/schemas/webhook-response.md ### 400 Bad Request. - Header `X-Correlation-ID`: The correlation id for the request that was processed. - `id` (string, uuid, required) - a unique identifier for this particular occurrence of the problem. - `links` (object, nullable) - Present on an authentication or authorisation failure, and null otherwise. - `about` (string, uri) - A link that leads to further details about this particular occurrence of the problem. When derefenced, this URI SHOULD return a human-readable description of the error. - `type` (string, uri) - A link that identifies the type of error that this particular error is an instance of. This URI SHOULD be dereferencable to a human-readable explanation of the general error. - `code` (string, required) - An application-specific error code, expressed as a string value. Key on this rather than on `title` or `detail`, which are written for a person. A rejection at the transport level uses the status name, one of `BadRequest`, `Unauthorized`, `Forbidden`, `NotFound`, `NotAllowed`, `Conflict`, `UnsupportedMediaType`, `BadGateway` or `InternalServerError`. An operation refusing a request on its own rules returns a code of its own. - `title` (string, required) - A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization. - `detail` (string, required) - A human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized. - `source` (object, nullable) - Where in the request the problem was found. All three keys are present whenever `source` is, with the ones that do not apply set to null. `source` itself is null where the failure is not about a part of the request. - `pointer` (string, json-pointer, nullable) - a JSON Pointer [RFC6901](https://tools.ietf.org/html/rfc6901) to the value in the request document that caused the error [e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute]. This MUST point to a value in the request document that exists; if it doesn’t, the client SHOULD simply ignore the pointer. - `parameter` (string, nullable) - A string indicating which URI query parameter caused the error. - `header` (string, nullable) - A string indicating the name of a single request header which caused the error. - `meta` (object, nullable) - A [meta object](https://jsonapi.org/format/#document-meta) containing non-standard meta-information about the error. Null where the request carried no `X-Correlation-ID`, and on an authentication failure, which does not echo it. - `correlationId` (string) - The `X-Correlation-ID` sent with the request, echoed back so it can be quoted to support. Absent when the request carried no correlation header. Example (A field in the request body did not validate): ```json { "id": "3a6c9e01-5f2b-4d8a-9c47-1e0b7d5a2f83", "links": null, "code": "BadRequest", "title": "Bad Request", "detail": "amount: Amount must be greater than 0", "source": { "pointer": "/amount", "parameter": null, "header": null }, "meta": { "correlationId": "497f6eca-6276-4993-bfeb-53cbbbba6f08" } } ``` ### 401 Unauthorised. - Header `X-Correlation-ID`: The correlation id for the request that was processed. `Error`, the same schema listed in full earlier in this document. Its own page: https://hub.ozow.com/api-reference/one-api/schemas/error.md Example (No usable access token on the request): ```json { "id": "1cecc2b7-1c29-418a-b26a-bf7546926083", "links": { "about": "https://ozow.stoplight.io/docs/one-api/zi18vomr0jm8c-generate-authentication-token", "type": "https://tools.ietf.org/html/rfc7235#section-3.1" }, "code": "Unauthorized", "title": "Unauthorized Request", "detail": "Authorization header is missing or invalid.", "source": { "pointer": null, "parameter": null, "header": "Authorization" }, "meta": null } ``` ### 403 Forbidden. - Header `X-Correlation-ID`: The correlation id for the request that was processed. `Error`, the same schema listed in full earlier in this document. Its own page: https://hub.ozow.com/api-reference/one-api/schemas/error.md Example (The token is valid but lacks the scope the operation needs): ```json { "id": "c47a2e08-9b31-4f6d-85a0-7e2c1d9f3b56", "links": { "about": "https://ozow.stoplight.io/docs/one-api/zi18vomr0jm8c-generate-authentication-token", "type": "https://tools.ietf.org/html/rfc7235#section-3.1" }, "code": "Forbidden", "title": "Forbidden Request", "detail": "Request is forbidden, most likely scope does not match required scope to perform requested action.", "source": { "pointer": null, "parameter": null, "header": "Authorization" }, "meta": { "correlationId": "497f6eca-6276-4993-bfeb-53cbbbba6f08" } } ``` ### 409 Conflict. - Header `X-Correlation-ID`: The correlation id for the request that was processed. `Error`, the same schema listed in full earlier in this document. Its own page: https://hub.ozow.com/api-reference/one-api/schemas/error.md Example (The idempotency key was reused with a different body): ```json { "id": "2f8b6d40-1c7e-49a5-b03f-8d5a2e1c9704", "links": null, "code": "Conflict", "title": "Conflict", "detail": "Idempotency key and request data do not match a previous request.", "source": { "pointer": null, "parameter": null, "header": "Idempotency-Key" }, "meta": { "correlationId": "497f6eca-6276-4993-bfeb-53cbbbba6f08" } } ``` ### 500 Internal Server Error. - Header `X-Correlation-ID`: The correlation id for the request that was processed. `Error`, the same schema listed in full earlier in this document. Its own page: https://hub.ozow.com/api-reference/one-api/schemas/error.md Example (The request failed on the Ozow side): ```json { "id": "9e0d5a83-6b24-4c19-8f7a-2d1b3e6c0a97", "links": null, "code": "InternalServerError", "title": "Internal Server Error", "detail": "Error occurred while processing request.", "source": { "pointer": "/data", "parameter": null, "header": null }, "meta": { "correlationId": "497f6eca-6276-4993-bfeb-53cbbbba6f08" } } ``` --- # TransactionCompleteFullData > A schema in the One API reference. Source: https://hub.ozow.com/api-reference/one-api/schemas/transaction-complete-full-data/ The `data` of a `transaction.complete` delivery whose subscription asked for `full`. It is the field set the Payments API posts to a notify URL, so a handler written for that notification reads this unchanged. Every value is a string, including the amount and the flags. ## Fields - `SiteCode` (string, required) - The site the transaction was created against. - `TransactionId` (string, uuid, required) - The transaction identifier. - `TransactionReference` (string, required) - Your own reference for the transaction. - `Amount` (string, required) - The amount, to two decimal places, with a full stop as the separator. - `Status` (string, required, one of "Successful", "Incomplete", "Pending", "Error") - The mapped status, the same four values the `thin` payload carries. - `Optional1` (string, required) - Your first optional field, empty when it was not set. - `Optional2` (string, required) - Your second optional field, empty when it was not set. - `Optional3` (string, required) - Your third optional field, empty when it was not set. - `Optional4` (string, required) - Your fourth optional field, empty when it was not set. - `Optional5` (string, required) - Your fifth optional field, empty when it was not set. - `CurrencyCode` (string, required) - The ISO 4217 currency code. - `IsTest` (string, required, one of "True", "False") - Whether the transaction was a test one. - `StatusMessage` (string, required) - The status detail, empty when there is none. - `Hash` (string, required) - The check hash over the field set, the same one the Payments API notification carries. Verify the Svix signature rather than this: the signature covers the whole delivery. - `SubStatus` (string) - Present only when the transaction has a sub-status. - `SubStatusDescription` (string) - Present only when the sub-status has a description. - `MaskedAccountNumber` (string) - The payer's masked account number. Present only when your site is configured to receive it and the transaction is complete, pending or under investigation. - `BankName` (string) - The payer's bank. Absent when your site is configured for legacy fields only. - `SmartIndicators` (string) - The risk indicators. Present only on a complete transaction that has them, and never when your site is configured for legacy fields only. - `BankId` (string) - Present only on a live transaction when your site is configured to receive banking details. - `AccountNumber` (string) - Present only on a live transaction when your site is configured to receive banking details. - `PublicRecipientName` (string) - Present only on a live transaction when your site is configured to receive banking details. --- # WebhookEnvelope > A schema in the One API reference. Source: https://hub.ozow.com/api-reference/one-api/schemas/webhook-envelope/ Every delivery has this shape. `data` is what the subscription's message type decides. ## Fields - `type` (string, required) - The event type the subscription was created for. - `timestamp` (string, date-time, required) - When the event was raised. - `data` (any of, required) - What the subscription's message type decides. A `thin` subscription receives `WebhookEventData`, which is every event's default and the only form the subscription events support. A `full` subscription to `transaction.complete` receives `TransactionCompleteFullData`, and to `refund.complete`, `RefundCompleteFullData`. A `full` subscription to any of the subscription events receives nothing at all. - Option 1: `WebhookEventData` - Option 2: `TransactionCompleteFullData` - Option 3: `RefundCompleteFullData` --- # WebhookEventData > A schema in the One API reference. Source: https://hub.ozow.com/api-reference/one-api/schemas/webhook-event-data/ The `data` of a delivery whose subscription asked for `thin`, which is every subscription event and the default for the rest. ## Fields - `id` (string, uuid, required) - What the event is about: the transaction, the refund, or the subscription. - `status` (string, required) - The outcome. The values differ per event: see the event's own description. - `reason` (string, nullable) - The status message, when there is one to give. --- # Transaction completed > POST to your notification URL > Sent by Ozow. Part of the One API reference. Source: https://hub.ozow.com/api-reference/one-api/webhooks/transaction-complete/ Raised when a transaction reaches a final state. `status` is one of `Successful`, `Incomplete`, `Pending` or `Error`. These are not the transaction's own statuses: they are mapped down to four. `Complete` becomes `Successful`, `Created` becomes `Incomplete`, `Pending` and `PendingInvestigation` become `Pending`, and everything else becomes `Error`, which includes a cancelled, abandoned or voided payment. `reason` carries the detail. A subscription registered as `full` receives `TransactionCompleteFullData` in `data` instead, which is the field set the Payments API posts to a notify URL. Delivered by Svix, with `svix-id`, `svix-timestamp` and `svix-signature` headers. Verify the signature with the webhook's secret before acting on the contents. ## Authentication Ozow sends no credential with this call, so this check is the only thing standing between a real delivery and a stranger’s. Verify the delivery signature before acting on the contents: your notification URL is public, and anyone can post to it. ## Payload **application/json** - `type` (string, required) - The event type the subscription was created for. - `timestamp` (string, date-time, required) - When the event was raised. - `data` (any of, required) - What the subscription's message type decides. A `thin` subscription receives `WebhookEventData`, which is every event's default and the only form the subscription events support. A `full` subscription to `transaction.complete` receives `TransactionCompleteFullData`, and to `refund.complete`, `RefundCompleteFullData`. A `full` subscription to any of the subscription events receives nothing at all. - Option 1: `WebhookEventData` - Option 2: `TransactionCompleteFullData` - Option 3: `RefundCompleteFullData` ## Your response ### 200 Acknowledged. Return this once you have stored the event. No body.