Api Integration

Overview

This document describes into details how to integrate into iPay 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, Vodafone Cash, VISA and MasterCard.

Prerequisite

To successfully complete the integration and send requests the following details are required as described in table:

Initiate payment transaction request to Gateway

Initiate payment

POST https://manage.ipaygh.com/gateway/checkout

This endpoint allows you to initiate payment transaction request.

Query Parameters

Sample code on how to generate the Request

<form action="https://manage.ipaygh.com/gateway/checkout" method="post">
    <input type="hidden" name="merchant_key"  value="PROVIDED MERCHANT KEY">
    <input type="hidden" name="success_url"  value="">
    <input type="hidden" name="cancelled_url" value="">    
    <input type="hidden" name="ipn_url"  value="">
    <input type="hidden" name="invoice_id" value="">
    <input type="hidden" name="extra_name"  value="customer name">
    <input type="hidden" name="extra_mobile" value="0240000000">    
    <input type="hidden" name="extra_email"  value="example@ipaygh.com">
    <input type="hidden" name="total" value="1.00">
    <input type="hidden" name="description"  value="Sample Order">
    <button type="submit">Make Payment</button>
</form>

Upon successful completion of payment process or cancellation of payment process on iPay 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, iPay can do two things:

It is worth stressing the IPN notification from iPay 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 iPay 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:

  1. Once an invoice is paid or cancelled, iPay does a GET to your IPN URL with the invoice_id parameter. Suppose, your IPN url is https://test.ipaygh.com/notify and a customer pays or cancels invoice with invoice ID: AA123, iPay will perform the GET request https://test.ipay.com/notify?invoice_id=AA123. This call is meant to prompt your application that an event of interest has occurred with respect to the invoice.

  2. Your application will then make the GET call "https://manage.ipaygh.com/gateway/json_status_chk?invoice_id=AA123&merchant_key =YOUR_MERCHANT_KEY" to receive details of the event.

  3. iPay 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

GET https://manage.ipaygh.com/gateway/json_status_chk

Query Parameters

Card Payment Response Codes (psp_response_code)

Gateway Error Codes:

Last updated