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:
REQUIREMENTS
DESCRIPTION
Merchant Key
This is a unique Key created by iPay and assigned to third parties for integration.
Initiate payment transaction request to Gateway
​1
 Every request to iPay gateway to initiate and process payment transactions must contain the below parameters. 
​2
 The thing to note is that iPay requires each transaction to be identified by a unique invoice ID and an amount due (in GHS for the avoidance of doubt).
post
https://manage.ipaygh.com
/gateway/checkout
Initiate payment
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="[email protected]">
    <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:
​1
 Send an email informing you of the payment or cancellation.
​2
 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 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.
get
https://manage.ipaygh.com
/gateway/json_status_chk
Sample payment notification Request
PARAMETER
VALUES
VALUE TYPE
DESCRIPTION
1. 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.
2. status_reason
Free text
String
This parameter holds detail description for a "failed" Transaction status. 
For other status values, it is empty.
3. buyer_firstname
Free text
String
First name of customer. 
Usually empty /null since no value is passed
4. buyer_lastname
Free text
String
Last name of customer. 
Usually empty / null
5. buyer_email
Free text
String
Email address of customer. 
Usually empty / null
6. buyer_phone
Free text
String
Phone number of customer. 
Usually empty / nul
7. invoice_id
Free text
String
Invoice Id of transaction
8. amount
Free text
Float
Payment amount made
9. as_at
Free text
Date
Transaction timestamp on gateway
10. narration
Free text
String
Description of payment made
11. extra
Free text
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
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)
Card Payment Response Codes (psp_response_code)
CODE
DESCRIPTION
0
The transaction was approved by the acquirer
1
The transaction could not be processed for an unspecified reason that is not covered by the other response codes.
2
The transaction was declined by the issuing bank – the customer should contact the bank.
3
The processing host did not reply to the transaction request. 
This message is displayed after a specified time if no response is received from the issuing bank. It usually indicates that the issuing bank’s system is temporarily unavailable
4
The customer’s card is past its expiry date
5
The customer’s card has insufficient credit to cover their purchase
6
The transaction could not be processed due to a problem with the processing host’s system
7
The transaction could not be processed due to a problem with the Payment Server.
B
Your acquirer has blocked this BIN. Please contact the support desk for further information
U
This transaction has been declined due to the CSC being unacceptable to the Issuer. Cardholder should contact their bank
E
The transaction has been declined by the issuing bank – the cardholder should contact the bank.
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 value missing or empty
4.  GW-009
Merchant is deactivated from receiving payments

Last modified 2yr ago

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

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

PARAMETER	VALUES	VALUE TYPE	DESCRIPTION
`1. 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.
`2. status_reason`	Free text	String	This parameter holds detail description for a "failed" Transaction status. For other status values, it is empty.
`3. buyer_firstname`	Free text	String	First name of customer. Usually empty /null since no value is passed
`4. buyer_lastname`	Free text	String	Last name of customer. Usually empty / null
`5. buyer_email`	Free text	String	Email address of customer. Usually empty / null
`6. buyer_phone`	Free text	String	Phone number of customer. Usually empty / nul
`7. invoice_id`	Free text	String	Invoice Id of transaction
`8. amount`	Free text	Float	Payment amount made
`9. as_at`	Free text	Date	Transaction timestamp on gateway
`10. narration`	Free text	String	Description of payment made
`11. extra`	Free text	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 `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)

CODE	DESCRIPTION
0	The transaction was approved by the acquirer
1	The transaction could not be processed for an unspecified reason that is not covered by the other response codes.
2	The transaction was declined by the issuing bank – the customer should contact the bank.
3	The processing host did not reply to the transaction request. This message is displayed after a specified time if no response is received from the issuing bank. It usually indicates that the issuing bank’s system is temporarily unavailable
4	The customer’s card is past its expiry date
5	The customer’s card has insufficient credit to cover their purchase
6	The transaction could not be processed due to a problem with the processing host’s system
7	The transaction could not be processed due to a problem with the Payment Server.
B	Your acquirer has blocked this BIN. Please contact the support desk for further information
U	This transaction has been declined due to the CSC being unacceptable to the Issuer. Cardholder should contact their bank
E	The transaction has been declined by the issuing bank – the cardholder should contact the bank.