Request Parameters
Parameters required to initiate payment transaction requests
Important
Every request to EcobankPay gateway to initiate and process payment transactions must contain the parameters described below.
API Endpoint
POST https://pgw.paywithonline.com/v1/mobile_agents_v2
Content-Type
Your request must include the following header:
Content-Type: application/json
Required Parameters
| Parameter | Required | Description |
|---|---|---|
| merchant_key | Y | Your unique assigned Merchant Key |
| invoice_id | Y | Your internally generated transaction invoice id. Should be unique for every transaction and not more than 25 characters in length. |
| total | Y | The total payment due for the cart. Please note that the gateway will *NOT* compute this. We want the merchant to compute this him/herself and to add in any tax or shipping elements they may want to. |
| success_url | N | The page to which EcobankPay will redirect the customer after customer completes the EcobankPay checkout process. Please note that this does not mean that payment has been received! |
| cancelled_url | N | The page to which EcobankPay will redirect the customer after customer cancels the EcobankPay checkout process. |
| number | N | Customer contact number (customer receives payment notification via SMS if provided) |
| N | Customer email address (customer receives payment notification if provided) | |
| name | N | Customer name |
| description | N | Description of payment or order description/details |
| ipn_url | N | This specifies the url to which EcobankPay will send notification once payment is received. |
| extra_outlet | N | Unique pre-configured Outlet/Branch ID for your merchant account. Pass this ID to record and track transactions per Outlet/Branches. |
| generate_checkout_url | Y | EcobankPay checkout page URL would be returned as part of the response payload for customer to be redirected. Value accepted: true |
| secure_hash | Y | Create an HMAC SHA-256 hash of the merchant_key, invoice_id and total query string. Kindly note the parameters must be sorted (eg invoice_id=test0&merchant_key=xxx-xxx&total=1). |
Example Request
{
"merchant_key": "acbd1234-1234-abcd-1234-abcdef123456",
"invoice_id": "invoice001",
"total": "25.00",
"description": "Ecobank payment test",
"name": "customer name",
"email": "customer@example.com",
"number": "233201234567",
"success_url": "https://example.com/success",
"cancelled_url": "https://example.com/cancel",
"ipn_url": "https://example.com/ipn-notification",
"extra_outlet": "main",
"generate_checkout_url": true,
"secure_hash": "6df3e718f9cb74a592ad8dd87f934c1723e5dec1112f70a860b3ccef7b840eeec"
}Note: The secure_hash value is an HMAC SHA-256 hash of the sorted parameters. The secret key will be provided to you during merchant registration.
Example hashing: HMAC SHA-256('invoice_id=invoice001&merchant_key=acbd1234-1234-abcd-1234-abcdef123456&total=25.00', 'YOUR_SECRET_KEY')
Extra Parameters
The extra parameter is an array object that can contain additional parameters such as:
| Parameter | Description |
|---|---|
| channel | Payment channel used by customer |
| Email address of customer if provided in initial request | |
| Mobile_no | Phone number of customer if provided in initial request |
| psp_response_code | This parameter is only available for Card Payment transactions. It holds the specific error code applied to a transaction. |
| psp_response_msg | This parameter gives explanation or description of the response error code for Card payments (if available). |