Mobile Money Integration

Learn how to accept mobile money payments through EcobankPay

Overview

Mobile money integration with EcobankPay allows your customers to pay using their mobile wallets. The integration follows these general steps:

1. Initialize a payment request to EcobankPay
2. Redirect the customer to the EcobankPay checkout page
3. Customer completes payment on their mobile device
4. EcobankPay notifies your application of payment status
5. Verify the payment status using the status check endpoint

Integration Steps

1. Initiate Payment Request

To start a mobile money payment, send a POST request to the EcobankPay mobile agents endpoint:

The request body must include the following required parameters:

Optional parameters that enhance the payment experience:

2. Sample Request

Here's an example of a mobile money payment request:

POST https://pgw.paywithonline.com/v1/mobile_agents_v2
Content-Type: application/json

{
  "merchant_key": "abcdef1234-f5d6-4931-8544-58dc97a5",
  "invoice_id": "INV12345",
  "total": 10.00,
  "description": "Payment for Order #12345",
  "email": "customer@example.com",
  "number": "+233201234567",
  "success_url": "https://yourwebsite.com/payment/success",
  "cancelled_url": "https://yourwebsite.com/payment/cancelled",
  "ipn_url": "https://yourwebsite.com/api/payment-webhook",
  "secure_hash": "d4f321f8fddd0e7cc24e5d9bc321ea5c25c6f05d44401f7fb0b9f2a3cc4c"
}

3. Response Handling

Upon successful submission, you'll receive a JSON response with payment details:

{
  "invoice_id": "INV12345",
  "tx_reference": "ECO123456789",
  "status_code": 0,
  "status": "success",
  "message": "Process started",
  "checkout_url": "https://pgw.paywithonline.com/7785598425589933",
  "tx_token": "2198cskdnv7785598425589933"
}

The key parameters in the response:

• checkout_url: URL to redirect the customer to complete payment
• tx_reference: EcobankPay's unique transaction reference
• status: Initial transaction status (success indicates request accepted)

4. Redirect the Customer

Redirect your customer to the checkout_url provided in the response. This page will display payment instructions and options for the customer.

5. Payment Notification Handling

EcobankPay will notify your application about payment status in two ways:

• Redirect to your success_url or cancelled_url based on payment outcome
• POST request to your ipn_url with payment details (if provided)

6. Verify Payment Status

To verify the payment status, make a GET request to the transaction status endpoint:

The response will include the current transaction status:

{
  "status": "paid",
  "status_reason": "",
  "invoice_id": "INV12345",
  "amount": 10.00,
  "as_at": "2023-03-28T14:22:30Z",
  "narration": "Payment for Order #12345"
}

Possible status values:

• new: Payment transaction initiated but not completed
• paid: Payment successfully completed
• cancelled: Payment cancelled by customer
• awaiting_payment: Payment pending, customer has not completed or cancelled
• failed: Transaction failed (check status_reason for details)

Error Handling

Common errors you might encounter during mobile money integration:

Security Considerations

To ensure secure transactions:

• Create an HMAC SHA-256 hash of the request parameters for the secure_hash field
• Always verify payment status using the status check endpoint before fulfilling orders
• Store your merchant secret securely and never expose it in client-side code
• Use HTTPS for all communication with EcobankPay APIs