Version: current

Ozow with Direct API

About this guide

This page explains how to add Ozow to your existing Direct API integration. Direct API integration is basically the same for all payment methods, only varying the payment_type_code and some additional required fields.

Availability:

Ozow integration through Direct API is available to the following countries:

  • South Africa

If you are not integrated with EBANX Direct API yet, please take a look in this basic guide about it. Are you not sure if EBANX Direct API is the best option for your e-commerce? Please, talk with one of our integration specialists.

What you will need

Before starting your integration, please make sure that you have:

  1. An EBANX Sandbox account. That's not the case? Please sign up for an Sandbox Account here;
  2. Ozow enabled in your EBANX Dashboard.

How it works

To complete Ozow integration through EBANX Direct API, please follow the steps below.

  1. Enable Ozow

    Ozow availability may vary depending on your contract. So the first step is to check if it is active in your EBANX dashboard.

    All set? We can go ahead to next step, otherwise, please get in touch with our integration specialists.

  2. Call the /ws/direct end-point to get the Ozow link (server-side)

    " With Ozow, your consumers are redirected to a third-party website and the payment is made safely and quickly. To get this redirection link, you just need to call the end-point ws/direct (server-side) with the following required fields:

    Basic parameters:

    ParameterDescription
    operationOperation must be request
    integration_keyYour unique and secret integration key
    payment_type_codeFor Ozow is ozow
    countryTwo-letter country code - za for South Africa

    How to use the Get Bank Code

    With this method, the merchant's user is directed straight to the selected bank, reducing the number of steps the user has to take and improving the overall UX.

    Customer data:

    ParameterDescription
    nameCustomer name
    emailCustomer email
    phone_numberCustomer phone number

    Charge parameters:

    ParameterDescription
    merchant_payment_codeUnique merchant payment code
    currency_codeISO-4217 Currency code transaction. Supported value: ZAR
    amount_totalTotal amount to be charged
    notification_urlURL to notify merchants when a transaction status change

    Get a Bank Code

    Before getting a Bank Code, it is necessary to obtain it. To get this code, you must call the end-point /ws/getBankList.

    curl --location --request GET 'https://sandbox.ebanxpay.com/ws/getBankList' \
    --data-urlencode 'integration_key={{integration_key}}' \
    --data-urlencode 'payment_type=ozow' \
    --data-urlencode 'country=za'
    ParameterDescription
    integration_key"your integration key"
    country_codeza
    payment_typeozow

    The payload below depicts an example of how to use the bank_code parameter

    Request

    curl -L -X POST 'https://sandbox.ebanxpay.com/ws/direct\execute' \
    -H 'Content-Type: application/json' \
    --data-raw '{
    "integration_key": "{{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",
    "notfication_url": "https://your-notification-url.com",
    },
    "metadata": {
    "bank_details": {
    "bank_code": "ABSAZA "
    }
    }
    }

    The payload below depicts an example without using the bank_code parameter

    curl -L -X POST 'https://sandbox.ebanxpay.com/ws/direct' \
    -H 'Content-Type: application/json' \
    --data-raw '{
    "integration_key": "{{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",
    "notfication_url": "https://your-notification-url.com",
    }
    }'

    A successful request will return a JSON response like the one below. The redirection link to the third-party website will be in the parameter payment.redirect_url.

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

    The complete API reference for the end-point ws/direct can be found here. We strongly recommend you to take a look in all the available options.

  3. 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 transferred to Ozow environment where they'll select the bank and complete the steps to finalize their payment securely and easily.

    At this point you have a pending payment in your EBANX Dashboard.

    Sandbox environment

    You can test this integration in our Sandbox environment as we offer a mock interface.

    Check it below:

    Ozow

  4. Wait for the payment

    Once the customer successfully completes the transaction, it will take sometime to EBANX get informed by Ozow. As soon as we get the confirmation, payment status is modified from pending to confirmed.

    If your customers don't conclude the payment, it will be automatically canceled.

Getting help

We hope this article was enlightening, but in case we’ve failed to take out your doubts you have the following options to keep on seeking for answers:

  • If you’re not our partner yet and would like to know more about our prices and conditions please fill our this form and our commercial team will get in touch with you.
  • In case you’re already our partner please get in touch with our support team at integration@ebanx.com.
Edit this page
Last updated on by FlavioCostaeSilva
On this page