Hosted Payment API V2

Prerequisite

Before implementing API V2 you need to follow below steps.

All server IPs must be whitelisted. Whitelist Ips
Also, make sure that webhook_url is not secured by any type of token (e.g. Bearer, JWT, Oauth2), and will be able to get external requests from servers.

How to integrate API V2

This API can be implemented with all of the platforms. For that, send a request with payload in JSON format to our API Endpoint.

Create Test Transaction

To make test transactions you need to make a POST request to the following url :

https://portal.gatewaypay.io/api/v2/test/transaction

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 Parameters *

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
email	Yes	String	Valid Email address of User
amount	Yes	Decimal	Amount Value
currency	Yes	String	3 Digit format, eg USD
ip_address	Yes	String	IP address of user device, eg 56.85.205.246
address	No	String	Full Address of User
country	No	String	2 letter Country, eg US
state	No	String	State Name, 2 letter for US states, eg CA
city	No	String	Valid City name
zip	No	String	Valid Zip Code
phone_no	No	String	Valid Phone Number of User
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.

Non-3DS Testing card data -

card_no : 4242 4242 4242 4242
ccExpiryMonth : 02
ccExpiryYear : 2026
cvvNumber : 123

3DS Testing card data -

card_no : 4000 0000 0000 3220
ccExpiryMonth : 02
ccExpiryYear : 2026
cvvNumber : 123

Note : Non required parameters are not necessary for this request. But you may need those parameters in further transaction process. Which depends on upon Gateway. Filling non required parameters in this request will fill corresponding fields in further process automatically and won't need to be filled again.

API Endpoint -
https://portal.gatewaypay.io/api/v2/transaction

Test API Endpoint -
https://portal.gatewaypay.io/api/v2/test/transaction

Method - POST

API Request (curl)

$url = "https://portal.gatewaypay.io/api/v2/test/transaction";

$data = [
    'first_name' => 'First Name',
    'last_name' => 'Last Name',
    'email' => 'test@gmail.com',
    'amount' => '10.00',
    'currency' => 'USD',
    'response_url' => 'https://yourdomain.com/callback.php',
    'address' => 'Address',
    'country' => 'US',
    'state' => 'NY',
    'city' => 'New York',
    'zip' => '38564',
    'phone_no' => '999999999',
    'ip_address' => '56.85.205.246'
];

$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_POST, 1);
curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_HTTPHEADER,[
    'Content-Type: application/json',
    'Authorization: Bearer 1|J3WoPkRDtCRQzyoYUwBtdYGG9JlBN0HwYZ66656'
]);
$response = curl_exec($curl);
curl_close($curl);

$responseData = json_decode($response);

if(isset($responseData['responseCode']) && $respsonseData['responseCode'] == '7') {
    header("Location: ".$responseData['3dsUrl']);
} elseif(isset($responseData['responseCode']) && $respsonseData['responseCode'] == '1') {
    echo "your transaction was approved.";
    print_r($responseData);
} else {
    echo "your transaction was declined";
    print_r($responseData);
}

Response

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

Validation Errors

Validation errors in request will produce response like:

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

Successful 3Ds secure Response

If the response contains "status":"3d_redirect" then you need to redirect the your request to "redirect_3ds_url". Which will be the merchant website.

{
    "responseCode": "7",
    "responseMessage": "Please redirect to 3dsUrl.",
    "3dsUrl": "https://portal.gatewaypay.io/api/v2/test-checkout/ODRCT981687163034UWNHU11",
    "data": {
        "transaction": {
            "order_id": "ODRCT981687163034UWNHU1",
            "customer_order_id": null,
            "amount": "1",
            "currency": "USD"
        },
        "client": {
            "first_name": "GatewayPay",
            "last_name": "Test",
            "email": "test@gmail.com",
            "phone_no": null,
            "address": null,
            "zip": null,
            "city": null,
            "state": null,
            "country": "IN"
        }
    }
}

Response Codes

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.

Redirection

After successful response of the request, you will be redirected to the merchant website.

From there, you can choose Card, Bank or Crypto Currency to create your transaction.

Pay With Card

Pay With Bank

Pay With Crypto Wallet

Also, you can cancel and retry another method of transaction after selecting any of above method.

Create Transaction

To make transactions you need to make a POST request to the following url :

https://portal.gatewaypay.io/api/v2/transaction