# Migrate refunds from the Payments API to One API > Everything needed to move an existing refunds integration onto One API, with the legacy guide and its One API counterpart side by side. Both sides are implemented against: the legacy refunds endpoints and their One API counterparts. Read Step 6 of the migration guide, which maps them, then the two refund guides beside each other. Authentication and the notification change with the rest of the integration, so read the payin package first if you have not moved that yet: a refund on One API needs a bearer token and a verified Svix signature, and the endpoints changed shape at the same time. Refunds are funded from your float balance on both APIs. A refund above that balance fails rather than queueing. Refund statuses reuse names that also appear on payins and mean something different there. Handle every refund status the statuses page lists. Test and live are separated by environment, not by a flag on the request. ## 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 - `payments-api` version 1.0, OpenAPI document: https://hub.ozow.com/api-reference/specs/payments-api.yaml - Build against `https://one.ozow.com/v1` for `one-api` - Build against `https://api.ozow.com` for `payments-api` - 7 pages, 20 operations, inlined in full below - The same package as links: https://hub.ozow.com/bundles/migrate-refunds-to-one-api.md --- # Implement against these Every field name, order and format below is exact. Copy them as written. --- # Migrating to One API > Map a redirect payin and refunds integration from the Payments API to One API: what changes, what does not, and the order to make the changes in. Source: https://hub.ozow.com/integration-methods/apis/deprecated-integrations/migrating-to-one-api/ This guide maps a redirect payin and refunds integration from the Payments API to One API. It covers what changes, what does not, and the order to make the changes in. One API is the current integration path. The Payments API continues to process live traffic and is not being switched off on a fixed date, but it does not receive new features, new payment methods are added to One API first. ## Before you start - You have a working Payments API integration using [Redirect: Payments API](https://hub.ozow.com/integration-methods/apis/deprecated-integrations/redirect-to-ozow.md), [Refunds: Payments API](https://hub.ozow.com/integration-methods/apis/deprecated-integrations/refund-a-payment.md), or both - 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 can run a staging integration against One API before touching production > ℹ️ **Note**: Only users with administrator privileges in the Ozow Dashboard can access the One API > Clients section. ## What does not change - Your site code stays the same - The payment methods available to your customers, Pay by Bank, Capitec Pay, Buy Now Pay Later, PayShap Request, are the same products on both APIs - Your float, settlement schedule, and Ozow Dashboard reporting are shared across both APIs - ZAR is the only supported currency on either API ## What changes | Concept | Payments API | One API | |---|---|---| | Authentication | API key plus a SHA512 hash signed with your private key, per request | OAuth 2.0 Client Credentials, a bearer token from `/v1/token` | | Request shape | Flat form fields, mostly `PascalCase` in notifications, `camelCase` in requests | Nested JSON resources, `camelCase` throughout | | Creating a payment | `POST /postpaymentrequest` returns a `url` directly | `POST /v1/payments` returns a `Payment` resource with a `redirectUrl` and a set of `links` | | Payment outcome | The payment request and its outcome are one resource, reported by notification | A `Payment` is the checkout session; each attempt against it is a separate `Transaction`, retrieved via `GET /payments/{id}/transactions` | | Cancelling before completion | Not possible via API, only the customer can abandon the payment page | `POST /payments/{id}/cancel` | | Outcome delivery | A form-encoded POST to `notifyUrl`, authenticated with a hash you verify yourself | A signed webhook delivered via [Svix](https://www.svix.com/), authenticated with `svix-id`, `svix-timestamp`, and `svix-signature` | | Refunds | Submitted as a batch array to `/secure/refunds/submit`, one hash check per item | `POST /transactions/{id}/refunds` for a single transaction, or `POST /refunds` for a batch, both idempotent via an `Idempotency-Key` header | | Cancelling a refund | Not possible via API | `POST /refunds/{id}/cancel` | | Standalone payment method button | `selectedBankId` field in the payment request | `institutionId` field in the payment request | | Customer Identity Verification | Flat `customerIdentifier` field | Nested `payer.identity` object with `type`, `country`, and `identifier` | | Retrying a failed request safely | Not supported, a resubmitted request is a new payment request | `Idempotency-Key` header on `POST` and `PUT` requests: replaying the same key returns the original result instead of creating a duplicate | | Recurring payments | Not available | Available, see [Recurring payments: One API](https://hub.ozow.com/integration-methods/apis/recurring-payments/set-up-recurring-payments.md) | | Embedded checkout | Not available, redirect only | Available: [iframe](https://hub.ozow.com/integration-methods/apis/payin/embedded-iframe.md), [modal](https://hub.ozow.com/integration-methods/apis/payin/embedded-modal.md), and [Wallet SDK](https://hub.ozow.com/integration-methods/apis/payin/embedded-wallet.md) | --- ## Step 1: Replace hash-based authentication with OAuth The Payments API signs every request with a SHA512 hash built from your private key. One API instead issues a short-lived bearer token from your Client ID and Client Secret. Remove your hash-generation code entirely, there is no request hash in One API. Replace it with a token request: ```endpoint POST https://one.ozow.com/v1/token Content-Type: application/x-www-form-urlencoded ``` ```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" ``` A token carries the scopes you asked for and no others, and each scope is refused on the endpoints outside it. Request the scope the calling code needs rather than one token for the whole integration: | What the code is doing | Scope | Where | |---|---|---| | Creating a payment, cancelling it, reading its transactions | `payments` | Steps 2, 3 and 5 | | Managing the webhook endpoint and reading its signing secret | `webhooks` | Step 4 | | Issuing and cancelling refunds | `refunds` | Step 6 | A `payments` token is refused with `403 Forbidden` on the webhook and refund endpoints, so the three parts of your integration hold three tokens. Cache them separately. Asking for a scope your client has not been granted is refused at the token request itself. 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. Cache the token and request a new one before it expires, rather than requesting one per payment. See [Step 1: Obtain an access token](https://hub.ozow.com/integration-methods/apis/payin/redirect-to-ozow.md#step-1-obtain-an-access-token) for the full flow and code samples in C#, PHP, JavaScript, and Python. > ⚠️ **Important**: Your private key has no equivalent in One API and is not used for anything. Do > not send it, and retire it from your secrets store once the migration is complete and the Payments > API integration is decommissioned. --- ## Step 2: Move from flat fields to nested resources The Payments API request is a single flat object. One API groups related fields, most visibly `amount` becomes an object with `currency` and `value`. **Payments API** ```json { "siteCode": "YOUR_SITE_CODE", "countryCode": "ZA", "currencyCode": "ZAR", "amount": "100.00", "transactionReference": "ORDER-001", "bankReference": "ABC123", "cancelUrl": "https://yourstore.com/cancel", "errorUrl": "https://yourstore.com/error", "successUrl": "https://yourstore.com/success", "notifyUrl": "https://yourstore.com/notify", "isTest": false, "hashCheck": "YOUR_GENERATED_HASH" } ``` **One API** ```json { "siteCode": "YOUR_SITE_CODE", "amount": { "currency": "ZAR", "value": 100.00 }, "merchantReference": "ORDER-001", "beneficiaryReference": "ABC123", "expireAt": "2026-12-31T23:59:59Z", "returnUrl": "https://yourstore.com/order-complete" } ``` **Field mapping** | Payments API | One API | Notes | |---|---|---| | `siteCode` | `siteCode` | Unchanged | | `countryCode` | `region` | Same ISO 3166-alpha-2 code, renamed and moved to the top level. Optional on One API, and defaults to `ZA` when you omit it | | `currencyCode` | `amount.currency` | Moves inside `amount`, and must be `ZAR` | | `amount` (string) | `amount.value` (number) | One API takes a numeric value, not a pre-formatted string | | `transactionReference` | `merchantReference` | Same purpose, renamed. Still the reference the payer sees on their own statement, and still yours to keep unique | | `bankReference` | `beneficiaryReference` | Same purpose, renamed: the reference that appears on **your** bank statement, for recon. One API is stricter, letters and numbers only where the Payments API also allowed spaces, dashes and punctuation | | `cancelUrl`, `errorUrl`, `successUrl` | `returnUrl` | One API redirects to a single `returnUrl` regardless of outcome; determine the outcome from a verified webhook or the transactions endpoint, not from which URL fired | | `notifyUrl` | `notifyUrl` | Still accepted, still optional, and still per payment request. Move to webhooks instead: they are configured once and signed, and Step 4 is that change | | `expiryDateUtc` | `expireAt` | **Now required on every payment request**, where the Payments API let you omit it. ISO 8601 (`2026-12-31T23:59:59Z`) rather than `yyyy-MM-dd HH:mm` | | `isTest` | Not a request field | Test and live are separated by environment (`stagingone.ozow.com` vs `one.ozow.com`), not by a flag on the request | | `hashCheck` | Not a request field | Removed entirely, see Step 1 | For the full request and response schema see [Create a payment](https://hub.ozow.com/api-reference/one-api/post-payments.md). --- ## Step 3: Update how you read the response and redirect the customer **Payments API response** ```json { "paymentRequestId": "00000000-0000-0000-0000-000000000000", "url": "https://pay.ozow.com/00000000-0000-0000-0000-000000000000/Secure", "errorMessage": null } ``` **One API 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" } ``` Redirect the customer to `redirectUrl` instead of `url`. Store `id` instead of `paymentRequestId`, you use it to check transactions or cancel the payment later. > ⚠️ **Important**: Persist that `id` against your order, before you redirect. On One API the `id` is > the handle to the payment: [Get a payment](https://hub.ozow.com/api-reference/one-api/get-payments-id.md), [List its > transactions](https://hub.ozow.com/api-reference/one-api/get-payments-id-transactions.md) and [Cancel > it](https://hub.ozow.com/api-reference/one-api/post-payments-id-cancel.md) all key off it, where the Payments API keyed off > the reference you chose. Store it with the order rather than for the life of the request. > ⚠️ **Important**: The Payments API returns a rejected request as HTTP 200 with a `null` `url` and > a reason in `errorMessage`. One API uses HTTP status codes for this instead, a validation failure > comes back as `400 Bad Request` with an `Error` body. Update your error handling to check the > status code rather than inspecting the response body for a `null` URL. A `Payment` created but never completed by the customer settles into one of two `PaymentStatus` values, `Created` or `Expired`. This is a separate concept from the transaction outcome, see Step 5. --- ## Step 4: Move from a per-request notifyUrl to a webhook subscription The Payments API takes a `notifyUrl` on every payment request and posts a form-encoded notification to it. One API configures a webhook endpoint once, and delivers signed events to it for every subsequent payment. **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). These need a token with the `webhooks` scope, and so does [Get Webhook Secret](https://hub.ozow.com/api-reference/one-api/get-webhooks-id-secret.md) below. Your payin token does not reach them **Subscribe to [`transaction.complete`](https://hub.ozow.com/api-reference/one-api/webhooks/transaction-complete.md)** to receive the same outcome your Payments API `notifyUrl` delivers. Choose the `full` message type if you need transaction details in the payload, or `thin` if you will call the API separately for details. Replace your hash verification with signature verification. Every webhook carries `svix-id`, `svix-timestamp` and `svix-signature` headers, and [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. 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 notification without first verifying its signature, in > exactly the way you never processed a Payments API notification without first verifying its hash. > Log and alert on verification failures. See [Step 4: Handle the webhook notification](https://hub.ozow.com/integration-methods/apis/payin/redirect-to-ozow.md#step-4-handle-the-webhook-notification) for the full webhook setup and verification process. --- ## Step 5: Re-map transaction statuses The Payments API reports one flat status on the notification. One API separates the `Payment` (the checkout session) from each `Transaction` attempted against it, and the transaction carries the outcome you act on. **Payments API notification statuses** | Status | Description | |---|---| | `Complete` | Payment completed successfully | | `Cancelled` | Customer cancelled the payment | | `Error` | An error occurred: check `SubStatus` for detail | | `Abandoned` | Customer left the payment page without completing | | `Pending` | The outcome is not known yet and is reposted to your `notifyUrl` once it is. If you do not use a `notifyUrl` you receive `PendingInvestigation` instead | | `PendingInvestigation` | Payment is under review: do not credit until resolved | **One API transaction statuses** | Status | Description | |---|---| | `Successful` | The transaction completed, credit the order | | `Incomplete` | The customer did not complete the payment attempt | | `Error` | The transaction failed. `reason` carries the detail | | `Pending` | The transaction is still in progress | | `Refunded` | The transaction completed and has since been refunded | These are not the same enumeration and the values do not line up one to one. `Refunded` has no Payments API equivalent, because a refund was reported as a separate resource entirely. Audit every status comparison before you cut over. `Error` and `Pending` keep their spelling across both APIs, but `Complete` becomes `Successful`. An equality check against `Complete` therefore returns false for every One API transaction without raising an error, leaving paid orders unfulfilled. Treat `Successful` as the only status that means the order is paid. > ⚠️ **Important**: Never update an order status without first verifying the webhook signature, the > same rule as the Payments API notification hash. --- ## Step 6: Rebuild refunds on the new endpoints If you issue refunds, the request and authentication both change alongside the payin flow. - Request a token with the `refunds` scope, the same call as Step 1 with a different `scope`. This replaces the Payments API's separate `/token` bearer flow for refunds, and it is a different token from the one your payin code holds - Replace the batch array to `/secure/refunds/submit` with either `POST /transactions/{id}/refunds` for a single refund or `POST /refunds` for a batch, see [Refunds: One API](https://hub.ozow.com/integration-methods/apis/refunds/refund-a-payment.md) - Add an `Idempotency-Key` header to every refund request, retrying a failed submission with the same key returns the original result instead of issuing a second refund - Drop your per-item hash check, refund requests are authenticated by the bearer token alone - `refundReason` becomes `reason`, and is still required - `isRtc` becomes `realTimePayment` - Refund statuses keep their spelling but shrink from nine values to six: `Pending`, `Submitted`, `Complete`, `Failed`, `Cancelled` and `Returned`. `PendingInvestigation`, `Invalid` and `Error` do not exist on One API, so any branch you have for those three needs somewhere else to go --- ## Migrating without downtime Do not attempt a single cutover. Payments API and One API are separate systems, and a payment created on one is not visible on the other. 1. Build and test the full One API flow in staging: token, payment creation, webhook delivery, and refunds if you use them 2. Deploy the One API integration behind a flag or a new code path, without removing the Payments API path yet 3. Route new payments to One API while existing in-flight Payments API payments finish on the old flow 4. Keep your Payments API webhook handler live until every payment created before the cutover has resolved, a payment can still complete or time out for some time after creation 5. Once no in-flight Payments API payments remain, decommission the old endpoint calls, retire the private key, and remove the hash-generation code > ⚠️ **Important**: Test in the staging environment before switching production traffic. Staging > credentials and endpoints are entirely separate between the two APIs, a Payments API staging site > code does not carry over to One API. --- ## What this guide does not cover If your Payments API integration uses more than payin and refunds, the rest moves too, and each part has its own guide rather than a step here: | On the Payments API | Where it goes | |---|---| | `/secure/settlements`, `/secure/settlements/getsitesettlements` | [Reconcile settlements](https://hub.ozow.com/integration-methods/apis/settlements/reconcile-settlements.md) | | `/secure/banktransfer/single`, `/secure/banktransfer/multiple` | [Send a payout](https://hub.ozow.com/integration-methods/apis/payout/send-a-payout.md) | | `/secure/bulkpaymentrequests/create` | No One API equivalent, contact support before you migrate | Migrate payin first. The others are separate integrations against separate endpoints, and each can move on its own schedule. --- ## Next steps - Review the [Building a secure integration](https://hub.ozow.com/getting-started/building-a-secure-integration.md) checklist, the webhook and credential handling sections apply to One API's model - Test your migrated integration using [Payin test cases](https://hub.ozow.com/integration-methods/testing/payin-test-cases-one-api.md) - See [Redirect: One API](https://hub.ozow.com/integration-methods/apis/payin/redirect-to-ozow.md) and [Refunds: One API](https://hub.ozow.com/integration-methods/apis/refunds/refund-a-payment.md) for the complete guides - Contact [support@ozow.com](mailto:support@ozow.com) if you need your One API Client ID and Client Secret issued or your webhook endpoint configured --- # Refund a payment > Issue a refund on the Payments API, the legacy path. Refunds are merchant-initiated backend operations, funded from your float balance. Source: https://hub.ozow.com/integration-methods/apis/deprecated-integrations/refund-a-payment/ > ⚠️ **Legacy integration**: The Payments API is a legacy integration path. For new integrations, > use [Refunds: One API](https://hub.ozow.com/integration-methods/apis/refunds/refund-a-payment.md) instead. This guide is for merchants > already using the Payments API. This guide walks you through issuing refunds to your customers using the Payments API. Refunds are merchant-initiated backend operations, there is no customer-facing step. The entire flow happens in your backend. > ℹ️ **Float required**: Ozow uses your float balance to fund refunds. Make sure your float has > sufficient funds before issuing refunds. See the [Float top-up > guide](https://hub.ozow.com/payment-products/settlements-and-float/float-top-up.md) to load funds into your > float. ## Before you start - You have your API key and site code from your [Ozow Dashboard](https://dash.ozow.com) - Your float balance is sufficient to cover the refund amounts - You have the transaction IDs of the original payments you want to refund - If you use `notifyUrl` to receive refund status updates, it is publicly accessible via HTTPS ## Environments | Environment | Base URL | Dashboard | |---|---|---| | Production | `https://api.ozow.com` | [dash.ozow.com](https://dash.ozow.com) | | Staging | `https://stagingapi.ozow.com` | [stagingdash.ozow.com](https://stagingdash.ozow.com) | --- ## How refunds work The Payments API processes refunds in batches. Even when you are refunding a single transaction, you submit it as an array containing one refund request. Each refund item in the array requires its own hash check. ```mermaid sequenceDiagram participant M as Your system participant O as Payments API participant B as Customer bank account M->>O: POST /token O-->>M: Returns a bearer token M->>M: Generate a hash check per refund item M->>O: POST /secure/refunds/submit O-->>M: Returns a refundId per item O->>B: Processes the refund to the original bank account O-->>M: Sends a notification to notifyUrl M->>M: Verifies the notification hash M->>M: Updates the refund status ``` --- ## Step 1: Get a bearer token Refund endpoints authenticate with a bearer token rather than the API key directly. Request one before submitting refunds. ```endpoint POST https://api.ozow.com/token ApiKey: YOUR_API_KEY Content-Type: application/x-www-form-urlencoded ``` **cURL** ```bash curl -X POST "https://api.ozow.com/token" \ -H "ApiKey: " \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=Password&SiteCode=YOUR_SITE_CODE" ``` **C#** ```csharp var client = new HttpClient(); client.DefaultRequestHeaders.Add("ApiKey", "YOUR_API_KEY"); var content = new FormUrlEncodedContent( new[] { new KeyValuePair("grant_type", "Password"), new KeyValuePair("SiteCode", "YOUR_SITE_CODE"), } ); var response = await client.PostAsync("https://api.ozow.com/token", content); var result = await response.Content.ReadAsStringAsync(); ``` **PHP** ```php "https://api.ozow.com/token", CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_POSTFIELDS => http_build_query([ "grant_type" => "Password", "SiteCode" => "YOUR_SITE_CODE", ]), CURLOPT_HTTPHEADER => [ "ApiKey: YOUR_API_KEY", "Content-Type: application/x-www-form-urlencoded", ], ]); $response = curl_exec($curl); curl_close($curl); echo $response; ?> ``` **JavaScript** ```javascript const response = await fetch("https://api.ozow.com/token", { method: "POST", headers: { "ApiKey": "YOUR_API_KEY", "Content-Type": "application/x-www-form-urlencoded", }, body: new URLSearchParams({ grant_type: "Password", SiteCode: "YOUR_SITE_CODE", }), }); const data = await response.json(); ``` **Python** ```python import requests response = requests.post( "https://api.ozow.com/token", headers={"ApiKey": "YOUR_API_KEY"}, data={"grant_type": "Password", "SiteCode": "YOUR_SITE_CODE"}, ) data = response.json() ``` **Successful response** ```json { "access_token": "YOUR_ACCESS_TOKEN", "token_type": "Bearer", "expires_in": "14400" } ``` Store the `access_token` and request a new one before it expires. Include it in the `Authorization` header of every refund request: ```http Authorization: Bearer YOUR_ACCESS_TOKEN ``` --- ## Step 2: Generate the hash check Each refund item in the batch requires its own SHA512 hash check. > ⚠️ **Critical, field order matters**: Concatenate the fields in exactly the order shown below. > Using the wrong order results in a hash check failure and the refund is rejected. **Hash field concatenation order** | Position | Field | |---|---| | 1 | `transactionId` | | 2 | `amount`, formatted with two decimal places, for example `100.00` | | 3 | `refundReason` | | 4 | `notifyUrl` | **Steps** 1. Concatenate the fields above in order 2. Append your private key to the concatenated string 3. Generate a SHA512 hash of the result and send the digest as lowercase hexadecimal **C#** ```csharp using System.Security.Cryptography; using System.Text; var transactionId = "00000000-0000-0000-0000-000000000000"; var amount = "50.00"; var refundReason = "Order cancellation"; var notifyUrl = "https://yourstore.com/notify"; var privateKey = "YOUR_PRIVATE_KEY"; var inputString = string.Concat(transactionId, amount, refundReason, notifyUrl, privateKey); using SHA512 sha = SHA512.Create(); var bytes = sha.ComputeHash(Encoding.UTF8.GetBytes(inputString)); var hashCheck = string.Concat(bytes.Select(b => b.ToString("x2"))); Console.WriteLine($"hashCheck: {hashCheck}"); ``` **PHP** ```php ``` **JavaScript** ```javascript const crypto = require("crypto"); const inputString = transactionId + amount + refundReason + notifyUrl + privateKey; const hashCheck = crypto.createHash("sha512").update(inputString).digest("hex"); console.log("hashCheck:", hashCheck); ``` **Python** ```python import hashlib input_string = transaction_id + amount + refund_reason + notify_url + private_key hash_check = hashlib.sha512(input_string.encode()).hexdigest() print("hashCheck:", hash_check) ``` --- ## Step 3: Submit the refund request ```endpoint POST https://api.ozow.com/secure/refunds/submit Authorization: Bearer YOUR_ACCESS_TOKEN Accept: application/json Content-Type: application/json ``` Submit every refund you want to process in a single request, as an array. Each item includes its own hash check from Step 2. **Request example** ```json [ { "transactionId": "00000000-0000-0000-0000-000000000000", "amount": 50.00, "refundReason": "Order cancellation", "notifyUrl": "https://yourstore.com/notify", "hashCheck": "YOUR_GENERATED_HASH" }, { "transactionId": "00000000-0000-0000-0000-000000000001", "amount": 100.00, "refundReason": "Duplicate charge", "notifyUrl": "https://yourstore.com/notify", "hashCheck": "YOUR_GENERATED_HASH" } ] ``` **Request fields** | Field | Type | Required | Description | |---|---|---|---| | `transactionId` | string | Yes | The Ozow transaction ID of the original payment | | `amount` | number | Yes | Amount to refund. Must not exceed the original transaction amount | | `refundReason` | string | No | Reason for the refund | | `notifyUrl` | string | No | URL Ozow posts the refund notification to | | `isRtc` | boolean | No | Whether the refund is processed as an RTC refund. Defaults to `false` | | `hashCheck` | string | Yes | SHA512 hash generated in Step 2 | For the full field reference see [Submit refund](https://hub.ozow.com/api-reference/payments-api/post-secure-refunds-submit.md). **Successful response** ```json [ { "refundId": "00000000-0000-0000-0000-000000000000", "transactionId": "00000000-0000-0000-0000-000000000000", "refundAmount": "50.00", "errors": null }, { "refundId": null, "transactionId": "00000000-0000-0000-0000-000000000001", "refundAmount": "100.00", "errors": ["Hash check invalid"] } ] ``` > ℹ️ **Note**: The API returns a response for each refund item in the array. Check the `errors` > field for each item, a `null` value means the refund was accepted. A non-null value means the > refund was rejected and includes the reason. Store the `refundId` for each accepted refund, you can use it to check the status later. --- ## Step 4: Handle the notification Ozow sends a notification to your `notifyUrl` when a refund either completes or fails. **Notification fields** | Field | Description | |---|---| | `refundId` | The refund identifier | | `transactionId` | The transaction identifier of the payment that was refunded | | `currencyCode` | The refund currency | | `amount` | The refund amount | | `status` | The refund status. See [Notification statuses](#notification-statuses) | | `bankName` | The name of the bank the refund was paid to | | `accountNumber` | The masked account number the refund was paid to | | `statusMessage` | Message about the refund status. Not always present | | `isRtc` | Whether RTC was used to pay the refund | | `hash` | SHA512 hash used to verify the notification | **Verifying the notification hash** 1. Concatenate the fields in this order: `refundId`, `transactionId`, `currencyCode`, `amount`, `status`, `bankName`, `accountNumber`, `statusMessage`, excluding `isRtc` and `hash` 2. Append your private key 3. Lowercase the entire string 4. Generate a SHA512 hash and compare it to the `hash` field received > ⚠️ **Important**: Always verify the notification hash before updating your records. Never update > refund status without first verifying the hash. --- ## Refund statuses Two different endpoints represent refund status differently. ### Refund resource status Returned by `getrefund`, `getrefunds`, and `getrefundsbytransactionid`: | Status | Description | |---|---| | `0` | Pending, the refund request has been submitted and accepted | | `1` | Complete, the refund has been paid successfully | | `2` | Submitted, the refund has been assigned to a batch and is being processed | | `3` | Failed, the refund payment has failed | | `4` | Cancelled, the refund was cancelled before it was submitted | | `5` | Returned, the refund payment was returned because the destination account no longer exists | ### Notification statuses Sent in the `status` field of the `notifyUrl` notification: | Status | Description | |---|---| | `Pending` | The refund request has been submitted and accepted | | `Submitted` | The refund has been assigned to a batch and is being processed | | `Complete` | The refund has been paid successfully | | `Failed` | The refund payment has failed | | `Cancelled` | The refund was cancelled before it was submitted | | `Returned` | The refund payment was returned because the destination account no longer exists | | `PendingInvestigation` | The refund is being investigated | | `Invalid` | The refund notification could not be validated | | `Error` | The refund could not be processed due to an error | --- ## Querying refunds ### Get refund by ID ```endpoint GET https://api.ozow.com/secure/refunds/getrefund?refundId={refundId} Authorization: Bearer YOUR_ACCESS_TOKEN ``` ### Get refunds by transaction ID Retrieve every refund issued against a specific original payment transaction: ```endpoint GET https://api.ozow.com/secure/refunds/getrefundsbytransactionid?transactionId={transactionId} Authorization: Bearer YOUR_ACCESS_TOKEN ``` ### Get refunds by date and status ```endpoint GET https://api.ozow.com/secure/refunds/getrefunds?refundDate={refundDate}&status={status} Authorization: Bearer YOUR_ACCESS_TOKEN ``` **Query parameters** | Parameter | Type | Required | Description | |---|---|---|---| | `refundDate` | string | Yes | Date of refunds to return. See [Get refunds](https://hub.ozow.com/api-reference/payments-api/get-secure-refunds-getrefunds.md) for the exact accepted format | | `status` | string | Yes | Refund status code to filter by, from the [Refund resource status](#refund-resource-status) table | --- ## Next steps - Review the [Building a secure integration](https://hub.ozow.com/getting-started/building-a-secure-integration.md) checklist - See the [Payments API reference](https://hub.ozow.com/api-reference/payments-api.md) for the full refund endpoint specifications - Need to issue refunds without writing code? See [Refunds: No-code](https://hub.ozow.com/integration-methods/no-code/refunds.md) - Considering migrating to One API? See [Refunds: One API](https://hub.ozow.com/integration-methods/apis/refunds/refund-a-payment.md) --- # Refund a payment > Issue a refund with One API. Refunds are merchant-initiated backend operations with no customer-facing step, so the whole flow is in your backend. Source: https://hub.ozow.com/integration-methods/apis/refunds/refund-a-payment/ This guide walks you through issuing refunds to your customers using One API. Refunds are merchant-initiated backend operations, there is no customer-facing step. The entire flow happens in your backend. > ℹ️ This guide uses the **One API**: Ozow's recommended API for all new integrations. > Already integrated? If your integration posts to `api.ozow.com` and builds a SHA512 hash, you're > on the Payments API: see [Refund a payment](https://hub.ozow.com/integration-methods/apis/deprecated-integrations/refund-a-payment.md) under > Legacy integrations, or [Migrating to One API](https://hub.ozow.com/integration-methods/apis/deprecated-integrations/migrating-to-one-api.md). > ℹ️ **Float required**: Ozow uses your float balance to fund refunds. Make sure your float has > sufficient funds before issuing refunds. See the [Float top-up > guide](https://hub.ozow.com/payment-products/settlements-and-float/float-top-up.md) to load funds into your > float. ## Before you start - You have a valid One API access token: see [Step 1: Obtain an access token](https://hub.ozow.com/integration-methods/apis/payin/redirect-to-ozow.md#step-1-obtain-an-access-token) for the token flow - Your One API client must have the `refunds` scope, and your token must request it. A token issued for `payments` alone is refused by every endpoint on this page - Your float balance is sufficient to cover the refund amount - You have the transaction ID of the original payment you want to refund ## Environments | Environment | Base URL | Dashboard | |---|---|---| | Production | `https://one.ozow.com/v1` | [dash.ozow.com](https://dash.ozow.com) | | Staging | `https://stagingone.ozow.com/v1` | [stagingdash.ozow.com](https://stagingdash.ozow.com) | --- ## How refunds work You can request a refund two ways: against a specific transaction, or as a batch of one or more refunds in a single call. Both create the same kind of refund resource and follow the same lifecycle. ```mermaid sequenceDiagram participant M as Your system participant O as One API participant B as Customer bank account M->>O: POST /transactions/{id}/refunds or POST /refunds O-->>M: Returns the refund resource with status pending O->>B: Processes the refund to the original bank account O-->>M: Sends a refund.complete webhook M->>M: Verifies the webhook signature M->>M: Updates the refund status ``` --- ## Refund a single transaction Use this to refund a specific payment. You can issue a full refund or a partial refund by specifying the amount. ```endpoint POST https://one.ozow.com/v1/transactions/{id}/refunds Authorization: Bearer YOUR_ACCESS_TOKEN Idempotency-Key: YOUR_UNIQUE_KEY Content-Type: application/json ``` Replace `{id}` with the transaction ID of the original payment. > ℹ️ **Idempotency key**: Include a unique `Idempotency-Key` header with every refund request. If a > request fails and you retry, using the same idempotency key prevents the refund from being > processed twice. **cURL** ```bash curl -X POST "https://one.ozow.com/v1/transactions/497f6eca-6276-4993-bfeb-53cbbbba6f08/refunds" \ -H "Authorization: Bearer " \ -H "Idempotency-Key: YOUR_UNIQUE_KEY" \ -H "Content-Type: application/json" \ -d '{ "amount": { "currency": "ZAR", "value": 50.00 }, "reason": "Order cancellation", "realTimePayment": false }' ``` **C#** ```csharp var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue( "Bearer", "YOUR_ACCESS_TOKEN" ); client.DefaultRequestHeaders.Add("Idempotency-Key", "YOUR_UNIQUE_KEY"); var payload = new { amount = new { currency = "ZAR", value = 50.00 }, reason = "Order cancellation", realTimePayment = false, }; var response = await client.PostAsync( "https://one.ozow.com/v1/transactions/497f6eca-6276-4993-bfeb-53cbbbba6f08/refunds", new StringContent(JsonSerializer.Serialize(payload), Encoding.UTF8, "application/json") ); var result = await response.Content.ReadAsStringAsync(); ``` **PHP** ```php "https://one.ozow.com/v1/transactions/497f6eca-6276-4993-bfeb-53cbbbba6f08/refunds", CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode([ "amount" => ["currency" => "ZAR", "value" => 50.00], "reason" => "Order cancellation", "realTimePayment" => false, ]), CURLOPT_HTTPHEADER => [ "Authorization: Bearer YOUR_ACCESS_TOKEN", "Idempotency-Key: YOUR_UNIQUE_KEY", "Content-Type: application/json", ], ]); $response = curl_exec($curl); curl_close($curl); echo $response; ?> ``` **JavaScript** ```javascript const response = await fetch( "https://one.ozow.com/v1/transactions/497f6eca-6276-4993-bfeb-53cbbbba6f08/refunds", { method: "POST", headers: { "Authorization": "Bearer YOUR_ACCESS_TOKEN", "Idempotency-Key": "YOUR_UNIQUE_KEY", "Content-Type": "application/json", }, body: JSON.stringify({ amount: { currency: "ZAR", value: 50.00 }, reason: "Order cancellation", realTimePayment: false, }), }, ); const data = await response.json(); ``` **Python** ```python import requests response = requests.post( "https://one.ozow.com/v1/transactions/497f6eca-6276-4993-bfeb-53cbbbba6f08/refunds", headers={ "Authorization": "Bearer YOUR_ACCESS_TOKEN", "Idempotency-Key": "YOUR_UNIQUE_KEY", "Content-Type": "application/json", }, json={ "amount": {"currency": "ZAR", "value": 50.00}, "reason": "Order cancellation", "realTimePayment": False, }, ) print(response.json()) ``` **Key request fields** | Field | Type | Required | Description | |---|---|---|---| | `amount.currency` | string | Yes | Must be `ZAR` | | `amount.value` | number | Yes | Amount to refund. Must not exceed the original transaction amount | | `reason` | string | Yes | Reason for the refund | | `realTimePayment` | boolean | Yes | Whether the refund pays out in real time. See [Ozow Pricing](https://ozow.com/pricing) for the cost of real-time refunds. Defaults to `false` | | `notifyUrl` | string | No | URL to notify of the refund status. Use webhooks instead: see [Handling the refund outcome](#handling-the-refund-outcome) | For the full list of request fields see [Request Refund](https://hub.ozow.com/api-reference/one-api/post-transactions-id-refunds.md). **Successful response** ```json { "links": { "self": "https://one.ozow.com/v1/refunds/6ba7b810-9dad-11d1-80b4-00c04fd430c8", "cancel": "https://one.ozow.com/v1/refunds/6ba7b810-9dad-11d1-80b4-00c04fd430c8/cancel" }, "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "transactionId": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "amount": { "currency": "ZAR", "value": 50.00 }, "requested": "2026-01-01T00:00:00Z", "status": "Pending", "reason": "Order cancellation", "realTimePayment": false } ``` Store the refund `id`, you can use it to check the status of the refund. To see the refunds already requested against a transaction, `GET` the same endpoint: ```endpoint GET https://one.ozow.com/v1/transactions/{id}/refunds Authorization: Bearer YOUR_ACCESS_TOKEN ``` --- ## Refund multiple transactions in one request `POST /refunds` submits a batch of refund requests, each against its own transaction. Use this when you need to issue several refunds at once; for a single refund it is simpler to use the transaction endpoint above. ```endpoint POST https://one.ozow.com/v1/refunds Authorization: Bearer YOUR_ACCESS_TOKEN Idempotency-Key: YOUR_UNIQUE_KEY Content-Type: application/json ``` **Request example** ```json [ { "transactionId": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "amount": { "currency": "ZAR", "value": 50.00 }, "reason": "Order cancellation", "realTimePayment": false }, { "transactionId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "amount": { "currency": "ZAR", "value": 100.00 }, "reason": "Duplicate charge", "realTimePayment": false } ] ``` **Key request fields** | Field | Type | Required | Description | |---|---|---|---| | `transactionId` | string | Yes | The transaction ID of the payment being refunded | | `amount.currency` | string | Yes | Must be `ZAR` | | `amount.value` | number | Yes | Amount to refund. Must not exceed the original transaction amount | | `reason` | string | Yes | Reason for the refund | | `realTimePayment` | boolean | Yes | Whether the refund pays out in real time. Defaults to `false` | | `notifyUrl` | string | No | URL to notify of the refund status. Use webhooks instead | For the full list of request fields see [Request Refunds](https://hub.ozow.com/api-reference/one-api/post-refunds.md). **Successful response** Ozow returns a `Refund` resource per item submitted, in the same shape shown above. --- ## Check a refund's status ```endpoint GET https://one.ozow.com/v1/refunds/{id} Authorization: Bearer YOUR_ACCESS_TOKEN ``` Replace `{id}` with the refund ID returned when you created the refund. ## Cancel a refund Cancels the refund if it can still be cancelled. ```endpoint POST https://one.ozow.com/v1/refunds/{id}/cancel Authorization: Bearer YOUR_ACCESS_TOKEN Idempotency-Key: YOUR_UNIQUE_KEY Content-Type: application/json ``` **Request body** ```json { "reason": "Requested in error" } ``` `reason` is required. A successful cancellation returns `200 OK` with no response body. ## List refunds Retrieve a paginated list of refunds filtered by date range. ```endpoint GET https://one.ozow.com/v1/refunds?fromDate=2026-01-01T00:00:00Z&toDate=2026-01-31T23:59:59Z Authorization: Bearer YOUR_ACCESS_TOKEN ``` **Query parameters** | Parameter | Type | Required | Description | |---|---|---|---| | `fromDate` | string | Yes | Start of date range, ISO 8601 date-time | | `toDate` | string | Yes | End of date range, ISO 8601 date-time | | `limit` | integer | No | Maximum items to return. 1 to 50, defaults to 50 | | `offset` | integer | No | Number of items to skip, defaults to 0 | | `siteCode` | string | No | Filter to a single site code | **Successful response** ```json { "links": { "self": "https://one.ozow.com/v1/refunds?fromDate=2026-01-01T00:00:00Z&toDate=2026-01-31T23:59:59Z&offset=0" }, "results": [ { "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "transactionId": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "status": "Complete" } ], "meta": { "totalPages": 1, "totalItems": 1 } } ``` ## Refund statuses | Status | Description | |---|---| | `pending` | The refund request has been submitted and accepted | | `submitted` | The refund has been assigned to a batch and is being processed | | `complete` | The refund has been paid successfully | | `failed` | The refund payment has failed | | `cancelled` | The refund was cancelled before it was submitted | | `returned` | The refund payment was returned because the destination account no longer exists | --- ## Handling the refund outcome Ozow sends a `refund.complete` webhook when a refund completes. Handle it the same way as a payment webhook, verify the Svix signature before acting on it. See [Step 4: Handle the webhook notification](https://hub.ozow.com/integration-methods/apis/payin/redirect-to-ozow.md#step-4-handle-the-webhook-notification) in the One API redirect guide for the full webhook verification process. > ℹ️ **Note**: Handle duplicate refund notifications idempotently. Receiving the same notification > twice must not result in issuing a double refund. --- ## Next steps - Review the [Building a secure integration](https://hub.ozow.com/getting-started/building-a-secure-integration.md) checklist - See the [One API reference](https://hub.ozow.com/api-reference/one-api.md) for the full refund endpoint specifications - Need to issue refunds without writing code? See [Refunds: No-code](https://hub.ozow.com/integration-methods/no-code/refunds.md) --- # 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. --- # Background Context for the above. Nothing here is implemented against. --- # 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). --- # Float top-up guide > Payouts and refunds are funded from your float balance. Set up your static top-up reference once, then load funds whenever your float runs low. Source: https://hub.ozow.com/payment-products/settlements-and-float/float-top-up/ Ozow uses your float balance to fund payout transactions and refunds. Without sufficient funds in your float, payouts and refunds will fail. Before you can process any payouts or refunds, your float must have sufficient funds loaded. This guide walks you through setting up your static top-up reference and loading funds into your float. > ℹ️ **You only need to complete this setup once.** Your static top-up reference and beneficiary > details are permanent, they will not change. Once set up, all you need to do is make a payment to > Ozow using your saved beneficiary details whenever you want to top up your float. ## Before you start - You need an active Ozow merchant account with payout and/or refund access enabled - You need access to your internet banking to add Ozow as a beneficiary and make a payment ## Step 1: Log in to the Ozow Dashboard Visit [dash.ozow.com](https://dash.ozow.com) and log in to your merchant account. ## Step 2: Navigate to Float Top-ups Go to [dash.ozow.com/MerchantAdmin/Refund/ReferenceTopups](https://dash.ozow.com/MerchantAdmin/Refund/ReferenceTopups) You can also find this page by navigating to **Float** in the left-hand menu. ## Step 3: Click "Top-up Float" Click the **Top-up Float** button on the right-hand side of the page. ## Step 4: Select your top-up type You will be redirected to the top-up type selection page at [dash.ozow.com/MerchantAdmin/Refund/ReferenceTopUpTypeSelection](https://dash.ozow.com/MerchantAdmin/Refund/ReferenceTopUpTypeSelection). Select **No, Thanks** and click **Submit**. ## Step 5: Copy your static reference You will be redirected to your static top-up reference page at [dash.ozow.com/MerchantAdmin/Refund/GetStaticTopUpReference](https://dash.ozow.com/MerchantAdmin/Refund/GetStaticTopUpReference). Copy your static reference by clicking the copy icon next to it. > ⚠️ **Important**: Do not alter your static reference in any way. It must be used exactly as shown. > This reference is a unique identifier for your float in Ozow's system. ## Step 6: Add Ozow as a beneficiary in your internet banking Log in to your internet banking and add Ozow as a beneficiary using the banking details shown on the static reference page in Step 5. Save your static reference against the beneficiary details in your internet banking. > ⚠️ **Important**: Save your static reference against the beneficiary details in your internet > banking. You must use this exact reference every time you top up. Do not change it. > ⚠️ **Security warning**: Only use the banking details shown on your Ozow Dashboard. Never use > banking details shared by a third party or found outside of your official Ozow Dashboard. ## Step 7: Make a payment Once you have added Ozow as a beneficiary, make a payment for the amount you want to load into your float. Enter the desired top-up amount when making the payment. Once Ozow receives your payment, the system will automatically assign the value to your float. You can confirm your updated float balance at [dash.ozow.com/MerchantAdmin/Refund/ReferenceTopups](https://dash.ozow.com/MerchantAdmin/Refund/ReferenceTopups). > ℹ️ **Plan ahead**: Given the 1-2 business day processing time, we recommend topping up your float > before it runs low rather than waiting until funds are depleted. Your low float balance alert will > help you stay ahead of this. ## Low float balance alerts As part of your payout and/or refund integration setup, Ozow will configure a low float balance email alert for your account. This alert notifies you automatically when your float balance drops below a threshold agreed on during setup, giving you time to top up before payouts or refunds start failing. You do not need to set this up yourself, Ozow configures it as part of your integration. If you want to adjust your alert threshold at any time, contact [support@ozow.com](mailto:support@ozow.com) or your account manager. ## Topping up in future You never need to repeat the setup process above. Your beneficiary details and static reference are permanent. Whenever you want to top up your float: 1. Log in to your internet banking 2. Make a payment to the Ozow beneficiary you saved in Step 6 3. Enter the desired top-up amount 4. Your float will be updated automatically once the payment is received ## Support If you have any questions about your float or need assistance with the top-up process, contact [support@ozow.com](mailto:support@ozow.com) or reach out to your account manager. --- # 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. --- # The contract The operations those pages declare, as the specification defines them. --- # List Refunds > GET `/refunds` > Part of the One API reference. Source: https://hub.ozow.com/api-reference/one-api/get-refunds/ Server: `https://one.ozow.com/v1` (Production) Other environments: `https://stagingone.ozow.com/v1` (Staging) Retrieve a list of refunds performed. ## Authentication - `Authentication` (oauth2) - Scopes: `refunds` ## 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. - `siteCode` (string) - The merchant site code. ## 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. - `links` (object) - Links used for pagination. - `results` (array of Refund) - The list of refunds. - `meta` (object) - The pagination meta data available. ### 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 } ``` ### 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 Refund > GET `/refunds/{id}` > Part of the One API reference. Source: https://hub.ozow.com/api-reference/one-api/get-refunds-id/ Server: `https://one.ozow.com/v1` (Production) Other environments: `https://stagingone.ozow.com/v1` (Staging) Retrieve a refund by its unique identifier. ## Authentication - `Authentication` (oauth2) - Scopes: `refunds` ## Path parameters - `id` (string, required) - The refund identifier. ## 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. - `links` (object, required) - Links related to this resource. - `self` (string, uri, required) - The unique URI to this resource. - `cancel` (string) - `id` (string, uuid, required) - The unique identifier for this refund. - `transactionId` (string, uuid, required) - The transactions identifier of the payment that is being refunded. - `amount` (object, required) - The refund amount. - `requested` (string, date-time, required) - The date and time the refund was requested. - `completed` (string, date-time) - The date and time the refund was completed. - `status` (any, required, one of "Pending", "Complete", "Submitted", "Failed", "Cancelled", "Returned") - The refund status. Possible values are: * Pending - The refund request has been submitted and accepted. * Complete - The refund has been paid successfully. * Submitted - The refund has been assigned to a batch and is being processed. * Failed - The refund payment has failed. * Cancelled - The refund has been cancelled before it was submitted. * Returned - The refund payment has been returned because the account that was being refunded no longer exists. - `reason` (string) - The reason for the status of the refund. - `paidTo` (object) - The bank details of where the refund was paid to. - `realTimePayment` (boolean, required, default false) - Whether or not this payment should happen in real time. Please refer to the [Ozow Pricing](https://ozow.com/pricing) page for more information. ### 401 Unauthorised. - 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 (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 } ``` ### 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" } } ``` --- # Get Refunds > GET `/transactions/{id}/refunds` > Part of the One API reference. Source: https://hub.ozow.com/api-reference/one-api/get-transactions-id-refunds/ Server: `https://one.ozow.com/v1` (Production) Other environments: `https://stagingone.ozow.com/v1` (Staging) Get the refunds requested against this payment. ## Authentication - `Authentication` (oauth2) - Scopes: `refunds` ## Path parameters - `id` (string, required) - The unique identifier of the transaction. ## 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-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) - Links used for pagination. - `results` (array of Refund) - The list of refunds. - `meta` (object) - The pagination meta data available. ### 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 } ``` ### 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" } } ``` --- # 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" } } ``` --- # Request Refunds > POST `/refunds` > Part of the One API reference. Source: https://hub.ozow.com/api-reference/one-api/post-refunds/ Server: `https://one.ozow.com/v1` (Production) Other environments: `https://stagingone.ozow.com/v1` (Staging) Request refunds for the specified transactions. ## Authentication - `Authentication` (oauth2) - Scopes: `refunds` ## 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 array of RefundRequest ## Responses ### 200 OK. The refund has been accepted. - Header `X-Correlation-ID`: The correlation id for the request that was processed. array of Refund ### 201 Created. The refund has been accepted. - Header `X-Correlation-ID`: The correlation id for the request that was processed. - `links` (object, required) - Links related to this resource. - `self` (string, uri, required) - The unique URI to this resource. - `cancel` (string) - `id` (string, uuid, required) - The unique identifier for this refund. - `transactionId` (string, uuid, required) - The transactions identifier of the payment that is being refunded. - `amount` (object, required) - The refund amount. - `requested` (string, date-time, required) - The date and time the refund was requested. - `completed` (string, date-time) - The date and time the refund was completed. - `status` (any, required, one of "Pending", "Complete", "Submitted", "Failed", "Cancelled", "Returned") - The refund status. Possible values are: * Pending - The refund request has been submitted and accepted. * Complete - The refund has been paid successfully. * Submitted - The refund has been assigned to a batch and is being processed. * Failed - The refund payment has failed. * Cancelled - The refund has been cancelled before it was submitted. * Returned - The refund payment has been returned because the account that was being refunded no longer exists. - `reason` (string) - The reason for the status of the refund. - `paidTo` (object) - The bank details of where the refund was paid to. - `realTimePayment` (boolean, required, default false) - Whether or not this payment should happen in real time. Please refer to the [Ozow Pricing](https://ozow.com/pricing) page for more information. ### 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 Refund > POST `/refunds/{id}/cancel` > Part of the One API reference. Source: https://hub.ozow.com/api-reference/one-api/post-refunds-id-cancel/ Server: `https://one.ozow.com/v1` (Production) Other environments: `https://stagingone.ozow.com/v1` (Staging) Cancels the refund with the specified identifier if possible. ## Authentication - `Authentication` (oauth2) - Scopes: `refunds` ## Path parameters - `id` (string, required) - The refund identifier. ## 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 - `reason` (string, required) - The reason for the refund cancellation. ## Responses ### 200 OK. The refund has been cancelled. - Header `X-Correlation-ID`: The correlation id for the request that was processed. ### 201 Created. The refund has been cancelled - Header `X-Correlation-ID`: The correlation id for the request that was processed. ### 400 Bad Request - `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 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" } } ``` ### 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" } } ``` --- # Request Refund > POST `/transactions/{id}/refunds` > Part of the One API reference. Source: https://hub.ozow.com/api-reference/one-api/post-transactions-id-refunds/ Server: `https://one.ozow.com/v1` (Production) Other environments: `https://stagingone.ozow.com/v1` (Staging) Request a refund on the specified transaction. ## Authentication - `Authentication` (oauth2) - Scopes: `refunds` ## Path parameters - `id` (string, required) - The unique identifier of the transaction. ## 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 - `amount` (object, required) - The amount that needs to be refunded. This can be less than the original transaction amount but not more. Note that only up to the transaction amount can be refunded. - `reason` (string, required) - The reason for the refund. - `notifyUrl` (string, uri) - Optional notify URL to send notifications of the status of the refund. The recommendation is to use webhooks instead of this method which are configurable via the webhooks endpoints of the API. - `realTimePayment` (boolean, required, default false) - Whether or not this payment should happen in real time. Please refer to the [Ozow Pricing](https://ozow.com/pricing) page for more information. ## Responses ### 200 OK. The refund has been accepted. - Header `X-Correlation-ID`: The correlation id for the request that was processed. - `links` (object, required) - Links related to this resource. - `self` (string, uri, required) - The unique URI to this resource. - `cancel` (string) - `id` (string, uuid, required) - The unique identifier for this refund. - `transactionId` (string, uuid, required) - The transactions identifier of the payment that is being refunded. - `amount` (object, required) - The refund amount. - `requested` (string, date-time, required) - The date and time the refund was requested. - `completed` (string, date-time) - The date and time the refund was completed. - `status` (any, required, one of "Pending", "Complete", "Submitted", "Failed", "Cancelled", "Returned") - The refund status. Possible values are: * Pending - The refund request has been submitted and accepted. * Complete - The refund has been paid successfully. * Submitted - The refund has been assigned to a batch and is being processed. * Failed - The refund payment has failed. * Cancelled - The refund has been cancelled before it was submitted. * Returned - The refund payment has been returned because the account that was being refunded no longer exists. - `reason` (string) - The reason for the status of the refund. - `paidTo` (object) - The bank details of where the refund was paid to. - `realTimePayment` (boolean, required, default false) - Whether or not this payment should happen in real time. Please refer to the [Ozow Pricing](https://ozow.com/pricing) page for more information. ### 201 Created. The refund has been accepted. - Header `X-Correlation-ID`: The correlation id for the request that was processed. - Header `Location`: The unique URI of the created resource. `Refund`, the same schema listed in full earlier in this document. Its own page: https://hub.ozow.com/api-reference/one-api/schemas/refund.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" } } ``` ### 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" } } ``` ### 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" } } ``` --- # 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` --- # Webhooks management > A group of operations in the One API reference. Source: https://hub.ozow.com/api-reference/one-api/tags/webhooks/ Subscribe to events, and replay one your server missed. ## Operations - `GET /webhooks` - List Webhook Subscriptions - `POST /webhooks` - Create Webhook Subscription - `GET /webhooks/{id}` - Get Webhook Subscription - `PUT /webhooks/{id}` - Update Webhook Subscription - `DELETE /webhooks/{id}` - Delete Webhook Subscription - `POST /webhooks/{id}/replay` - Replay Failed Messages - `GET /webhooks/{id}/secret` - Get Webhook Secret --- # Refund 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/refund-complete/ Raised when a refund reaches a final state. `status` is `Pending`, `Failed`, `Complete`, `Submitted`, `Cancelled`, `Returned` or `Invalid`. `Pending` covers a refund under investigation, and `Failed` covers both a failure and an error. A subscription registered as `full` receives `RefundCompleteFullData` in `data` instead, and its `Status` is the refund's own, unmapped: `PendingInvestigation` and `Error` arrive as themselves rather than as `Pending` and `Failed`. 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. --- # 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. --- # Get refund > GET `/secure/refunds/getrefund` > Part of the Payments API reference. Source: https://hub.ozow.com/api-reference/payments-api/get-secure-refunds-getrefund/ Server: `https://api.ozow.com` (Production) Other environments: `https://stagingapi.ozow.com` (Staging) Query a refund using the Ozow refund identifier. ## Authentication - `BearerToken` (HTTP bearer) - The token generated by the `Get API token` operation. The same token is used for every request until it expires. ## Query parameters - `refundId` (string, required) - Ozow's identifier for the refund. This identifier is passed back to the merchant in the SubmitRefunds response’s RefundId field. ## Responses ### 200 OK **application/json** - `id` (string, uuid, required) - The identifier for the refund. - `createdDate` (string, date-time, required) - The date the refund was created. - `createdDateUtc` (string, date-time, required) - The UTC date the refund was created. - `merchantCode` (string, required) - Corresponding merchant code of the refund. - `siteCode` (string, required) - Corresponding site code of the refund. - `siteName` (string, required) - Corresponding site name of the refund. - `bankToName` (string, required) - Bank the refund was sent to. - `currencyCode` (string, required, max length 3) - Refund currency. - `amount` (number, double, required) - Refund amount. - `statementReference` (string, required) - Bank reference of the refund for the payer. - `status` (integer, required) - Refund status. Possible values are: * 0 - Pending - The refund request has been submitted and accepted. * 1 - Complete - The refund has been paid successfully. * 2 - Submitted - The refund has been assigned to a batch and is being processed. * 3 - Failed - The refund payment has failed. * 4 - Cancelled - The refund has been cancelled before it was submitted. * 5 - Returned - The refund payment has been returned because the account that was being refunded no longer exists. - `toAccount` (string, required) - Account number refund was sent to. - `paymentDate` (string, date-time, required) - Payment date of the refund. - `transactionReference` (string, required) - Reference of the transaction which was refunded. - `customer` (string) - Refunded transaction customer. - `lastEvent` (string, required) - Most recent log activity of the refund. - `refundCompletedDate` (string, date-time) - The date the refund was completed. - `createdBy` (string, required) - Name of the user who created the refund. - `isRtc` (boolean, required) - `True` if the refund was paid via RTC. **application/xml** `Refund`, the same schema listed in full earlier in this document. Its own page: https://hub.ozow.com/api-reference/payments-api/schemas/refund.md ### 400 Bad Request. The operation could not be carried out. The body is a message rather than a structured error. string Example (example 1): ```json There was an error processing your request ``` ### 401 Unauthorized. The `ApiKey` header is missing or does not match the site, or for a `Secure` operation the bearer token is missing, expired or invalid. string Example (example 1): ```json API key is missing or invalid. ``` --- # Get refunds > GET `/secure/refunds/getrefunds` > Part of the Payments API reference. Source: https://hub.ozow.com/api-reference/payments-api/get-secure-refunds-getrefunds/ Server: `https://api.ozow.com` (Production) Other environments: `https://stagingapi.ozow.com` (Staging) List refunds by date and status. ## Authentication - `BearerToken` (HTTP bearer) - The token generated by the `Get API token` operation. The same token is used for every request until it expires. ## Query parameters - `refundDate` (string, required) - The date of the refunds you would like to be returned. - `status` (string, required) - The status of the refunds you would like to be returned. ## Responses ### 200 OK **application/json** array of Refund **application/xml** array of Refund ### 400 Bad Request. The operation could not be carried out. The body is a message rather than a structured error. string Example (example 1): ```json There was an error processing your request ``` ### 401 Unauthorized. The `ApiKey` header is missing or does not match the site, or for a `Secure` operation the bearer token is missing, expired or invalid. string Example (example 1): ```json API key is missing or invalid. ``` --- # Get refunds by transaction ID > GET `/secure/refunds/getrefundsbytransactionid` > Part of the Payments API reference. Source: https://hub.ozow.com/api-reference/payments-api/get-secure-refunds-getrefundsbytransactionid/ Server: `https://api.ozow.com` (Production) Other environments: `https://stagingapi.ozow.com` (Staging) Retrieves all refunds linked to a specific Ozow transaction. ## Authentication - `BearerToken` (HTTP bearer) - The token generated by the `Get API token` operation. The same token is used for every request until it expires. ## Query parameters - `transactionId` (string, required) - Ozow's identifier for original payment transaction. This is passed back to the merchant in the payment redirect and notification response’s TransactionId field. ## Responses ### 200 OK **application/json** array of Refund **application/xml** array of Refund ### 400 Bad Request. The operation could not be carried out. The body is a message rather than a structured error. string Example (example 1): ```json There was an error processing your request ``` ### 401 Unauthorized. The `ApiKey` header is missing or does not match the site, or for a `Secure` operation the bearer token is missing, expired or invalid. string Example (example 1): ```json API key is missing or invalid. ``` --- # Create Payment Request > POST `/postpaymentrequest` > Part of the Payments API reference. Source: https://hub.ozow.com/api-reference/payments-api/post-post-payment-request/ Server: `https://api.ozow.com` (Production) Other environments: `https://stagingapi.ozow.com` (Staging) Creates a payment request with the requested parameter set. ## Authentication - `ApiKey` (API key in the ApiKey header) - The unique API key for the merchant. See [Prerequisites and onboarding](../../getting-started/prerequisites-and-onboarding.md) for where to find it. ## Request body **application/json** - `siteCode` (string, required, max length 50) - A unique code for the site currently in use. A site code is generated when adding a site in the Ozow merchant admin section. - `countryCode` (string, required, max length 2, pattern ^[A-Z]+) - The ISO 3166-1 alpha-2 code for the user's country. The country code will determine which banks will be displayed to the customer. Please note only South African (ZA) banks are currently supported by Ozow. - `currencyCode` (string, required, max length 3, pattern ^[A-Z]+) - The ISO 4217 three-letter code for the transaction currency. Please note only the South African Rand (ZAR) is currently supported by Ozow, so any currency conversion must take place before posting to the Ozow site. - `amount` (number, double, required) - The transaction amount. The amount is in the currency specified by the currency code posted. - `transactionReference` (string, required, max length 50) - The merchant's reference for the transaction. This reference can be used to look up the transaction with the `GetTransactionByReference` operation. - `bankReference` (string, required, max length 20) - The reference that will be pre-populated in the "their reference" field in the customers online banking site. This is the payment reference that appears on the merchant’s bank statement and can be used for recon purposes. Only alphanumeric characters, spaces, and dashes are allowed. - `optional1` (string, max length 50) - Optional field the merchant can post for additional information they would need passed back in the response. These are also stored with the transaction details by Ozow, and can be useful for filtering transactions in the merchant admin section. - `optional2` (string, max length 50) - Optional field the merchant can post for additional information they would need passed back in the response. These are also stored with the transaction details by Ozow, and can be useful for filtering transactions in the merchant admin section. - `optional3` (string, max length 50) - Optional field the merchant can post for additional information they would need passed back in the response. These are also stored with the transaction details by Ozow, and can be useful for filtering transactions in the merchant admin section. - `optional4` (string, max length 50) - Optional field the merchant can post for additional information they would need passed back in the response. These are also stored with the transaction details by Ozow, and can be useful for filtering transactions in the merchant admin section. - `optional5` (string, max length 50) - Optional field the merchant can post for additional information they would need passed back in the response. These are also stored with the transaction details by Ozow, and can be useful for filtering transactions in the merchant admin section. - `customer` (string, max length 100) - The customer’s name or identifier. - `cancelUrl` (string, uri, max length 150) - The URL to which the redirect result should be posted to if the customer cancels the payment. This is also the page the customer will be redirected to. This URL can also be set for the applicable merchant site in the merchant admin section. If a value is set in the merchant admin and sent in the post, the posted value will be redirected to if the payment is cancelled. - `errorUrl` (string, uri, max length 150) - The URL to which the redirect result should be posted if an error occurs while trying to process the payment. This is also the page the customer will be redirected to. This URL can also be set for the applicable merchant site in the merchant admin section. If a value is set in the merchant admin and sent in the post, the posted value will be redirected to if an error occurred while processing the payment. - `successUrl` (string, uri, max length 150) - The URL to which the redirect result should be posted to if the payment is successful. This is also be the page the customer gets redirected to. This URL can also be set for the applicable merchant site in the merchant admin section. If a value is set in the merchant admin and sent in the post, the posted value will be redirected to if the payment was successful. Please note that it is not sufficient to assume that the payment was successful simply because the customer has been redirected back to this page. It is highly recommended that you check the response fields as well as the transaction status using our check transaction status API call. - `notifyUrl` (string, uri, max length 150) - The URL that the notification result should be posted to. The result will post regardless of the outcome of the transaction. This URL can also be set for the applicable merchant site in the merchant admin section. If a value is set in the merchant admin and sent in the post, the notification result will be sent to the posted value. Find out more in the notification response section in step 2. - `isTest` (boolean, required) - Accepted values are true or false. Send true to test your request posting and response handling. If set to true you will be redirected to select whether you would like a successful or unsuccessful redirect response sent back. Please note that notification responses are sent for test transactions and the online banking payment is skipped. - `selectedBankId` (string, uuid) - If the 'SelectedBankId' field is populated by the Merchant, the Customer will be redirected to the Ozow login page of the selected bank. However, if the field is left empty, the Customer will be presented with Ozow bank selection screen. See [Payment method identifiers](../../integration-methods/apis/payin/payment-method-ids.md) for the value to send. - `bankAccountNumber` (string, max length 20) - The bank account number the payment should be made to. - `branchCode` (string, max length 10) - The branch code for the bank account. - `bankAccountName` (string, max length 50, pattern ^[a-zA-Z0-9\s]+$) - The name of the beneficiary account the payment is made into. Letters, digits and spaces only. Required, along with `bankAccountNumber`, `branchCode` and `bankId`, whenever any one of them is sent. - `payeeDisplayName` (string, max length 50) - The name shown on the site as the entity being paid (not in banking screens). - `expiryDateUtc` (string, max length 19) - Payment will not be allowed to be made after this date. Date should be UTC and value should be formatted as yyyy-MM-dd HH:mm - `allowVariableAmount` (boolean) - Allows the user to change the amount passed through before paying. This option must also be enabled for the site in the merchant admin portal to be used. Accepted values are true or false. DO NOT include false in the hash check string, just ignore instead. - `variableAmountMin` (number, double) - If AllowVariableAmount is passed through as true, this will dictate the lowest acceptable amount the user can enter. - `variableAmountMax` (number, double) - If AllowVariableAmount is passed through as true, this will dictate the highest acceptable amount the user can enter. - `customerIdentifier` (string, max length 13) - Merchants classified as high-risk must provide a valid South African identity number. It's important to note that this is an optional field for all other merchants. Capitec Pay is the bank this most often applies to; see [Payment method identifiers](../../integration-methods/apis/payin/payment-method-ids.md) for what needs approval before you build against it, and reach out to [support@ozow.com](mailto:support@ozow.com) for whether your account is classified this way. - `customerCellphoneNumber` (string, max length 10, pattern ^[0-9]+) - Merchant can provide customer cellphone number for faster login on certain banks. DO NOT include in the hash check string, just ignore instead. - `hashCheck` (string, required, max length 250) - SHA512 hash used to ensure that certain fields in the message have not been altered after the hash was generated. See [Generate the hash check](../../integration-methods/apis/deprecated-integrations/redirect-to-ozow.md#step-1-generate-the-hash-check) for the field order and a worked example. **application/xml** `PaymentRequest`, the same schema listed in full earlier in this document. Its own page: https://hub.ozow.com/api-reference/payments-api/schemas/payment-request.md ## Responses ### 200 OK. The request reached the API, which is not the same as it being accepted. A rejected request is also a 200, with the reason in `errorMessage` and no `url`. Check that field, not the status code. **application/json** - `paymentRequestId` (string, uuid, required, max length 50) - Ozow's unique identifier for the payment request. - `url` (string, uri, required, max length 100) - Generated URL that allows payment for the request used to create the payment. You will need to redirect the payer to this URL, who upon completion of the payment will be redirected back to your site. **The payment Url you'll receive from the API is dynamic. Please do not hard code it into your integrations as it might change.** - `errorMessage` (string, max length 50) - Error message generated when validating the request. **application/xml** `PaymentRequestResult`, the same schema listed in full earlier in this document. Its own page: https://hub.ozow.com/api-reference/payments-api/schemas/payment-request-result.md ### 401 Unauthorized. The `ApiKey` header is missing or does not match the site, or for a `Secure` operation the bearer token is missing, expired or invalid. string Example (example 1): ```json API key is missing or invalid. ``` ### 403 Forbidden. The credentials were readable but the site cannot be authorised, because no merchant matches the site code or the merchant is deactivated. string Example (example 1): ```json Merchant for site code TSTSTE0001 is deactivated ``` ### 500 Internal Server Error. Something failed on the Ozow side. string --- # Submit refund > POST `/secure/refunds/submit` > Part of the Payments API reference. Source: https://hub.ozow.com/api-reference/payments-api/post-secure-refunds-submit/ Server: `https://api.ozow.com` (Production) Other environments: `https://stagingapi.ozow.com` (Staging) Submit refunds to Ozow for processing. ## Authentication - `BearerToken` (HTTP bearer) - The token generated by the `Get API token` operation. The same token is used for every request until it expires. ## Request body An array of refund requests. **application/json** array of RefundRequest **application/x-www-form-urlencoded** - `transactionId` (string, uuid, required) - The transaction identifier. This is the identifier for the payment that was originally processed on Ozow. - `amount` (number, double, required) - The amount that needs to be refunded. This can be less than the original transaction amount but not more. - `refundReason` (string, max length 500) - The reason for the refund. - `notifyUrl` (string, uri, max length 500) - The URL Ozow will send a notification to once the refund has been finalised. - `hashCheck` (string, required, max length 150) - SHA512 hash proving the request has not been altered after you generated it. Concatenate four fields in this order, with no separator, then append your private key: 1. `transactionId` 2. `amount`, formatted with two decimal places, so `100.00` 3. `refundReason` 4. `notifyUrl` Hash the result with SHA512 and send the digest as lowercase hexadecimal. **Unlike the payment request hash, do not convert the concatenated string to lowercase before hashing.** Refunds hash the string exactly as you built it, so the case of your reason and your notify URL matters. Only the digest is compared case insensitively. - `isRtc` (boolean, default false) - Whether the refund should be processed as an RTC refund. ## Responses ### 200 OK **application/json** - `refundId` (string, uuid, required) - The identifier for the refund that was created. No identifier is returned if there was an error creating the refunds. - `transactionId` (string, uuid, required) - The transaction identifier. This will correspond to one of the transaction identifiers passed through in the request. - `refundAmount` (string, required) - The refund amount. - `errors` (array of string) - Validation errors for the specific refund. **application/xml** `RefundResponse`, the same schema listed in full earlier in this document. Its own page: https://hub.ozow.com/api-reference/payments-api/schemas/refund-response.md ### 400 Bad Request. The operation could not be carried out. The body is a message rather than a structured error. string Example (example 1): ```json There was an error processing your request ``` ### 401 Unauthorized. The `ApiKey` header is missing or does not match the site, or for a `Secure` operation the bearer token is missing, expired or invalid. string Example (example 1): ```json API key is missing or invalid. ``` --- # Get API token > POST `/token` > Part of the Payments API reference. Source: https://hub.ozow.com/api-reference/payments-api/post-token/ Server: `https://api.ozow.com` (Production) Other environments: `https://stagingapi.ozow.com` (Staging) All requests are authenticated using the token you will receive from this request. The same token can be used for all requests until it expires. The only content type supported by this operation is "application/x-www-form-urlencoded". ## Authentication - `ApiKey` (API key in the ApiKey header) - The unique API key for the merchant. See [Prerequisites and onboarding](../../getting-started/prerequisites-and-onboarding.md) for where to find it. ## Request body - `grant_type` (string, required, max length 50) - Set as "Password". - `SiteCode` (string, required, max length 50) - The Ozow site code for the site which the payment is being made to. [Please contact support for SiteCode - support@ozow.com] ## Responses ### 200 OK **application/json** - `access_token` (string, required, max length 500) - The token needed for subsequent requests. - `token_type` (string, required, max length 50) - The token type. - `expires_in` (string, required, max length 50) - The lifetime of the token in seconds. **application/xml** `Token`, the same schema listed in full earlier in this document. Its own page: https://hub.ozow.com/api-reference/payments-api/schemas/token.md ### 401 Unauthorized. The `ApiKey` header is missing or does not match the site, or for a `Secure` operation the bearer token is missing, expired or invalid. string Example (example 1): ```json API key is missing or invalid. ``` --- # Refund notification > POST to your notification URL > Sent by Ozow. Part of the Payments API reference. Source: https://hub.ozow.com/api-reference/payments-api/webhooks/refund-notification/ Sent to the notification URL given on the refund request, once the refund has either completed or failed. Verify the `hash` field before acting on the contents. Concatenate the notification fields in the order they appear, excluding `isRtc` and `hash`, append your private key, lowercase the result, and compare a SHA512 of it against the value received. ## 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 Hash field before acting on the contents: your notification URL is public, and anyone can post to it. ## Payload **application/x-www-form-urlencoded** - `RefundId` (string, uuid, required) - The refund identifier. - `TransactionId` (string, uuid, required) - The transaction identifier of the transaction that is being refunded. - `CurrencyCode` (string, required, max length 3) - The refund currency. Will always be the same as the amount in the transaction. - `Amount` (number, double, required) - The refund amount, in the currency the currency code names. Written with two decimal places, which is the form the hash is built from. - `IsRtc` (string, required) - An indication of whether RTC was used to pay the refund. - `Status` (string, required, one of "Pending", "Submitted", "Complete", "Failed", "Cancelled", "Returned", "PendingInvestigation", "Invalid", "Error") - The refund status. Sent as the name, not as a number, because the notification is form encoded and the status is written out in full. - `BankName` (string, required, max length 50) - The name of the bank the refund was paid to. - `AccountNumber` (string, required, max length 50) - The masked account number payment was made to. The hash is built from the masked value, so hash what you received rather than the number you sent. - `StatusMessage` (string, max length 500) - Message regarding the status of the refund. This field will not always have a value. - `Hash` (string, required, max length 128) - SHA512 hash used to ensure that certain fields in the message have not been altered after the hash was generated. ## Your response ### 200 Acknowledged. Return this once you have stored the notification. No body.