Payment Gateway API guide for merchants

Version 1.2.1

Workflow for merchant

  • Present a “Pay with iPay” button at checkout
  • When the user selects “Pay with iPay”, merchant should create an order in iPay (using the Create order API). In this request, merchant is required to specify the amount, description, and 3 callback urls (success, failure and cancellation). If everything is fine, merchant will receive a payment Url in the response of that API call.
  • Merchant should direct the user’s browser to the paymentUrl received from iPay. From there, the payment will be handled by iPay. iPay might present a login page to authenticate the user. After authentication, the payment page will look similar to the second image on the side.
  • The iPay member will select the “Pay” button to confirm the payment, or “Cancel” to cancel the payment. There might be additional steps to finish the payment if the member has multi-factor authentication enabled. All of these will be handled by iPay.
  • After a payment is successfully completed, iPay’s payment gateway will redirect the client’s browser to the success CallbackUrl. This url should be hosted by merchant’s system, so merchant will know when the payment is successfully finished. Once the success callback is hit, It is strongly recommended that the merchant also uses the Check order status API from backend to ensure that the payment is actually successful.
If the iPay member cancels the payment by selecting the “Cancel” button on the payment gateway, member’s browser will be redirected to the cancelCallbackUrl. If the payment fails in gateway, iPay will redirect member’s browser to the failureCallbackUrl. These callback urls should also be hosted by merchant’s system

Figure: Sequence diagram of payment flow of iPay payment gateway

Sandbox and Production environments

iPay provides a sandbox environment for 3rd parties to assist them in development phase. When developing integration with iPay, 3rd parties can test their integration with the sandbox environment. The sandbox behaves exactly like the main production application, except no real money is involved in the transactions. A merchant can sign up to create a business account in the sandbox, just like the main site.

The URL of the sandbox application is https://demo.ipay.com.bd.

All the API specifications provided in this document applies for both the production and sandbox
environment, unless explicitly mentioned otherwise.

API Specification

Base URL for merchant APIs:

Sandbox: https://demo.ipay.com.bd/api/pg 

Production: https://app.ipay.com.bd/api/pg

Authentication

All REST API calls need to have bearer authentication. More precisely, all http requests need to have an additional Authorization header like below:

Authorization: Bearer <API Key>

Please note the single space between Bearer and <API Key>.
To avail your API Key (for both production and sandbox), please contact with iPay.

Create order API

This API will be used by merchant backend to create an order. It requires authentication in the form of an Authorization header.

URI {baseurl}/order
Method POST
Expected Request Content Type application/json
Expected additional headers "Authorization" : "Bearer <API Key>"
Expected Request Body {
"amount" : 120,
"referenceId" : "abcd1234",
"description" : "Buy x,y,z from XYZ.com",
"successCallbackUrl" : "https://xyz.com/success/reference/abcd1234",
"failureCallbackUrl" : "https://xyz.com/failure/reference/abcd1234",
"cancelCallbackUrl" : "https://xyz.com/cancel/reference/abcd1234"
}
Response Content Type
Status code Body
200 {
"message" : "Order placed successfully",
"orderId" : "IPAY-12345678",
"paymentUrl" : "app.ipay.com.bd/pay/IPAY-12345678",
"referenceId" : "abcd1234"
}
401 {
"message" : "Invalid API key"
}
409 {
"message" : "Reference Id 'abcd1234' has already been used"
}

Request fields

Field name Type Mandatory? Details
amount Number Yes The total payable amount of the order in BDT. Up to two decimal points of precision is allowed. For example: 100.23, 100.2, 100 all of these are allowed. 100.234 is not allowed.
referenceId String Yes A unique Identifier of the order which is generated by the merchant. This id should be unique for each order of a merchant. You can use it later in the Check order status API to check the status of this order in the gateway. This can be maximum 50 characters
description String Yes A textual description of the order. This will be shown in the payment page of the gateway, so that iPay member can easily have a glance for what he is paying. For example: “Buy goodies from xyz merchant”. This can be maximum 255 characters.
successCallbackUrl String Yes A URL served by the merchant’s system. If the payment is successful, iPay will redirect the member’s browser to that URL. For example: https://xyzmerchant.com/callback/success/abcd1234. So when that url is hit, merchant’s system will know when the payment is successful. This can be maximum 512 characters.
cancelCallbackUrl String Yes A URL served by the merchant’s system. If the iPay member cancels the payment (by clicking “Cancel” on payment page), iPay will redirect the member’s browser to that URL. For example: https://xyzmerchant.com/callback/cancel/abcd1234. So when that url is hit, merchant’s system will know when the payment is canceled. This can be maximum 512 characters.

Response fields

Field name Type Details
message String TA message summarizing the status of the operation.
orderId String A unique Identifier of the order generated by iPay’s payment gateway. You can use it later in the Check order status API to check the status of this order in the gateway. This will consist of a maximum of 25 characters.
paymentUrl String The URL of the payment gateway, where an iPay member can pay for this order. Merchant system should direct the client’s browser to this URL so that he/she can complete the payment.
referenceId String The referenceId of the order, generated by merchant. This is the same referenceId that was in the request.

Order statuses

Possible values of status and statusCode in Check order status API response:
Status statusCode Meaning
Created 102 The order has been created by merchant. No iPay member has taken any action on it yet. This order is still payable.
Successfully paid 200 The order has been successfully paid by an iPay member. This order is not payable anymore.
Payment cancelled by member 445 iPay member has cancelled the order by clicking on the “Cancel” button on iPay payment gateway. This order is not payable anymore.
Payment failed 444 iPay member has tried to pay the order and failed. This might result from insufficient balance of the member, the member’s account being blocked, his/her transaction limits being crossed etc. This order is not payable anymore.
Expired 410 If no action is taken by any iPay member on an order within 15 minutes of creation, the order will expire. An expired order is not payable.
Unknown status 500 This status denotes internal technical problems in the payment gateway. If you find this status, please contact with iPay.

Check order status API

This API can be used by merchant backend to check an order’s current status. It requires authentication in the form of an Authorization header.
URI This API has two versions. You can use any of them.

  1. Using reference id: {baseurl}/order/referenceId/{referenceId}/status
  2. Using order id: {baseurl}/order/{orderId}/status
Method GET
Expected additional headers "Authorization" : "Bearer <API Key>"
Response Content Type application/json
Response Content Type
Status code Body
200 {
"statusCode" : 200,
"status" : "Successfully paid",
"orderId" : "IPAY-1234",
"referenceId" : "abcd1234",
"transactionId" : "23I2-12345678",
"transactionTime" : "18 Sep 2017 12:33:39.749 BDT"
}
401 {
"message" : "Invalid API key"
}
409 {
"message" : "Order not found"
}

Request fields

Field name Type Mandatory? Details
orderId String Yes The orderId of the order that the merchant is querying. This is generated by iPay’s payment gateway and is returned as a response of the Create order API..
referenceId String Yes The referenceId of the order that the merchant is querying. This is the merchant-generated unique id that was used in Create order API.

Response fields

Field name Type Details
statusCode String A number denoting the current status of the order. All possible values of this code are listed in the Order statuses table.
status String A text denoting the current status of the order. All possible values of this status are listed in the Order statuses table.
orderId String TorderId of the order.
referenceId String referenceId of the order.
transactionId String If the payment is successful, this field will have the transactionId of the transaction between iPay member and the merchant. Both the merchant and the iPay member will see the transaction against this transactionId in their iPay transaction history. If the payment was not successful, this field will be null.
transactionTime String If the payment is successful, this field will have the timestamp of the transaction. In case the payment was not successful, this field will be null.