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
MethodPOST
Expected Request Content Typeapplication/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 codeBody
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 nameTypeMandatory?Details
amountNumberYesThe 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.
referenceIdStringYesA 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
descriptionStringYesA 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.
successCallbackUrlStringYesA 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.
cancelCallbackUrlStringYesA 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 nameTypeDetails
messageStringTA message summarizing the status of the operation.
orderIdStringA 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.
paymentUrlStringThe 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.
referenceIdStringThe 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:
StatusstatusCodeMeaning
Created102The order has been created by merchant. No iPay member has taken any action on it yet. This order is still payable.
Successfully paid200The order has been successfully paid by an iPay member. This order is not payable anymore.
Payment cancelled by member445iPay member has cancelled the order by clicking on the “Cancel” button on iPay payment gateway. This order is not payable anymore.
Payment failed444iPay 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.
Expired410If 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 status500 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
MethodGET
Expected additional headers"Authorization" : "Bearer <API Key>"
Response Content Typeapplication/json
Response Content Type
Status codeBody
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 nameTypeMandatory?Details
orderIdStringYesThe 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..
referenceIdStringYesThe 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 nameTypeDetails
statusCodeStringA number denoting the current status of the order. All possible values of this code are listed in the Order statuses table.
statusStringA text denoting the current status of the order. All possible values of this status are listed in the Order statuses table.
orderIdStringTorderId of the order.
referenceIdStringreferenceId of the order.
transactionIdStringIf 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.
transactionTimeStringIf 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.