Ozow | EBANX Developers Academy

Ozow is a popular online payment method in South Africa, integrated with EBANX to enable instant electronic funds transfer (EFT) payments directly from a customer’s bank account. With Ozow, customers are securely redirected to their bank’s platform where they authorize payment in real-time, simplifying the checkout process without needing credit or debit cards. This integration supports multiple South African banks, providing a seamless experience for customers accustomed to local payment methods.

Requirements

API credentials - Ensure you have your EBANX integration key. If not, complete the Merchant Signup Form.
Familiarity with EBANX Direct - This setup follows the same general structure as other payment methods, with a few unique parameters.

How it works

Get bank list - Use the Get Bank List API to retrieve available bank codes.
Prompt customer for bank selection - Display the list of banks obtained from the Get Bank List API and prompt the customer to select their bank.
Request payment - Call the ws/direct endpoint with the required parameters, including the selected bank code.
Redirect customer - Redirect the customer to the generated URL, where they will be taken directly to their selected bank’s platform to complete the payment.
Handle notifications - Set up notifications to receive real-time updates on the payment status from EBANX.

Instructions

Follow the steps below.

Select your environment
Select the appropriate environment for your integration. Use the sandbox environment for testing, or the production environment for live transactions. Use the URL for your HTTP requests based on your selection.
SandboxProduction
https://sandbox.ebanx.com/ws/direct

Define your parameters

With Ozow, customers are redirected to a secure third-party website to complete the payment quickly and safely. To obtain this redirection link, call the ws/direct endpoint with the following required fields:

Basic parameters:

Parameter	Description
`operation`	Set to `request`
`integration_key`	Your EBANX integration key
`payment_type_code`	Set to `ozow`
`country`	Set to `za` for South Africa

Payment parameters:

Parameter	Description
`merchant_payment_code`	Unique merchant payment code
`currency_code`	Supported value: `ZAR`
`amount_total`	Total amount to be charged
`notification_url`	URL to notify merchants when a transaction status change
`name`	Customer name
`email`	Customer email
`phone_number`	Customer phone number

Bank code parameter:

Parameter	Description
`metadata.bank_details.bank_code`	Bank code. (See below).

Bank code parameter

When you include bank_code in your ws/direct request for Ozow, it streamlines the payment process by directing the customer straight to their selected bank. This reduces steps in the user experience, as it eliminates the need for the customer to manually choose their bank after redirection, leading to a quicker, more seamless checkout.

If you do not include the bank code in the request:

The customer will be redirected to a selection page where they must manually select their bank.
This adds an extra step, slightly extending the checkout time and potentially impacting the user experience, especially for returning customers who are already familiar with their bank choice.

Including the bank code generally enhances the UX by making the payment flow more direct and efficient.

Capture bank code

To prompt your customer for a bank selection, first retrieve the available banks by calling the ws/getBankList API with the following parameters:

Parameters

integration_key - Your EBANX integration key
payment_type - Set to ozow
country - Set to za (for South Africa)

See the Get Bank List API reference guide for more info.

Sample request:

// Get Bank List 
curl -X POST \
  --location 'https://sandbox.ebanxpay.com/ws/getBankList' \
  --header 'Content-Type: application/json' \
  --data '{
    "integration_key": "your_ebanx_integration_key",
    "payment_type": "ozow",
    "country": "za"
  }'

Sample response

// Bank list.
[
  {
    "code": "banco_agrario",
    "name": "BANCO AGRARIO"
  },
          // ... additional banks.
  {
    "code": "banco_av_villas",
    "name": "BANCO AV VILLAS"
  },
]

Use the bank list to prompt your customer to make a selection. The bank_code can then be included in the payment request, ensuring the customer is redirected appropriately to their bank during the checkout process

Sample request (with bank code)

The following depicts an example with the bank_code parameter.

curl -X POST \
  --location 'https://sandbox.ebanx.com/ws/direct\execute' \
  --header 'Content-Type: application/json' \
  --data '{
    "integration_key": "your_ebanx_integration_key",
    "payment": {
        "payment_type_code": "ozow",
        "currency_code": "ZAR",
        "merchant_payment_code": "merchant_payment_code_here",
        "country": "ZA",
        "document": "0301014304184",
        "email": "email@example.com",
        "name": "John Example",
        "amount_total": "1",
        "redirect_url": "https://your-call-back-url.com",
        "notification_url": "https://your-notification-url.com"
    },
    "metadata": {
        "bank_details": {
            "bank_code": "ABSAZA" // Bank code included.
        }
    }
}'

Sample request (without bank code)

The following depicts an example without the bank_code parameter.

If you do not include the bank code in the request, your customer will be redirected to a selection page where they must manually select their bank.

curl -X POST \
  --location 'https://sandbox.ebanx.com/ws/direct' \
  --header 'Content-Type: application/json' \
  --data '{
    "integration_key": "your_ebanx_integration_key",
    "payment": {
        "payment_type_code": "ozow",
        "currency_code": "ZAR",
        "merchant_payment_code": "merchant_payment_code_here",
        "country": "ZA",
        "document": "0301014304184",
        "email": "email@example.com",
        "name": "John Example",
        "amount_total": "1",
        "redirect_url": "https://your-call-back-url.com",
        "notification_url": "https://your-notification-url.com"
    }
}'

Example response

A successful request returns a response like the example below, with the third-party website link provided in the payment.redirect_url parameter.

{
  "payment": {
    "hash": "63daaad563d447b3b4ab570fc519333b053447befdffcd67",
    "country": "za",
    "merchant_payment_code": "rimi9m6blfagmqga2c1",
    "order_number": "1234567",
    "status": "PE",
    "status_date": null,
    "open_date": "2023-01-01 01:01:01",
    "confirm_date": null,
    "transfer_date": null,
    "amount_br": "50.00",
    "amount_ext": "50.00",
    "amount_iof": "0.00",
    "currency_rate": "1.0000",
    "currency_ext": "ZAR",
    "due_date": "2023-01-01 01:01:01",
    "instalments": "1",
    "payment_type_code": "ozow",
    "redirect_url": "https://sandbox.ebanx.com/ws/redirect/execute?hash=63daaad563d447b3b4ab570fc519333b053447befdffcd67",
    "pre_approved": false,
    "capture_available": null
  },
  "status": "SUCCESS",
  "redirect_url": "https://sandbox.ebanx.com/ws/redirect/execute?hash=63daaad563d447b3b4ab570fc519333b053447befdffcd67"
}

At this stage, the payment will appear as pending (PE) in your

EBANX Dashboard

Redirect customer to the returned URL
Redirect your customer to the URL returned in the parameter redirect_url. After the redirection, your customer will be at a third-party website with all the necessary purchase details to finalize their payment securely and easily.
Testing Ozow in a sandbox environment
In our Sandbox environment, we provide an Ozow simulation interface to test bank transfer payments. This mock interface allows you to simulate different payment outcomes:
- Simulate Authorized = YES: Confirms the payment as successful.
- Simulate Authorized = NO: Denies the payment.
- Leave Pending: Leaves the payment in a pending state.
This simulation mimics the real production flow, where users are redirected to their Internet Banking to complete transactions, enabling you to thoroughly test authorized and unauthorized payments.
Monitor payment for status changes
Notifications
- EBANX will send a notification whenever a payment status changes.
- Make sure your system is set up to receive notifications from EBANX for any changes in payment status.
- Learn more about Payment Notifications
Status
- After receiving a notification that status has changed, retrieve the payment status.
- When a payment is confirmed, the status will change from pending (PE) to confirmed (CO). If the customer does not complete the payment, the status will eventually change to cancelled (CA).
- Learn more about Retrieving Payment Status
Congratulations!
You have succesfully integrated Ozow.
For more information, refer to the
Direct API reference guide

Resources

Use the following resources when testing in your sandbox environment.

API Reference

Click here to access detailed API documentation to integrate efficiently.

Click to explore

Mock Customer Data

Click here to view mock customer data for testing and validating user flows.

Click to explore

Error Codes

Click here to review common error codes to troubleshoot and resolve issues quickly.

Click to explore

Still need help?

We hope this article was helpful. If you still have questions, you can explore the following options:

Merchant support: Contact our support team at sales.engineering@ebanx.com for assistance.
Not a partner yet? Please complete the Merchant Signup Form, and our commercial team will reach out to you.

Requirements​

How it works​

Instructions​

Select your environment

Define your parameters

Basic parameters:​

Payment parameters:​

Bank code parameter:​

Bank code parameter​

Capture bank code​

Sample request (with bank code)

Sample request (without bank code)

Example response

Redirect customer to the returned URL

Testing Ozow in a sandbox environment​

Monitor payment for status changes

Congratulations!

Resources​

API Reference

Mock Customer Data

Error Codes

Still need help?

Requirements

How it works

Instructions

Basic parameters:

Payment parameters:

Bank code parameter:

Bank code parameter

Capture bank code

Testing Ozow in a sandbox environment

Resources