USSD with Direct API

About this guide

This page explains how to add USSD 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:

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

• Nigeria

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. USSD enabled in your EBANX Dashboard.

How it works

To complete USSD integration throught EBANX Direct API, please follow the steps below.

1. Enable USSD

   USSD 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. Get the available banks for USSD

   To get list of available banks for USSD, 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 'operation=request' \

   --data-urlencode 'country=ng'

   A successful request will return an array with JSON objects listing bank code and name.

   Important: For when customer's bank is code: zenith_bank, the account_number field will be added as mandatory on the Basic parameters.

   Basic parameters:

   Parameter	Description
   operation	Operation must be request
   integration_key	Your unique and secret integration key
   payment_type_code	For USSD type is ussd
   country	Two-letter country code - ng for Nigeria
   bank_details.bank_code	Customer bank code, obtained at JSON object from /ws/getBankList
   bank_details.account_number	Customer account number. Mandatory when bank bank_code is zenith_bank

   Customer data:

   Parameter	Description
   name	Customer name
   email	Customer email
   phone_number	Customer phone number

   Charge parameters:

   Parameter	Description
   merchant_payment_code	Unique merchant payment code
   currency_code	ISO-4217 Currency code transaction. Supported value: NGN
   amount_total	Total amount to be charged

   Check the example:

   curl --location --request POST 'https://sandbox.ebanxpay.com/ws/direct' \

   --header 'Content-Type: application/json' \

   --data-raw '{

   "integration_key": "{{integration_key}}",

   "operation": "request",

   "payment": {

   "name": "John Doe",

   "email": "email@example.com",

   "phone_number": "2340000000",

   "country": "ng",

   "payment_type_code": "ussd",

   "merchant_payment_code": "13a7460fe0b1v21a",

   "currency_code": "NGN",

   "amount_total": 500,

   "bank_details": {

   "bank_code": "fidelity_bank"

   }

   }

   }'

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

   {

   "payment": {

   "hash": "63e3bd5332ffbbf4d81e046dbaf0bdae90acc3f15b91482f",

   "country": "ng",

   "merchant_payment_code": "13a7460fe0b1v21a",

   "order_number": "1234567",

   "status": "PE",

   "status_date": null,

   "open_date": "2023-01-01 01:01:01",

   "confirm_date": null,

   "transfer_date": null,

   "amount_br": "500.00",

   "amount_ext": "500.00",

   "amount_iof": "0.00",

   "currency_rate": "1.0000",

   "currency_ext": "NGN",

   "due_date": "2023-01-01",

   "instalments": "1",

   "payment_type_code": "ussd",

   "redirect_url": "https://sandbox.ebanx.com/ws/redirect/execute?hash=63e3bd5332ffbbf4d81e046dbaf0bdae90acc3f15b91482f",

   "pre_approved": false,

   "capture_available": null,

   },

   "status": "SUCCESS"

   }

   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 able to see the voucher with the information to complete the transaction.

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

4. Wait for the payment

   Once the transfer is completed by the customer, it will take sometime to EBANX get informed by the bank. 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.