Direct API Documentation

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 *

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

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

// You can call our API following curl post example
$url = "https://portal.gatewaypay.io/api/transaction";
$key = "Your API Key";
// Fill with real customer info
$data = [
    'first_name' => 'First Name',
    'last_name' => 'Last Name',
    'address' => 'Address',
    'customer_order_id' => 'ORDER-78544646461235',
    'country' => 'US',
    'state' => 'NY', // if your country US then use only 2 letter state code.
    'city' => 'New York',
    'zip' => '38564',
    'ip_address' => '192.168.168.4',
    'email' => 'test@gmail.com',
    'country_code' => '+91',
    'phone_no' => '999999999',
    'amount' => '10.00',
    'currency' => 'USD',
    'card_no' => '4242424242424242',
    'ccExpiryMonth' => '02',
    'ccExpiryYear' => '2026',
    'cvvNumber' => '123',
    'response_url' => 'https://yourdomain.com/callback.php',
    'webhook_url' => 'https://yourdomain.com/notification.php',
];

$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['status']) && $respsonseData['status'] == '3d_redirect') {
    header("Location: ".$responseData['redirect_3ds_url']);
} elseif(isset($responseData['status']) && $respsonseData['status'] == 'success') {
    echo "your transaction was approved.";
    print_r($responseData);
} else {
    echo "your transaction was declined";
    print_r($responseData);                    
}

Response Codes

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

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 of validation errors in request, response will be like:

{
    "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

This is successful transaction response

{
    "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"
        }
    }
}

Declined Response

This is the declined transaction response

{
    "responseCode": "0",
    "responseMessage": "Card not supported for testing.",
    "data": {
        "transaction": {
            "order_id": "ODRNCOK1683713972T5IVS7",
            "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"
        }
    }
}

3Ds secure Json Response type

If the response returns “status”:"3d_redirect” need to redirect the “redirect_3ds_url”

Response After 3DS

After 3D secure is completed, the user will be redirected to merchant website.

If transaction will be successful, the user will redirect to ”response_url” with response in query string similar to 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 be redirected to “response_url” with response in query string as follows:

https://portal.gatewaypay.io?responseCode=0&responseMessage=Card%not%supported%for%testing.&order_id=ODRDX3Y1683876328LBIJA1&customer_order_id=TX121212

{
    "responseCode": "7",
    "responseMessage": "Please redirect to 3dsUrl.",
    "3dsUrl": "https://portal.gatewaypay.io/payment/test-transaction/SDZSOO1683713932",
    "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": "+44898989898",
            "address": "Test",
            "zip": "123456",
            "city": "Test",
            "state": "Test",
            "country": "GB"
        }
    }
}

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 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": "787878778",
      "address": "Testing address",
      "zip": "676776",
      "city": "Test",
      "state": "Test",
      "country": "Test"
    },
    "card": {
        "card_no": "424242XXXXXX4243",
        "ccExpiryMonth": "05",
        "ccExpiryYear": "2023",
        "cvvNumber": "XXX"
    }
  }
}