Version: current

Mobile Money with Direct API

About this guide

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

Mobile Money integration through Direct API is available to the following countries:

  • Ghana

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

How it works

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

  1. Enable Mobile Money

    Mobile Money 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. Configure your Notification URL

    For your Mobile Money transactions, once the payment is confirmed you will receive a notification changing the status from pending to confirmed. Check the instructions for configuring your URL on Notifications

    Basic parameters:

    ParameterDescription
    operationOperation must be request
    integration_keyYour unique and secret integration key
    payment_type_codeFor Mobile Networ Opperators in Ghana the types are mpesa, airtel and mtn
    countryTwo-letter country code - gh for Ghana

    Customer data:

    ParameterDescription
    phone_numberCustomer phone number, in full international format. It is a mandatory item
    account_numberCustomer bank account with 16 characters limitation

    Charge parameters:

    ParameterDescription
    merchant_payment_codeUnique merchant payment code
    currency_codeISO-4217 Currency code transaction. Supported value: GHS
    amount_totalTotal amount to be charged in full mode, without decimals
    info

    The phone_number information is key for this payment flow and it's used to send a push notification for the customer to validate and confirm the charge. It must be sent in full international format, including the Country Code (233 for Ghana).

    In Ghana all mobile money payments requires an OTP authentication before charging the client.

    Check the example:

    curl -L -X POST 'https://sandbox.ebanxpay.com/ws/direct' \
    -H 'Content-Type: application/json' \
    --data-raw '{
    "integration_key": "{{integration_key}}",
    "operation": "request",
    "payment": {
    "name": "YOUR NAME",
    "email": "youremail@youremail.com",
    "phone_number": "234000000000",
    "country": "gh",
    "payment_type_code": "AIRTEL",
    "merchant_payment_code": "63c9377be268e2131",
    "currency_code": "GHS",
    "amount_total": "100"
    }
    }'

    A successful request will return a JSON response like the one below.

    {
    "payment": {
    "hash": "65d9025d1b3125c494bbaa5e28d591c684faa41543c7cf91",
    "country": "gh",
    "merchant_payment_code": "63c9377be268e2131",
    "order_number": null,
    "status": "PE",
    "status_date": null,
    "open_date": "2024-02-23 20:38:53",
    "confirm_date": null,
    "transfer_date": null,
    "amount_br": "100.00",
    "amount_ext": "100.00",
    "amount_iof": "0.00",
    "currency_rate": "1.0000",
    "currency_ext": "GHS",
    "due_date": "2024-02-26",
    "instalments": "1",
    "payment_type_code": "airtel",
    "redirect_url": "https://sandbox.ebanx.com/ws/redirect/execute?hash=65d9025d1b3125c494bbaa5e28d591c684faa41543c7cf91",
    "pre_approved": false,
    "capture_available": null,
    "withOtp": true
    },
    "status": "SUCCESS",
    "redirect_url": "https://sandbox.ebanx.com/ws/redirect/execute?hash=65d9025d1b3125c494bbaa5e28d591c684faa41543c7cf91"
    }
    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. OTP Functionality

    To use the OTP functionality in the Cellulant flow for Ghana (Until now), you will need to make some API calls.

    The first call is to create an authorization to make calls and update the KEY in the expirable_key table. The field values must be confirmed when making the call

    In the second call, a payment will be created. A detail to identify it as an OTP is a field called withOtp. Here's an example of a payment returned. Some data will be omitted, just for better visualization.

    {
    "payment": {
    "hash": "123456789",
    "country": "gh",
    "merchant_payment_code": "67838300",
    "status": "PE",
    "currency_ext": "GHS",
    "instalments": "1",
    "payment_type_code": "airtel",
    "redirect_url": "https://sandbox.ebanx.com/ws/redirect/execute?hash=123456789",
    "pre_approved": false,
    "capture_available": null,
    "customer": {
    "document": "38850825862",
    },
    "single_transaction": {
    "amount_local": "0.00",
    "amount_crossborder": "10.00"
    }
    "withOtp": true
    },
    "status": "SUCCESS",
    "redirect_url": "https://sandbox.ebanx.com/ws/redirect/execute?hash=123456789"
    }

    The fields that must be sent to obtain the above response.

    {
    "integration_key": "987654321",
    "operation": "request",
    "payment": {
    "merchant_payment_code": "{{merchant_payment_code}}",
    "amount_total": 10,
    "currency_code": "GHS",
    "name": "Johnny Silva",
    "e-mail": "johnny.arruda@objective.com.br",
    "birth_date": "15\/09\/1995",
    "document": "38850825862",
    "country": "gh",
    "zipcode": "11111",
    "address": "Rua E",
    "city": "São Paulo",
    "street_number": "10",
    "state": "SP",
    "phone_number": "2337000000",
    "payment_type_code": "airtel"
    }
    }

    The third step is to validate this payment. To do this, the payment hash will be used, along with the phone number, to confirm the payment. The token will also be used in this validation along with the other data to confirm the payment. In the example, we used the wrong data, but when making the request, make the change.

    {
    "hash": "123456789",
    "phone_number": "23370000000",
    "token": "123456",
    }

  4. Error Codes

    Some Error Codes could appear into the integration journey. Find below a list of these items and it meanings to serve as a reference in your troubleshooting

    Error Codes:

    Error CodeDescription
    BP-OTP-000Missing fields
    BP-OTP-001Payment not found
    BP-OTP-002Otp validation fail
    BP-OTP-003Payment is pending
    BP-OTP-004Fail in make the charge
    BP-OTP-005Invalid Token
    BP-OTP-006Problem in resolver processor

  5. Checkout using Mobile Money

    The following images depicts how a checkout will behave using Mobile Money in Ghana

    Step 1 Customer fill the blank fields below with their information Mobile Money with Direct API

    Step 2 Customer choose Mobile Money as payment method Mobile Money with Direct API

    Step 3 Customer will be redirected to insert an OTP code sent via SMS Mobile Money with Direct API

    Step 4 Customer will complete the payment in their mobile phone Mobile Money with Direct API

    Step 5

    Scenario A | Scenario with successful payment Mobile Money with Direct API

    Scenario B | Scenario with denied payment Mobile Money with Direct API

  6. Wait for the payment

    Shortly after a successful charge response your customer will receive a push notification, from the mobile operator network, on its mobile device requiring a PIN validation to confirm the payment.

    Once the customer confirms it, 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 Fernando Pankiewicz Gomes
On this page