Hosted Checkout

This guide walks you through a Hosted Checkout integration using One API. Your system creates a payment request, redirects the customer to Ozow's secure Hosted Checkout, and receives a webhookWebhook A URL of yours that Ozow calls when something happens, rather than you polling to find out. The call carries no credential of yours and arrives at a public URL, so authenticate it before acting on it: a hash field on the Payments API, a Svix signature on One API. notification when the payment is complete.

Before you start#

• You have completed Prerequisites and onboarding
• You have access to One API clients in the Ozow Portal. If you don't have access, contact support@ozow.com or your account manager
• 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

Environments#

How redirect works#

Core integration#

Step 1: Set up your Client ID and Client Secret#

1. Open One API Clients: In the side menu, select One API, then Clients. You'll see a list of your existing API clients.

2. Add a new client: Click Add Client at the top right of the Clients page.

3. Enter the client details: Complete the form and click Submit.

• Client App Name: a name that helps you recognise the integration later, for example "Karoo Coffee Co. production".
• Allowed Scopes: choose only the scopes your integration needs, for example payments or refunds. For more information see the scope table below.
• Merchant Site (optional): limit the client to one site. Leave it blank to use the client across your merchant account.

4. Copy and store your credentials: Your Client ID and Client Secret are shown. Use the copy icons to copy both, and store them somewhere secure, such as a password manager or secrets vault, before you click Done.

Step 2: Obtain an access token#

One API uses OAuth 2.0 Client Credentials authentication. You need an access token before making any API calls.

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"

var client = new HttpClient();
var content = new FormUrlEncodedContent(
    new[]
    {
        new KeyValuePair<string, string>("client_id", "YOUR_CLIENT_ID"),
        new KeyValuePair<string, string>("client_secret", "YOUR_CLIENT_SECRET"),
        new KeyValuePair<string, string>("scope", "payments"),
        new KeyValuePair<string, string>("grant_type", "client_credentials"),
    }
);
var response = await client.PostAsync("https://one.ozow.com/v1/token", content);
var result = await response.Content.ReadAsStringAsync();

<?php
$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_URL => "https://one.ozow.com/v1/token",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => http_build_query([
        "client_id" => "YOUR_CLIENT_ID",
        "client_secret" => "YOUR_CLIENT_SECRET",
        "scope" => "payments",
        "grant_type" => "client_credentials",
    ]),
    CURLOPT_HTTPHEADER => ["Content-Type: application/x-www-form-urlencoded"],
]);
$response = curl_exec($curl);
curl_close($curl);
echo $response;
?>

const response = await fetch("https://one.ozow.com/v1/token", {
  method: "POST",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body: new URLSearchParams({
    client_id: "YOUR_CLIENT_ID",
    client_secret: "YOUR_CLIENT_SECRET",
    scope: "payments",
    grant_type: "client_credentials",
  }),
});
const data = await response.json();

import requests

response = requests.post(
    "https://one.ozow.com/v1/token",
    data={
        "client_id": "YOUR_CLIENT_ID",
        "client_secret": "YOUR_CLIENT_SECRET",
        "scope": "payments",
        "grant_type": "client_credentials",
    },
)
data = response.json()

Successful response

{
  "access_token": "mF_9.B5f-4.1JqM",
  "token_type": "Bearer",
  "expires_in": "14400",
  "scope": "payments"
}

Store the access_token and include it in the Authorization header of all subsequent requests:

Authorization: Bearer YOUR_ACCESS_TOKEN

Tokens expire after the number of seconds in expires_in, which is 14400, four hours. Read that field rather than hard coding the number: a change to the lifetime reaches you in the response before it reaches this page. If authentication fails, the API returns 401 Unauthorized.

Step 3: Create a payment request#

Create a payment request for your customer's order.

POST https://one.ozow.com/v1/payments
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

curl -X POST "https://one.ozow.com/v1/payments" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "siteCode": "YOUR_SITE_CODE",
    "amount": {
      "currency": "ZAR",
      "value": 100.00
    },
    "merchantReference": "ORDER-001",
    "beneficiaryReference": "ONLINESHOP002",
    "expireAt": "2026-12-31T23:59:59Z",
    "returnUrl": "https://yourstore.com/order-complete"
  }'

var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue(
    "Bearer",
    "YOUR_ACCESS_TOKEN"
);

var payload = new
{
    siteCode = "YOUR_SITE_CODE",
    amount = new { currency = "ZAR", value = 100.00 },
    merchantReference = "ORDER-001",
    beneficiaryReference = "ONLINESHOP002",
    expireAt = "2026-12-31T23:59:59Z",
    returnUrl = "https://yourstore.com/order-complete",
};

var response = await client.PostAsync(
    "https://one.ozow.com/v1/payments",
    new StringContent(JsonSerializer.Serialize(payload), Encoding.UTF8, "application/json")
);
var result = await response.Content.ReadAsStringAsync();

<?php
$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_URL => "https://one.ozow.com/v1/payments",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode([
        "siteCode" => "YOUR_SITE_CODE",
        "amount" => ["currency" => "ZAR", "value" => 100.00],
        "merchantReference" => "ORDER-001",
        "beneficiaryReference" => "ONLINESHOP002",
        "expireAt" => "2026-12-31T23:59:59Z",
        "returnUrl" => "https://yourstore.com/order-complete",
    ]),
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer YOUR_ACCESS_TOKEN",
        "Content-Type: application/json",
    ],
]);
$response = curl_exec($curl);
curl_close($curl);
echo $response;
?>

const response = await fetch("https://one.ozow.com/v1/payments", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    siteCode: "YOUR_SITE_CODE",
    amount: { currency: "ZAR", value: 100.00 },
    merchantReference: "ORDER-001",
    beneficiaryReference: "ONLINESHOP002",
    expireAt: "2026-12-31T23:59:59Z",
    returnUrl: "https://yourstore.com/order-complete",
  }),
});
const data = await response.json();

import requests

response = requests.post(
    "https://one.ozow.com/v1/payments",
    headers={
        "Authorization": "Bearer YOUR_ACCESS_TOKEN",
        "Content-Type": "application/json",
    },
    json={
        "siteCode": "YOUR_SITE_CODE",
        "amount": {"currency": "ZAR", "value": 100.00},
        "merchantReference": "ORDER-001",
        "beneficiaryReference": "ONLINESHOP002",
        "expireAt": "2026-12-31T23:59:59Z",
        "returnUrl": "https://yourstore.com/order-complete",
    },
)
data = response.json()

Key request fields

For the full list of request fields see Create a payment.

Successful 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"
}

Step 4: Redirect the customer#

Redirect your customer's browser to the redirectUrl from the response. Ozow displays the payment page where the customer selects their preferred payment method and completes the payment.

Send them to the URL you were given, and do not build one. Its shape is Ozow's to change, and a URL assembled from the payment id is a URL that stops working without notice.

status on the response is Created. Compare it without case.

Once the customer completes or cancels the payment, Ozow redirects them back to your returnUrl.

Step 5: Handle the webhook notification#

Ozow sends a webhook notification to your endpoint when a transaction completes. One API uses Svix to deliver webhooks.

There are two ways to be told, and you choose them independently.

Webhooks are the recommended path. notifyUrl is optional and exists so that an integration already handling the Payments API notification keeps working: point it at your existing handler and the payload and hash are the ones it already verifies.

If you set neither, nothing is delivered and you must poll Get Transactions instead, which is slower and which Step 6 covers.

Setting up your webhook endpoint

Set up your webhook endpoint in one of two ways:

Option 1: Via the Ozow Portal

1. Open the client's webhooks: Go to One API > Clients. Find the client you want notifications for and click Manage Webhooks in its row.

2. Add a webhook: On the Webhooks page, click Add Webhook. If the client has no webhooks yet, you'll see "No Webhooks Setup".

3. Enter the webhook details: Complete the form and click Submit.

   • Message Type: how much detail each notification contains.
   • Event Type: the event that triggers the notification.
   • Endpoint: the HTTPS URL on your server that will receive the notifications.

4. Your new webhook appears in the list on the Webhooks page. Add a separate webhook for each event type you want to receive.

Option 2: Via the API: List Webhook Subscriptions to see what you already have, then Create Webhook Subscription for what you do not

Available webhook events

Subscribe to the name exactly as written. An event name the service does not know is rejected, so a subscription to something close is a subscription that never fires.

Message types

When setting up your webhook subscription you can choose how much data is included in each notification:

Choose full if you need transaction details in the webhook payload. Choose thin if you only need the status and will query the API for details separately.

What arrives

Every delivery has the same envelope. data is WebhookEventData when the subscription asked for thin, TransactionCompleteFullData for a full subscription to transaction.complete, and RefundCompleteFullData for a full subscription to refund.complete. Every value in a full payload is a string, the amount and the flags included.

{
  "type": "transaction.complete",
  "timestamp": "2026-03-14T09:30:00Z",
  "data": {
    "id": "00000000-0000-0000-0000-000000000000",
    "status": "Successful",
    "reason": null
  }
}

id is the transaction, refund or subscription the event is about. reason carries the status message and is null when there is nothing to say.

The status values for transaction.complete

These are not the transaction statuses on the statuses page: the webhook maps them down to four.

A cancelled payment arrives as Error, not as Cancelled. reason tells you which it was. Switch on these four and read reason for the detail; do not expect the status names the transaction itself carries.

For refund.complete, status is Pending, Failed, Complete, Submitted, Cancelled, Returned or Invalid. Those are the thin values. A full subscription carries the refund's own status in Status, unmapped, so PendingInvestigation and Error arrive as themselves rather than as Pending and Failed. Handle both if you are on full.

Verifying the webhook signature

Every webhook notification includes Svix signature headers. You must verify the signature before acting on any notification.

Verify a webhook signature has the five steps of the check and a working verifier in csharp, php, python and javascript, with or without the Svix library. To retrieve the secret for your webhook, use Get Webhook Secret.

Step 6: Confirm the transaction outcome#

After verifying the webhook, check the transaction status and update your order.

You can also check transaction status directly via the API at any time:

GET https://one.ozow.com/v1/payments/{id}/transactions
Authorization: Bearer YOUR_ACCESS_TOKEN

Replace {id} with the payment ID returned in Step 2. fromDate and toDate are required query parameters. See Get Transactions for details.

See statuses for what each returned transaction status means.

Step 7: Cancel a payment#

If your customer abandons checkout or you need to cancel an order before the customer completes payment, you can cancel the payment request using the cancel link returned in the payment response.

POST https://one.ozow.com/v1/payments/{id}/cancel
Authorization: Bearer YOUR_ACCESS_TOKEN

A successfully cancelled payment will no longer be accessible to the customer via the redirectUrl. If the customer attempts to use the link after cancellation they will see an error.

Optional features#

Standalone button#

A standalone button lets you surface a specific Ozow payment method as a dedicated button on your checkout page. Instead of showing a generic payment page where the customer selects their payment method, a standalone button takes the customer directly to a specific payment method; for example Capitec Pay, Buy Now Pay Later, or Crypto Payments.

Adding a standalone button to your checkout removes an extra step for the customer, increases awareness of specific payment methods, and can improve conversion rates.

Implementation

Include the institutionId field in your payment request. When a valid institutionId is included, the customer is taken directly to that payment method. The institutionId for each payment method is available on the relevant Payment method identifiers page.

{
  "siteCode": "YOUR_SITE_CODE",
  "region": "ZA",
  "amount": {
    "currency": "ZAR",
    "value": 100.00
  },
  "merchantReference": "ORDER-001",
  "expireAt": "2026-12-31T23:59:59Z",
  "returnUrl": "https://yourstore.com/order-complete",
  "institutionId": "YOUR_INSTITUTION_ID"
}

Customer Identity Verification#

If your business operates in a high-risk industry, you are required to implement Customer Identity VerificationCustomer Identity Verification Checking that the payment instrument belongs to the natural person making the payment. Ozow requires it for merchants it has classified as high-risk, on Pay by Bank, Absa Pay, Capitec Pay, Nedbank Direct EFT, FNB Payment Requests and PayShap Request, and can disable those methods where it is not implemented correctly. before going live with Bank API payment methods.

To implement it in One API, pass the payer.identity object in the payment request:

{
  "siteCode": "YOUR_SITE_CODE",
  "amount": { "currency": "ZAR", "value": 100.00 },
  "merchantReference": "ORDER-001",
  "expireAt": "2026-12-31T23:59:59Z",
  "returnUrl": "https://yourstore.com/order-complete",
  "payer": {
    "id": "CUSTOMER-123",
    "name": "Firstname Lastname",
    "identity": {
      "type": "said",
      "country": "ZA",
      "identifier": "0000000000000"
    }
  }
}

Identity fields

For full details on Customer Identity Verification requirements see Customer Identity Verification.

Next steps#

• Review the Building a secure integration checklist before going live
• Test your integration using Money in test cases
• Switch your base URL from staging to production when you are ready to go live
• See the One API reference for the full technical specification