On this page you will be guided on how to integrate the ISW IPG to your website to handle payment processing.
Scope
On this page you will be guided on how to integrate the ISW IPG to your website to handle payment processing.
Flow Overview
When a customer is ready to pay the integrating merchant is expected to make HTTP POST request containing checkout information such as merchant id and amount to the IPG backend.
The IPG backend logs the information under a unique session id and redirects the customer to the IPG frontend where they can proceed to enter payment specific details like card or phone details and pay.
Once the payment has been made the IPG frontend redirects to the merchant’s site with the payment response appended to the url as a query parameter. In case the payment processing failed this response will contain the failure reason.
Steps #
Merchant website constructs payment/checkout information including such things as amount, order id, transaction ref, and redirect url.
When the customer proceeds to pay the merchant site should then make a POST request to https://{host}/ipg-backend/api/checkout (the IPG backend url).
The IPG backend then processes the POST requests and redirects to a frontend url with a unique session id for the payment where the customer can enter payment specific details such as card or mobile number.
Once the customer submits the payment details the frontend handles processing between it and the ISW or other payment provider APIs.
If successful the IPG frontend redirects to the merchant’s specified redirect url with the response appended as a query parameter called response.
In case a payment attempt fails the user gets the option to try again using the same or other payment option, only the last response gets forwarded to the merchant-provided redirect url.
Initiating a payment
A payment is initiated by POSTing to https://gatewaybackend-uat.quickteller.co.ke/ipg-backend/api/checkout or the equivalent live URL as shall be provided.
The POST request’s Content-Type header must be application/x-www-form-urlencoded
Sample request using cURL #
curl --location --request POST 'https://gatewaybackend-uat.quickteller.co.ke/ipg-backend/api/checkout' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'merchantCode=ISWKEN0001' \
--data-urlencode 'domain=ISWKE' \
--data-urlencode 'transactionReference=f5qva' \
--data-urlencode 'orderId=qu20iz' \
--data-urlencode 'expiryTime=2021-04-13T17:16:44.981Z' \
--data-urlencode 'currencyCode=KES' \
--data-urlencode 'amount=100' \
--data-urlencode 'narration=Test+from+new+gateway' \
--data-urlencode 'redirectUrl=https://uat.quickteller.co.ke/' \
--data-urlencode 'iconUrl=' \
--data-urlencode 'merchantName=' \
--data-urlencode 'providerIconUrl=' \
--data-urlencode 'cardTokensJson=[{"panLast4Digits":"1895","panFirst6Digits":"506183","token":"C48FA7D7F466914A3E4440DE458AABC1914B9500CC7780BEB4","expiry":"05/20"},{"panLast4Digits":"1111","panFirst6Digits":"411111","token":"3105E927EF17A245977CDA0ED62B257E4378592E8D7C7A5272-016153570198200","expiry":"02/22"}]' \
--data-urlencode 'reqId=' \
--data-urlencode 'field1=' \
--data-urlencode 'dateOfPayment=2016-09-05T10:20:26' \
--data-urlencode 'terminalId=3TLP0001' \
--data-urlencode 'terminalType=What?' \
--data-urlencode 'channel=WEB' \
--data-urlencode 'fee=0' \
--data-urlencode 'preauth=0' \
--data-urlencode 'customerId=1002' \
--data-urlencode 'customerFirstName=Japheth' \
--data-urlencode 'customerSecondName=Ongeri' \
--data-urlencode '[email protected]' \
--data-urlencode 'customerMobile=86-13012345678' \
--data-urlencode 'customerCity=NBI' \
--data-urlencode 'customerCountry=KE' \
--data-urlencode 'customerPostalCode=wstlnds' \
--data-urlencode 'customerStreet=1002' \
--data-urlencode 'customerState=NBI'
Complete POST parameters ref
The following table contains all the expected form fields that can be submitted when initiating a payment.
| Field | Required | Description |
|---|---|---|
| transactionReference | true | A unique identifier of the transaction on the merchant’s side – maximum 15 characters, duplicates will be rejected. |
| merchantCode | true | The merchant id assigned by ISW |
| currencyCode | true | The ISO currency code e.g. KES |
| amount | true | Transaction Amount – in minor denomination (cents) |
| dateOfPayment | false | Date of the payment |
| orderId | true | Merchant’s orderId for the payment item, similar to receipt number, duplicates allowed. |
| terminalId | false | The terminal id |
| terminalType | true | |
| redirectUrl | true | The url of the merchant page to which IPG will redirect the user and pass the response once payment completes. |
| channel | false | |
| domain | true | The domain the merchant is assigned to, provided by ISW – default ISWKE |
| narration | false | Description for the transaction |
| fee | false | Fee – default 0 |
| preauth | false | Preauth – default 0 |
| iconUrl | false | A web-accessible url of the merchant icon to be used in the IPG frontend. If none is given the ISW logo will be shown. |
| providerIconUrl | false | |
| cardTokensJson | false | JSON string array containing one or more json objects representing saved card tokens, for example [{"panLast4Digits":"1111","panFirst6Digits":"411111","token":"DBA747BC30109711E8A1A2FDAFCD27A851B37DDA24F8BE2724","expiry":"04/20"}] |
| reqId | false | |
| merchantName | false | |
| field1 | false | |
| customerId | true | The customer’s id from the merchant’s point of view e.g. email, phone, or database/registration id. |
| customerFirstName | false | Customer’s first name |
| customerSecondName | false | Customer’s second name |
| customerEmail | false | Customer’s email |
| customerMobile | false | Customer’s mobile |
| customerCity | false | Customer’s city |
| customerCountry | false | Customer’s country |
| customerPostalCode | false | Customer’s postal code |
| customerStreet | false | Customer’s street |
| customerState | false | Customer’s state |
| expiryTime | false | |
| displayPrivacyPolicy | false | |
| applyOffer | false | Enable or disable application of configured offers for a specific payment. False by default which means true has to be passed for an offer to be applied |
| primaryAccentColor | false | A hex code for colour to set the primary accent colour for links, titles, and buttons |