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. money in 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 features are added to One API first.

Before you start#

• You have a working Payments API integration using Redirect to Ozow with Payments API, Refund a payment with Payments API, or both
• You have access to One API clients in the Ozow Portal, and you have created a Client ID and Client Secret
  • If you don't have access to your One API Clients, contact support@ozow.com or your account manager
  • If you need help creating your Client ID and Client Secret, see Set up your Client ID and Client Secret
• You have 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., in the format XXX-XXX-XXX. See Find your site code if you're not sure where to find it
• You can run a staging integration against One API before touching production

What does not change#

• Your site code stays the same
• The payment methods available to your customers 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 Portal 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 2: 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 Portal
• Via the API

See Step 5: Handle the webhook notification for detailed setup steps.

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.

---

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

One API and Payments API use the same underlying data, so any payment created through Payments API is also available through One API. You don't need to move or re-create existing payments when you switch, and you can look up and refund payments created on Payments API using One API.

1. Build and test the full One API flow. Before you change anything in production, test every part of your integration on One API: getting an access token, creating payments, receiving webhooks, and processing refunds if you use them.
2. Deploy One API alongside Payments API. Release your One API integration behind a feature flag or on a new code path. Don't remove your Payments API code yet.
3. Send new payments to One API. Switch new payments over to One API. Any payments already in progress on Payments API will finish on the old flow.
4. Keep your Payments API webhook handler running. A payment can still complete or time out for some time after it was created. Keep the handler live until every payment created before the switch has reached a final status.
5. Remove Payments API. Once no Payments API payments are still in progress, remove the old endpoint calls and the hash-generation code, and retire your private key. You'll still be able to look up and refund older payments through One API.

---

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 Money in test cases
• See Redirect to Ozow with One API and Refund a payment with One API for the complete guides