Receive Payments - Direct Checkout v1.0

Simplified integration guide for EcobankPay Direct Checkout

Gateway Overview

This document describes in detail how to integrate into EcobankPay gateway checkout to collect customer payments from your website or mobile App. You can use our re-direct API to process payments from MTN Mobile Money, AirtelTigo Money, Telecel Cash, VISA and MasterCard and GhQR.

Prerequisites

To successfully complete the integration and send requests, the following details are required:

REQUIREMENTS	DESCRIPTION
Merchant Key	This is a unique Key created by EcobankPay and assigned to third parties for integration.

Initiate payment transaction request to Gateway

Every request to EcobankPay gateway to initiate and process payment transactions must contain the below parameters.

The thing to note is that EcobankPay requires each transaction to be identified by a unique invoice ID and an amount due (in GHS for the avoidance of doubt).

Request:

Endpoint:

https://checkout.paywithonline.com/

Method:

POST

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.

Optional Parameters:

PARAMETER	REQUIRED	DESCRIPTION
extra_mobile	N	Customer contact number (customer receives payment notification via SMS if provided)
extra_email	N	Customer email address (customer receives payment Email notification if provided)
extra_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.

Sample code on how to generate the Request:

<form action="https://checkout.paywithonline.com/" method="post">
  <div class="modal-body">
    <div class="row">
      <div class="col-lg">
        <input name="merchant_key" type="hidden" value="your_merchant_key">
        <input name="success_url" type="hidden" value="">
        <input name="cancelled_url" type="hidden" value="">
        <input name="ipn_url" type="hidden" value="">
        Invoice ID <input name="invoice_id" type="text" value="">
        Name <input name="extra_name" type="text" value="">
        Contact <input name="extra_mobile" type="text" value="">
        Email <input name="extra_email" type="text" value="">
        Total <input name="total" type="text" value="">
      </div>
    </div>
  </div>
</form>

Upon successful completion of payment process or cancellation of payment process on EcobankPay gateway checkout page by customer, the customer is re-directed to the success url or cancelled url page specified in the request respectively.

Handling payment notifications

Once the customer pays or cancels an invoice, depending on your site setup, EcobankPay can do two things:

Send an email informing you of the payment or cancellation
Send a notification to an IPN (instant payment notification) URL for your application to take some automated action

It is worth stressing the IPN notification from EcobankPay is not confirmation of a payment. Rather it is a prompt that an event of interest has happened to one of your invoices. It is your application's responsibility to query the EcobankPay gateway for details on the event using the status check end point. While this may sound complicated, it is not. Here's how it works:

Once an invoice is paid or cancelled, EcobankPay does a GET to your IPN URL with the invoice_id parameter. Suppose, your IPN url is https://ipn_url.ecobankpay.com.gh/notify and a customer pays or cancels invoice with invoice ID AA123, EcobankPay will perform the GET requesthttps://ipn_url.ecobankpay.com.gh/notify?invoice_id=AA123. This call is meant to prompt your application that an event of interest has occurred with respect to this invoice.
Your application will then make the GET callhttps://pgw.paywithonline.com/v1/gateway/json_status_chk?invoice_id=AA123&merchant_key=YOUR_MERCHANT_KEY to receive details of the event.
EcobankPay responds to the query in the step above with a JSON object. Details of the response object are described as part of the status check end point.

Sample payment notification Request

Request:

Endpoint:

https://pgw.paywithonline.com/v1/gateway/json_status_chk

Method:

GET

Parameters:

PARAMETER	REQUIRED	DESCRIPTION
merchant_key	Y	Your unique assigned Merchant Key
invoice_id	Y	Invoice Id of the particular transaction whose details to check

Response Codes

Below is the general response received for a payment status request sent.

PARAMETER	VALUES	VALUE TYPE	DESCRIPTION
status	new, paid, cancelled, awaiting_payment, failed	String	Transaction status of payment: new: payment transaction is new, initiated to the respective payment network paid: payment made successfully by customer cancelled: payment cancelled by customer awaiting_payment: payment pending. Customer does not complete or cancel payment. Failed: Transaction failed. Reason for failure is provided in status_reason parameter.
status_reason	Free text	String	This parameter holds detail description for a Failed Transaction status. For other status values, it is empty.

Gateway Error Codes

#	ERROR	DESCRIPTION
1.	GW-001	merchant_key missing or empty
2.	GW-002	invoice_id missing or empty
3.	GW-003	total/amount value missing or empty
4.	GW-009	Merchant is deactivated from receiving payments

Response Parameters

PARAMETER	DESCRIPTION
psp_response_msg	This parameter gives explanation or description of the response error code for Card payments (if available).
psp_response_code	This parameter is only available for Card Payment transactions. It holds the specific error code applied to a transaction.

Extra Parameters

PARAMETER	VALUES	VALUE TYPE	DESCRIPTION
extra		Array Object	Sub array of extra parameters available:

channel	payment channel used by customer
email	Email address of customer if provided in initial request
Mobile_no	Phone number of customer if provided in initial request

← Back to Integration Guide Next: Payment Flow →