Migrating to One API

This guide maps a redirectRedirect Sending the payer to the Ozow payment page to complete the payment, and returning them to your site afterwards. The alternative is embedding the checkout in your own page, where the payer never leaves it. payinPayin A payment made by a consumer to a merchant. The direction most of this site is about: money coming in. Its counterpart is a payout, which sends money out and is not tied to any payment anyone made you. 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, Refunds: Payments API, or both
• You have a Client ID and Client Secret from the One API Clients section of your Ozow Dashboard
• You can run a staging integration against One API before touching production

What does not change#

• Your site codeSite code The unique code for a site registered under a merchant. A site is a place to transact: a website, or a branch of a store. A merchant can have several, and each transaction names the one it belongs to, so sending the wrong code files the payment against the wrong place. stays the same
• The payment methods available to your customers, Pay by BankPay by Bank The payer authorises the payment inside their own banking app or online banking, and the funds move from their bank account. No card is involved and no card details are entered., Capitec PayCapitec Pay Capitec's own payment method. The payer gives a cellphone, account or ID number rather than card details, and approves the payment in the Capitec app, so no card number and no banking login is ever entered at checkout. It gets its own button rather than sitting inside the bank list, and it requires Customer Identity Verification.Capitec, Buy Now Pay Later, PayShap RequestPayShap Request The request side of PayShap. Rather than the payer pushing money, the payee asks for it: the payer receives a request and approves it in their own banking app, and the funds move once they do. Enabled by Ozow on request rather than by default.payshap.co.za, are the same products on both APIs
• Your floatFloat The balance held with Ozow that payouts and refunds are paid out of. Both draw on it, and neither will process while it is empty. Payins do not need one, so if you only take payments you never meet it., settlementSettlement Ozow paying the money you have collected into your bank account. Payins arrive at Ozow first and are settled to you on a schedule, so what a customer paid you today and what has been settled to you today are different amounts. schedule, and Ozow Dashboard reporting are shared across both APIs
• ZARZAR The ISO 4217 code for the South African rand, and the currency every amount on this site is in unless a page says otherwise. Amounts are decimal rand rather than cents, so 100.00 is one hundred rand. is the only supported currency on either API

What changes#

---

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:

POST https://one.ozow.com/v1/token
Content-Type: application/x-www-form-urlencoded

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:

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 for the full flow and code samples in C#, PHP, JavaScript, and Python.

---

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

{
  "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

{
  "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

For the full request and response schema see Create a payment.

---

Step 3: Update how you read the response and redirect the customer#

Payments API response

{
  "paymentRequestId": "00000000-0000-0000-0000-000000000000",
  "url": "https://pay.ozow.com/00000000-0000-0000-0000-000000000000/Secure",
  "errorMessage": null
}

One API response

{
  "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.

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, select your client, and manage webhooks from there
• Via the API: see the webhook endpoints. These need a token with the webhooks scope, and so does Get Webhook Secret below. Your payin token does not reach them

Subscribe to transaction.complete 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 has the five steps and a working verifier in four languages. Retrieve your webhook secret with Get Webhook Secret.

See 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

One API transaction statuses

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.

---

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
• 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

---

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:

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 checklist, the webhook and credential handling sections apply to One API's model
• Test your migrated integration using Payin test cases
• See Redirect: One API and Refunds: One API for the complete guides
• Contact support@ozow.com if you need your One API Client ID and Client Secret issued or your webhook endpoint configured