Integration Guide

Step-by-step guide to integrate EcobankPay into your application

Integration Options

Integration Flow

The integration with EcobankPay follows these high-level steps:

1. Merchant creates a payment request

   The merchant creates a payment request by sending required parameters (including the merchant key, invoice ID, and total amount) to the EcobankPay API endpoint.

2. EcobankPay returns a checkout URL

   EcobankPay processes the request and returns a checkout URL where the customer will be redirected to complete the payment.

3. Customer completes payment on EcobankPay

   The customer is redirected to the checkout URL where they select their preferred payment method (Mobile Money, Card, etc.) and complete the payment.

4. Customer is redirected back to merchant site

   After the payment is completed (or cancelled), the customer is redirected back to the merchant site using the success or cancelled URL provided in the initial request.

5. EcobankPay sends notification to merchant

   EcobankPay sends a notification to the merchant's IPN URL to inform them about the payment status.

6. Merchant verifies payment status

   The merchant verifies the payment status by querying the EcobankPay API with the invoice ID.

Step 1: Initiate Payment Request

To initiate a payment transaction, make a POST request to the EcobankPay API endpoint with the required parameters.

{
  "merchant_key": "your-merchant-key",
  "invoice_id": "unique-invoice-id",
  "total": "100.00",
  "description": "Payment for order #12345",
  "name": "Customer Name",
  "email": "customer@example.com",
  "number": "233201234567",
  "success_url": "https://your-website.com/success",
  "cancelled_url": "https://your-website.com/cancel",
  "ipn_url": "https://your-website.com/ipn-notification",
  "generate_checkout_url": true,
  "secure_hash": "calculated-hash-value"
}

For a complete list of request parameters and their descriptions, see the Request Parameters documentation.

// Example in JavaScript
const crypto = require('crypto');

const merchantKey = 'your-merchant-key';
const invoiceId = 'unique-invoice-id';
const total = '100.00';
const secretKey = 'your-secret-key'; // Provided by EcobankPay

// Sort parameters alphabetically and combine them
const dataToHash = `invoice_id=${invoiceId}&merchant_key=${merchantKey}&total=${total}`;

// Create HMAC SHA-256 hash
const secureHash = crypto.createHmac('sha256', secretKey)
                         .update(dataToHash)
                         .digest('hex');
console.log(secureHash); // Use this value in your request

Step 2: Handle EcobankPay Response

After sending the payment request, EcobankPay will return a response with a checkout URL.

{
  "invoice_id": "unique-invoice-id",
  "tx_reference": "ecobankpay-transaction-reference",
  "url": "https://pgw.paywithonline.com/v1/checkout/8a7b6c5d4e3f2g1h",
  "success": true,
  "message": "Invoice created"
}

If the request is successful, redirect the customer to the URL provided in the response to complete the payment.

{
  "success": false,
  "error": {
    "code": "GW-001",
    "message": "merchant_key missing or empty"
  }
}

If the request fails, handle the error appropriately in your application.

Step 3: Payment Verification

After the customer completes the payment process, you should verify the payment status using the status check endpoint.

{
  "invoice_id": "unique-invoice-id",
  "tx_reference": "ecobankpay-transaction-reference",
  "status": "paid",
  "status_reason": "",
  "amount": 100.00,
  "buyer_firstname": "Customer",
  "buyer_lastname": "Name",
  "buyer_email": "customer@example.com",
  "buyer_phone": "233201234567",
  "narration": "Payment for order #12345",
  "as_at": "2023-08-15T14:22:45Z"
}

For a complete list of response parameters and their descriptions, see the Response Codes documentation.

Step 4: Handling Payment Notifications

EcobankPay will send a notification to your IPN URL when a payment is completed or cancelled. Your application should handle these notifications appropriately.

For detailed information on handling payment notifications, see the Webhook Notifications documentation.

Next Steps

• Review the Request Parameters documentation for a complete list of parameters you can include in your payment requests.
• Understand the Response Codes returned by the EcobankPay API.
• Learn how to handle Webhook Notifications to automate your payment processing workflow.
• Familiarize yourself with the Error Codes that may be returned by the API.
• Check out the Sample Code for practical examples of implementing the EcobankPay integration.