Payment Flow
Understanding the flow of payment transactions with EcobankPay
Important
Payment Transaction Flow
Customer selects items and proceeds to checkout
Customer browses merchant's website/app, selects products/services, and initiates the checkout process.
Merchant creates payment request
Merchant creates a payment request containing the required parameters (merchant_key, invoice_id, total, etc.) and sends it to the EcobankPay API.
Key Operations:
- Generate a unique invoice ID
- Calculate order total
- Create secure hash using merchant_key, invoice_id, and total
- Send POST request to EcobankPay endpoint
EcobankPay returns checkout URL
EcobankPay processes the request, validates the secure hash, and returns a checkout URL for the customer to complete the payment.
Response Content:
{
"invoice_id": "unique-invoice-id",
"tx_reference": "ecobankpay-transaction-reference",
"url": "https://pgw.paywithonline.com/v1/checkout/8a7b6c5d4e3f2g1h",
"success": true,
"message": "Invoice created"
}Customer is redirected to EcobankPay checkout
Merchant redirects the customer to the checkout URL provided by EcobankPay.
Checkout Process:
- Customer is taken to a secure EcobankPay-hosted page
- Payment options are displayed (Mobile Money, Cards, etc.)
- Customer selects preferred payment method
Customer completes payment
Customer enters payment details and confirms payment on the EcobankPay checkout page.
Payment Methods:
- Mobile Money: Customer enters phone number and confirms payment on mobile device
- Card Payment: Customer enters card details and completes 3D Secure verification if required
- QR Payments: Customer scans QR code with mobile banking app
EcobankPay processes payment
EcobankPay processes the payment through the selected payment method provider.
Customer is redirected back to merchant site
After payment is completed (or cancelled), the customer is redirected back to the merchant's success_url or cancelled_url.
EcobankPay sends notification to merchant
EcobankPay sends a notification to the merchant's IPN URL to inform about the payment status.
IPN Process:
- EcobankPay makes a GET request to merchant's IPN URL with invoice_id
- Merchant receives the notification and acknowledges receipt
Merchant verifies payment status
Merchant queries the EcobankPay API to verify the payment status using the invoice_id.
Status Verification:
- Merchant makes a GET request to the status check endpoint
- EcobankPay returns payment status (paid, cancelled, failed, etc.)
- Merchant updates order status in their system
Merchant fulfills order
If payment is successful, merchant fulfills the order and sends confirmation to the customer.
Payment Lifecycle
A payment in the EcobankPay system can go through several states during its lifecycle:
| Status | Description | Next Steps |
|---|---|---|
| new | Payment transaction is new, initiated to the respective payment network | Wait for customer to complete payment |
| awaiting_payment | Payment pending. Customer has not completed or cancelled payment yet. | Wait for customer to complete payment |
| paid | Payment made successfully by customer | Fulfill order |
| cancelled | Payment cancelled by customer | Update order status, notify customer |
| failed | Transaction failed. Reason for failure is provided in status_reason parameter. | Review error, update order status, notify customer |
Important Considerations
- Always verify payment status: Never rely solely on the redirect to your success URL as confirmation of payment. Always verify the payment status using the status check endpoint.
- Handle IPN notifications properly: IPN notifications are not confirmation of payment but rather a prompt to check the payment status. Always query the status check endpoint when receiving an IPN notification.
- Secure hash validation: Always validate the secure hash in your requests to ensure data integrity.
- Unique invoice IDs: Always use unique invoice IDs for each transaction to avoid confusion and ensure proper tracking.
- Error handling: Implement comprehensive error handling to provide a smooth experience for your customers.