Sign In     Back

Hosted API Documentation

How to integrate Hosted API

This is Hosted Page API documentation. In this API, User details will be sent to GatewayPay Server with curl request, where as card details will be loaded to GatewayPay server. Follow the below steps to integrate hosted page API with GatewayPay.

Authorization

Authorization

To authenticate the user we have to pass API-KEY in our request header. Please find below how we can pass API-KEY in header during request.

Authorization: Bearer 1|3WIXuhS9eYVh1vFjG8JoyfztPTqeE9EVXyeJS77676

If we do not pass API-KEY in header then we will get this error in our response.

 {
    "responseCode": "6",
    "responseMessage": "Unauthorised request, please pass API Key in Header",
    "data": {
        "transaction": {
            "order_id": null,
            "customer_order_id": "TX121212",
            "amount": "12.50",
            "currency": "USD"
        },
        "client": {
            "first_name": "Test",
            "last_name": "Test",
            "email": "test@gmail.com",
            "phone_no": "+4477676767",
            "address": "Test",
            "zip": "123456",
            "city": "Test",
            "state": "Test",
            "country": "GB"
        }
    }
}

Request

Request Parameter *

The following parameters should be sent to the request.

Paramters Required Data Type Description
first_name Yes String First Name from (Credit/Debit) Card
last_name Yes String Last Name from (Credit/Debit)Card
address Yes String Full Address of User
country Yes String 2 letter Country, eg US
state Yes String State Name, 2 letter for US states, eg CA
city Yes String Valid City name
zip Yes String Valid Zip Code
ip_address Yes String IP address of user device, eg 56.85.205.246
email Yes String Valid Email address of User
country_code No String Valid Country Code of User
phone_no Yes String Valid Phone Number of User
amount Yes Decimal Amount Value
currency Yes String 3 Digit format, eg USD
customer_order_id No String Customer order id generated from user side.
response_url Yes String Response URL where we redirect after transaction process completed.
webhook_url No String POST URL where we send webhook notification.
Testing URL -
https://portal.gatewaypay.io/api/test/hosted/transaction

Live URL -
https://portal.gatewaypay.io/api/hosted/transaction
Method - POST
Send Curl request

Send a Curl request with all the parameters provided to the URL below. We encourage all users to please provide all the necessary fields. All credit card fields in the request parameters must be provided and must be the same information indicated in the cardholder's credit card/billing information.

Response

After you redirect to url payment_redirect_url, a form will be loaded over GatewayPay payment page. You will need to fill credit card details if asked

If making request in testing URL, then it will ask for Credit card details. Use this bellow testing card data

Testing Card data
Non 3DS Testing Card 
card_no : 4242 4242 4242 4242
ccExpiryMonth : 02
ccExpiryYear : 2026
cvvNumber : 123
3DS Testing Card 
card_no : 4000 0000 0000 3220
ccExpiryMonth : 02
ccExpiryYear : 2026
cvvNumber : 123

Response Codes

You will get some response codes in our JSON response. when you hit our API.

These are the response code with their meanings:
1.) "0" : "Fail" => It means transaction get declined. 
2.) "1" :"Success" => It means transaction processed successfully.
3.) "2" :"Pending" => It means user not complete the transaction process or there is some other issue that's why transaction got stuck in between.
4.) "3" :"Cancelled" => It means user cancelled the transaction.
5.) "4" :"to_be_confirm" => It means when there is some delay in bank response to confirm the transaction status.
6.) "5" :"Blocked" => It means when transaction blocked due to restricted country or per day transaction or card limit.
7.) "6" :"Unathorized" => It means when user pass wrong API-KEY.
8.) "7" :"Redirected" => It means redirect user to 3ds link to complete the transaction.
9.) "8" :"Abandoned" => It means the user abandoned the transaction.

Validation Errors

If in case there will be validation errors in the request, the response will be similar to the following:


{
    "responseCode": "6",
    "responseMessage": "The first name field is required.",
    "data": {
        "transaction": {
            "order_id": null,
            "customer_order_id": "TX121212",
            "amount": "12.50",
            "currency": "USD"
        },
        "client": {
            "first_name": null,
            "last_name": "Test",
            "email": "test@gmail.com",
            "phone_no": "+4478777877",
            "address": "Test",
            "zip": "123456",
            "city": "Test",
            "state": "Test",
            "country": "GB"
        }
    }
}

Successful Response

After a successful request, the response will be returned in JSON format.

Example 
{
    "responseCode": "1",
    "responseMessage": "Transaction processed successfully.",
    "data": {
        "transaction": {
            "order_id": "ODRPAE41683713959RTAT3J",
            "customer_order_id": "TX121212",
            "amount": "12.50",
            "currency": "USD"
        },
        "client": {
            "first_name": "Test",
            "last_name": "Test",
            "email": "test@gmail.com",
            "phone_no": "+44898989898",
            "address": "Test",
            "zip": "123456",
            "city": "Test",
            "state": "Test",
            "country": "GB"
        }
    }
}

If the request data contains a valid format, then the above response will be returned. You will need to redirect to “payment_redirect_url” for payment page before “valid_till”.

Response from GatewayPay

After Credit card form is completely filled up, the user must press the Pay button. This request will take some time, if user card has 3D secure feature enabled, it will also redirect the process to a 3D secure page, where user will be asked to input PIN or OTP if asked. After the entire process is complete, user will be redirected to the merchant website and will reflect the transaction status.

If transaction is successful, the user will be redirected to ”response_url” with the response in query string like the one below: 

https://portal.gatewaypay.io?responseCode=1&responseMessage=Test%20transaction%20processed%20successfully.&order_id=ODRDX3Y1683876328LBIJA1&customer_order_id=TX121212
If the transaction fails, the user will redirect as well to “response_url” with the response query string similar to the one below: 
https://portal.gatewaypay.io?responseCode=0&responseMessage=Card%not%supported%for%testing.&order_id=ODRDX3Y1683876328LBIJA1&customer_order_id=TX121212

Webhooks

Webhooks events are transaction callbacks that sends notifications of transaction to the merchant server. If you want to receive webhooks, then send "webhook_url" parameter with initial request(See above request example).

Here are the simple explanation of each parameter:

1.) order_id : Transaction reference number of our system.
2.) customer_order_id: Merchant transaction reference.
3.) transaction_status: "success" / "fail" / "pending" / "blocked".
4.) reason: Response from the bank about transaction status.
5.) currency: Currency of the transaction.
6.) amount: Amount of the transaction.
7.) email: Email of the transaction.
8.) transaction_date: Date of the transaction.

Here are the example of webhook notification request:

{
  "responseCode": "1",
  "responseMessage": "Transaction processed successfully.",
  "data": {
    "transaction": {
      "order_id": "ODRU8RL1686230176CWZJQE",
      "customer_order_id": null,
      "amount": "11",
      "currency": "USD"
    },
    "client": {
      "first_name": "Test",
      "last_name": "GatewayPay",
      "email": "tech@gatewaypay.io",
      "phone_no": "8676767676",
      "address": "Testing address",
      "zip": "676776",
      "city": "Test",
      "state": "Test",
      "country": "Test"
    },
    "card": {
        "card_no": "424242XXXXXX4243",
        "ccExpiryMonth": "05",
        "ccExpiryYear": "2023",
        "cvvNumber": "XXX"
    }
  }
}