Mobile Money

Mobile Money is a popular alternative payment method in Ghana, supported by EBANX to offer a convenient and secure way for customers to complete transactions using their mobile wallets. This method allows Ghana customers to make purchases directly from their mobile phones, leveraging the local mobile network operators’ infrastructure to access funds. By integrating Mobile Money through EBANX, you can provide Ghana customers with a trusted, widely used payment option that aligns with local preferences, offering a seamless checkout experience accessible to those without traditional bank accounts.

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

1. Payment request
   • The customer chooses Mobile Money as the payment method at checkout.
   • The merchant sends a Mobile Money (MoMo) payment request to EBANX.
2. Payment response
   • EBANX responds with payment.status set to Pending (PE).
   • And withOtp set to true, indicating that the payment requires OTP.
3. OTP collection and validation
   • EBANX notifies provider to send a one-time password (OTP) to the customer. (not visible to merchant).
   • The customer receives the OTP and provides it to the merchant.
   • The merchant sends a new request to EBANX with the OTP, hash, and phone number.
4. MoMo PIN request - The provider sends a PIN request to the customer (not visible to merchant).
   • Customer provides MOMO PIN - The customer enters their Mobile Money PIN (not visible to merchant).
   • Provider processes payment - The provider processes the payment (not visible to merchant).
   • Provider notifies EBANX - The provider notifies EBANX that the payment has been processed (not visible to merchant).
5. EBANX updates status - EBANX updates the payment status and notifies the merchant via webhook.

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.

   SandboxProduction

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

2. Define your parameters

   Once you’ve defined your parameters, these details will be used to construct your HTTP request, which initiates the Mobile Money transaction and enables EBANX to process the payment accurately and securely.

   
   

   Defining API parameters

   You must provide required parameters for payment requests. These parameters ensure successful completion of transactions.
   
   

   Essential parameters

   • payment.payment_type_code - Specifies the payment method to be used for the transaction.
   • payment.currency_code - Three-letter code of the payment currency.
   • payment.amount_total - Total amount to be charged.

   
   

   Additional parameters

   • EBANX Integration Key - Used to authenticate and authorize API requests.
   • Customer Information
     • Includes details such as the customer name, email, address and document number (Depends on the requirements of the payment method or local regulations).
     • While not mandatory for all countries or payment methods, providing this information can enhance security and increase the likelihood of successful processing.
   • Additional Context - Extra data for specific methods or countries.

   
   

   To learn more about API parameters, please refer to the

   API Reference Guide chevron_right

   At the API Reference Guide, select Ecuador and Safety Pay from the dropdown menues.

3. Sample request

   Use the following example to initiate a 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": "Kofi Aidoo",
           "email": "customeremail@youremail.com",
           "phone_number": "233241234567", // Required.
           "country": "gh",
           "payment_type_code": "airtel", // Mobile network operator.
           "merchant_payment_code": "63c9377be268e2131",
           "currency_code": "GHS",
           "amount_total": "100"
       }
     }'

4. Sample response

   A successful request returns a response like the example 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 // OTP requirement.
       },
       "status": "SUCCESS",
       "redirect_url": "https://sandbox.ebanx.com/ws/redirect/execute?hash=65d9025d1b3125c494bbaa5e28d591c684faa41543c7cf91"
   }
   
   
   At this stage, the payment will appear as pending (PE) in your

   EBANX Dashboardchevron_right

5. OTP collection and validation

   After you initiate the payment, EBANX triggers a process that sends an OTP directly to the customer. The merchant is responsible for collecting this OTP from the customer and validating it with EBANX.

   To validate the OTP, send a POST request to the /ws/otp endpoint. Include the following fields in the request:

   • Payment hash - The hash received in step 4.
   • Phone number - The customer's phone number.
   • Token - The OTP provided by the customer.

   EBANX will verify the OTP and proceed with the payment processing flow.

   
   

   Example validation request

   curl -X POST \
     --location 'https://sandbox.ebanx.com/ws/otp' \
     --header 'Content-Type: application/json' \
     --data '{
         "integration_key": "your_ebanx_integration_key",
         "operation": "validate",  // Set to 'validate'
         "hash": "65d9025d1b3125c494bbaa5e28d591c684faa41543c7cf91", // Hash from step 4.
         "phone_number": "233241234567",
         "token": "123456", // OTP 
     }'

6. MoMo PIN request

   After EBANX verifies the OTP, the provider sends a request to the customer to enter their Mobile Money (MoMo) PIN. This step, along with subsequent actions, occurs seamlessly in the background and is not visible to the merchant.

   Once the customer enters their PIN, the provider processes the payment and notifies EBANX of the transaction status. Finally, EBANX updates the payment status and sends a notification to the merchant via webhook, ensuring the merchant is informed of the outcome.

7. Monitor payment for status changes

   Once a payment is made, the status will change. EBANX uses webhooks to notify merchants of payment status changes. Upon receiving a webhook notification, the merchant should query EBANX to retrieve detailed information about the payment.

   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 Notificationschevron_right

   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 Statuschevron_right

8. Congratulations!

   You have succesfully integrated Mobile Money.

   For more information, refer to the

   Direct API reference guidechevron_right

Screenshots

The images below illustrate the checkout process when using Mobile Money in Ghana.

Step 1: Customer provides required fields.

Step 2: Customer chooses Mobile Money as the payment method.

Step 3: Customer is redirected to enter the OTP code sent via SMS.

Step 4: Customer completes the payment on their mobile phone.

Step 5

Result A | Payment Succesful.

Result B | Payment denied.

Error codes

During the integration process, various error codes may appear. Below is a list of codes to help guide your troubleshooting.

Error Code	Description
BP-OTP-000	Missing fields
BP-OTP-001	Payment not found
BP-OTP-002	OTP validation fail
BP-OTP-003	Payment is pending
BP-OTP-004	Failed to process the charge.
BP-OTP-005	Invalid Token
BP-OTP-006	Problem in resolver processor

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 explorechevron_right

Mock Customer Data

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

Click to explorechevron_right

Error Codes

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

Click to explorechevron_right

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.