Geidea Checkout

Overview

Our Checkout offering is a pre-built payment UI that offers the quickest way to integrate and start securely accepting payments. It allows you to accept popular payment methods through a single web front-end implementation.

Geidea Checkout supports both one-time payments and subscriptions for your customers - through a quick, easy and low-code integration into your website's checkout flow. It is very user-friendly and customizable.

Additional payment methods can be enabled without any extra development work - Geidea Checkout seamlessly handles all payment method flows complexity, including 3D Secure 2.0 authentication.

Step 1: Create a checkout session

The checkout session streamlines the payment process by allowing you to pre-configure the payment details and options for the session, and then simply open the Geidea checkout payment page to complete the transaction.

You can configure this resource with multiple options such as amount and currency, payment method selection priority, appearance, order details (items, summary, etc), and customer details.

Create Session Request

The create session endpoint requires basic authentication credentials where the merchant public key is used as the username and the API password as the password. Kindly check this section to find your access credentials.

🚧

Warning

Your API password is a secret key! It is important to never expose your API password in the front end of your application. Instead, store your API password securely on the server-side, and use a backend proxy to make API requests on behalf of your frontend application. This approach ensures that your API password is never exposed to the client side, reducing the risk of unauthorized access and data breaches.

To initiate an Initiate authentication API call, you will need to provide the following required fields.

ParameterDescription
amountThe total amount value of the payment. This parameter is required, and the format is a double - a number with 2 digits after the decimal point. For example 19.99
currencyThe currency of the payment. This is a 3-digit alphabetic code, following the ISO 4217 currency code standard. For example: SAR

List of available currencies:
SAR Saudi Riyal
EGP Egyptian Pound
AED UAE Dirham
QAR Qatari Rial
OMR Omani Rial
BHD Bahraini Dinar
KWD Kuwaiti Dinar
USD US Dollar
GBP UK Pound Sterling
EUR Euro

To enable multicurrency for your account - contact our support team.

You can find a full list of parameters which can be used with the Create Session API here.

Below is an example of executing a Create Session API call for payment of 10.00 SAR with the mandatory parameters.

curl -X POST https://api.merchant.geidea.net/payment-intent/api/v1/direct/session \
  -H 'Authorization: Basic <base64 encoded merchant public key and api password>' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 10.00,
    "currency": "SAR",
  }'
<?php

$url = "https://api.merchant.geidea.net/payment-intent/api/v1/direct/session";

$username = "<merchant_public_key>";
$password = "<api_password>";

$data = array(
    "amount" => 10.00,
    "currency" => "SAR"
);
$data_json = json_encode($data);

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Authorization: Basic ' . base64_encode("$username:$password"),
    'Content-Type: application/json',
));
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS,$data_json);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response  = curl_exec($ch);
curl_close($ch);

Below is an example of creating a session for payment of 10.00 SAR with some additional optional parameters, which we highly recommend you use in your integration.

curl -X POST https://api.merchant.geidea.net/payment-intent/api/v1/direct/session \
  -H 'Authorization: Basic <base64 encoded merchant public key and api password>' \
  -H 'Content-Type: application/json' \
  -d '{
  "amount": 10.00,
  "currency": "SAR",
  "callbackUrl": "https://www.example.com/callback",
  "merchantReferenceId": "ABC-123",
  "language": "ar"
  }'
<?php

$url = "https://api.merchant.geidea.net/payment-intent/api/v1/direct/session";

$username = "<merchant_public_key>";
$password = "<api_password>";

$data = array(
    "amount" => 10.00,
    "currency" => "SAR",
    "callbackUrl" => "https://example.com/payment-callback",
    "merchantReferenceId" => "ORDER-123",
    "language" => "ar"
);
$data_json = json_encode($data);

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Authorization: Basic ' . base64_encode("$username:$password"),
    'Content-Type: application/json',
));
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS,$data_json);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response  = curl_exec($ch);
curl_close($ch);

In the example above we have used the following parameters (in addition to amount and currency):

NameDescription
callbackUrlYou can provide a webhook URL, where Geidea will POST the full order information after each payment is completed in JSON format. This parameter is not required but is highly recommended.

For full information about webhooks, you can visit our [Webhooks page.](doc: webhooks)
merchantReferenceIdYou can provide your own unique reference ID using this parameter.
languageThis will load the Geidea Checkout form in the preferred language. The format is a 2-digit alphabetic code as a string.

Accepted values are:
en for English
ar for Arabic

Create Session Response

After sending the create session request in the example above - if your request is valid, then you will receive a response which includes a session object, with a session.id parameter inside. You will need to use this session.id later in order to start Geidea checkout.

Below is an example of a successful response you can expect to receive for the create session request above.

{
    "session": {
        "id": "a19f270e-363d-43cb-0dcb-08db0e9b791f",
        "amount": 10.00,
        "currency": "SAR",
        "callbackUrl": "https://www.example.com/callback",
        "expiryDate": "2023-02-19T14:40:19.8901413Z",
        "status": "Initiated",
        "merchantPublicKey": "b61637c9-da30-40ce-95e1-d08d1e90fc39",
        "language": "ar",
        "merchantReferenceId": "ABC-123",
    },
    "responseMessage": "Success",
    "detailedResponseMessage": "The operation was successful",
    "language": "EN",
    "responseCode": "000",
    "detailedResponseCode": "000"
}

The response includes your session expiryDate - each session by default expires after one hour. This is the timeframe in which you will need to start the Geidea Checkout flow. You can also see the already mentioned id of the session - which you must save and use in Step 3 of this flow.

Step 2: Set up Geidea Checkout

Next, embed our Geidea Checkout JavaScript library into your web checkout page HTML. In the example below, we've embedded the script into the section of our example checkout.html file.

<head>
  <!-- GeideaCheckout web script load section -->
  <script src="https://www.merchant.geidea.net/hpp/geideaCheckout.min.js"></script>
</head>

After you have embedded the Geidea Checkout JS library, you should initialize an instance of the GeideaCheckout payment object.

// initialize the payment object
const payment = new GeideaCheckout(onSuccess, onError, onCancel);

To initialize the payment object, you need to:

1. Provide reference to three callback event functions (onSuccess, onError, onCancel). After the payment process is completed, Geidea Checkout will redirect the customer back to the parent URL from where the checkout was started. One of the three methods will be triggered after the payment through the Geidea Checkout form is completed and the customer has returned. You must create a function for each of these events.

  • onSuccess: this callback event function is triggered after a payment has been successful. You can use this function to display a successful message to the customer to confirm that the payment order has been successful. The responseCode parameter in this case will always be '000' and the responseMessage will be 'Success'. You can see a full list of Response codes here.

  • onError: this callback event function is triggered when the parameters in your payment configuration (configurePayment) are invalid; or when there is a payment processing error which does not allow the order to continue.

  • onCancel: this callback function is triggered when your user clicks the 'Cancel' button on the Geidea Checkout form; or when the payment has timed out.

  • Geidea Checkout will call one of the three callback events based on the outcome of the customer payment. When one of the callback events is triggered, a JSON data object including information about the order is also sent to the event. This data object includes 6 parameters which can be used to display the result of the payment to your customer:

{
   "responseCode":"string",
   "responseMessage":"string",
   "detailResponseCode":"string",
   "detailResponseMessage":"string",
   "orderId":"GUID",
   "reference":"GUID"
}

2. Create the onSuccess, onError, and onCancel functions. You can determine how you would like the checkout flow to continue after payment has been completed - for example, you can display a successful or failed message to the customer, or you can redirect to a success or error page - you can create your functions as you like.

In the following example, each of the three functions is only alerting the order information after Geidea Checkout is completed:

// onSuccess function definition
let onSuccess = function(data) {
  alert("Success:" + "\n" +
  data.responseCode + "\n" +
  data.responseMessage + "\n" +
  data.detailResponseCode + "\n" +
  data.detailResponseMessage + "\n" +
  data.orderId + "\n" +
  data.reference);
}

// onError function definition
let onError = function(data) {
  alert("Error:" + "\n" +
  data.responseCode + "\n" +
  data.responseMessage + "\n" +
  data.detailResponseCode + "\n" +
  data.detailResponseMessage + "\n" +
  data.orderId + "\n" +
  data.reference);
}

//onCancel function definition
let onCancel = function(data) {
  alert("Cancel:" + "\n" +
  data.responseCode + "\n" +
  data.responseMessage + "\n" +
  data.detailResponseCode + "\n" +
  data.detailResponseMessage + "\n" +
  data.orderId + "\n" +
  data.reference);
}
  • The orderId parameter returned in the callback event data object is Geidea's unique ID assigned to every order. The format of this parameter is a GUID.

  • The reference parameter returned in the data object serves as an additional reference which can be used to help our support team find all the information about the payment process - in the case where an order was not created and the orderId is missing. The format of this parameter is a GUID.

Once you have completed steps 1 and 2, you are ready to start the Geidea Checkout payment.

Start the payment

After you have created your session, received your session.id, and initialized the payment object, you are ready to start the payment with Geidea Checkout.

To start the payment, you will need to use the startPayment method by passing the session.id which you received when you created the session in Step 1:

// initialize the payment object
const payment = new GeideaCheckout(onSuccess, onError, onCancel);

// start the payment
payment.startPayment(sessionId);

The startPayment method must be attached to an action on your web page - you can attach it to a 'Checkout' or a 'Pay' button, or you can use any preferred onClick event on your own web page.

After triggering the startPayment method, Geidea Checkout will appear as a modal/popup iframe on top of your web page by default. This is the recommended flow.

687

Based on your preference - you can start Geidea Checkout anywhere during your customer checkout flow - for example, you can choose to redirect to Geidea Checkout using your sessionId, or you can load the Geidea Checkout iframe in a previously defined empty <div> container.

Below is a basic example of a checkout.html page, which loads Geidea Checkout.

<!DOCTYPE html>
<html>
<head>
	<title>Geidea Checkout Example</title>
	<script src="https://www.merchant.geidea.net/hpp/geideaCheckout.min.js"></script>
	<script>
		function createAndStartPayment() {
			// Create a new XMLHttpRequest object
			var xhr = new XMLHttpRequest();

			// Set up the request
			xhr.open('POST', 'create_session.php');
			xhr.setRequestHeader('Content-Type', 'application/json');

			// Set up a function to handle the response
			xhr.onload = function() {
				if (xhr.status === 200) {
					// Get the response text
					var response = xhr.responseText.trim();

					// Check if the response is empty or not
					if (response.length > 0) {
						// Start the payment with the session ID
						startPayment(response);
					} else {
						alert('Error: Empty response from server');
					}
				} else {
					alert('Error: ' + xhr.statusText);
				}
			};

			// Set up a function to handle network errors
			xhr.onerror = function() {
				alert('Error: Network Error');
			};

            // Send the request with the JSON string
            var data = {
                amount: 10.00,
                currency: "SAR",
                callbackUrl: "https://www.example.com/callback",
                merchantReferenceId: "ABC-123",
                language: "ar",
            };
            xhr.send(JSON.stringify(data));
		}

		function startPayment(sessionId) {
			// Initialize GeideaCheckout
			var payment = new GeideaCheckout(onSuccess, onError, onCancel);

			// Start the payment
			payment.startPayment(sessionId);
		}

		// Define the onSuccess function
		let onSuccess = function(data) {
			alert('Success:' + '\n' +
			data.responseCode + '\n' +
			data.responseMessage + '\n' +
			data.detailedResponseCode + '\n' +
			data.detailedResponseMessage + '\n' +
			data.orderId + '\n' +
			data.reference);
		};

        // Define the onError function
		let onError = function(data) {
			alert('Error:' + '\n' +
			data.responseCode + '\n' +
			data.responseMessage + '\n' +
			data.detailedResponseCode + '\n' +
			data.detailedResponseMessage + '\n' +
			data.orderId + '\n' +
			data.reference);
		};

		// Define the onCancel function
		let onCancel = function(data) {
			alert('Payment Cancelled:' + '\n' +
			data.responseCode + '\n' +
			data.responseMessage + '\n' +
			data.detailedResponseCode + '\n' +
			data.detailedResponseMessage + '\n' +
			data.orderId + '\n' +
			data.reference);
		};
	</script>
</head>
<body>
	<button onclick="createAndStartPayment()">Geidea Checkout</button>
</body>
</html>

The checkout.html file above uses the following PHP script for creating a session.

<?php
// Replace with your actual merchant public key and API password
$username = "your_merchant_public_key";
$password = "your_api_password";

// Set the API endpoint URL
$url = "https://api.merchant.geidea.net/payment-intent/api/v1/direct/session";

// Retrieve the JSON string from the request body
$data = file_get_contents("php://input");

// Decode the JSON string into a PHP associative array
$data = json_decode($data, true);

// Access the values of the array
$amount = $data["amount"];
$currency = $data["currency"];
$callbackUrl = $data["callbackUrl"];
$merchantReferenceId = $data["merchantReferenceId"];
$language = $data["language"];

// Set the request data
$data = array(
    'amount' => $amount,
    'currency' => $currency,
    'callbackUrl' => $callbackUrl,
    'merchantReferenceId' => $merchantReferenceId,
    'language' => $language,
);

// Set the cURL options
$options = array(
    CURLOPT_URL => $url,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($data),
    CURLOPT_HTTPHEADER => array(
        "Content-Type: application/json",
        "Authorization: Basic " . base64_encode("$username:$password")
    ),
    CURLOPT_RETURNTRANSFER => true
);

// Initialize cURL
$ch = curl_init();

// Set cURL options
curl_setopt_array($ch, $options);

// Execute the cURL request
$response = curl_exec($ch);

// Check for errors
if (curl_errno($ch)) {
    $error_msg = curl_error($ch);
    curl_close($ch);
    die("cURL Error: $error_msg");
}

// Close the cURL session
curl_close($ch);

// Decode the JSON response
$response_data = json_decode($response, true);

// Check for errors in the response
if ($response_data["responseCode"] !== "000" || $response_data["detailedResponseCode"] !== "000") {
    die("Error: " . $response_data["detailedResponseMessage"]);
}

// Get the session ID from the response
$session_id = $response_data["session"]["id"];

// Output the session ID
echo $session_id;
?>