Skip to main content
USSD

USSD (Unstructured Supplementary Service Data) is a widely used payment method in various regions, allowing customers to make transactions via their mobile phones without needing internet access. In the EBANX integration, USSD provides a simple and accessible payment experience for customers who may not have smartphones or stable internet connections. When a customer selects USSD as their payment method, EBANX generates a code that the customer enters into their phone’s dialer. The customer follows the interactive prompts on their screen to authorize the transaction securely. This method is especially advantageous in regions where mobile banking infrastructure is popular and provides an accessible way for customers to complete purchases.

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​

  • Select USSD as payment method - Your customer chooses USSD as the payment method at checkout.
  • 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.

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

    https://sandbox.ebanx.com/ws/direct

  2. Define your parameters

    With USSD, 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:​

    ParameterDescription
    operationSet to request
    integration_keyYour EBANX integration key
    payment_type_codeSet to ussd
    countrySet to ng for Nigeria

    Payment parameters:​

    ParameterDescription
    merchant_payment_codeUnique merchant payment code
    currency_codeSupported value: NGN
    amount_totalTotal amount to be charged
    nameCustomer name
    emailCustomer email
    phone_numberCustomer phone number

    Bank parameters:​

    ParameterDescription
    payment.bank_details.bank_codeBank code. See below
    payment.bank_details.account_numberBank account number.
    Mandatory when zenith_bank.

    Bank parameters​

    When you include bank_code in your ws/direct request for USSD, 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
    • country - Set to ng (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",
        "operation": "request",
        "country": "ng"
      }'

    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

  3. Sample request

    curl -X POST \
      --location 'https://sandbox.ebanx.com/ws/direct' \
      --header 'Content-Type: application/json' \
      --data '{
        "integration_key": "your_ebanx_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": "zenith_bank",
            "account_number": "245234672345" // Mandatory when bank_code is `zenith_bank`
          }
        }
      }'

  4. Sample response

    A successful request returns a response like the example below, with the bank redirect link provided in the payment.redirect_url parameter.


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

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

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

  6. Monitor payment for status changes

    Notifications

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

    • After receiving a notification, retrieve the payment status.

  7. Congratulations!

    You have succesfully integrated USSD.

    For more information, refer to the
    Direct API reference guidechevron_right

Resources​

Use the following resources when testing in your sandbox environment.

Credit Card Icon

Sample Cards

Click here to view mock card data to validate your payment integration.

Click to explorechevron_right
Globe Icon

API Reference

Click here to access detailed API documentation to integrate efficiently.

Click to explorechevron_right
Mock Data Icon

Mock Customer Data

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

Click to explorechevron_right
Debit Card Icon

Error Codes

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

Click to explorechevron_right

Still need help?

Help Image

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