1. Intro

In this tutorial we will create a payment session. The purpose of the payment session is to verify the identity of the cardholder to prevent fraudulent transactions and refunds. The payment session reference is used when calling our Web SDK’s payment functions. 

To create the payment session, we will be making a request to Judopay’s Transaction API.

The ‘payment session reference’ returned from the API should be stored in the backend server, where it is ready to be used when calling our Web SDK’s payment functions.

‍

For this tutorial we will be using PHP as our server-side scripting language. You may use any server-side language you wish.

‍

2. Defining parts of the request.

To make a request to Judopay’s Transaction API we first need to define:

• The request headers
• The environment server URL
• The request endpoint
• The request body

Define an array of headers, which includes: content type, authorisation and the API version.

For authorisation, set this as Basic and then the base 64 encoding of your API token, colon, then your API secret.

// Base64 Encode the APIToken + Secret for the API Auth Header
$userEncode = base64_encode($APIToken.":".$APISecret);

‍

For the API version, ensure this is set to the most recent version, which can be found in our documentation.

To check the latest API version, visit Judopay’s Transaction API reference documentation.

Define the end-point, /payment-session.

//Setting the endpoint
$endpoint="/paymentsession";

‍

Define the Judopay API server URL, depending on the environment; where api-sandbox.judopay is for the sandbox environment, and api.judopay is for the live environment.

//Setting the API server url with the endpoint
$environment = "https://api-sandbox.judopay.com".$endpoint;

‍

Add the end-point to the end of the Judopay API URL.

Define an array which includes: your judoId, the transaction amount, the transaction currency, a payment reference and a consumer reference.

// Setting the data for the request's payload
$data=array(
'judoId' => $judoId, //Unique merchant/location ID supplied by Judopay
'amount' => $amount,
'currency' => $currency,
'yourPaymentReference' => $yourPaymentReference, //Unique reference for this payment
'yourConsumerReference' => $yourConsumerReference //Unique reference to anonymously identify your customer
);

‍

Convert the format of this array to JSON.

// Convert the data array to JSON
$requestPayload=json_encode($data);

‍

This will be used as the request body.

Please note, all the values used here must also be used later, when calling other Web SDK functions, such as invokePayment().

If any of these values are different, it will cause an error.

‍

3. Making a request to Judopay's Transaction API

Now we pull together everything we have defined, to make a POST request to Judopay’s Transaction API payment-session end-point.

//Making a POST request to Judopay's API
$ch = curl_init($environment);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_FRESH_CONNECT, TRUE);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS,$requestPayload);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($ch);

‍

4. Handling the API resonse.

// Decode the JSON reply
$obj = json_decode($response);

//Check if response contains the reference
if(isset($obj->reference)){
   $reference = $obj->reference; //store value so it can be accessed later (when calling WebSDK functions)
   echo $reference;
}

//Handle the API error
else {
   $errorMessage = $obj->message;
echo $errorMessage;

‍

If the request is successful, you should receive an object containing a reference and the reference expiry date.
If unsuccessful, you should receive an error response from the API.

• This is an object containing an error message, along with further details about the error.

Judopay’s Transaction API reference documentation also contains information on the expected responses from the API calls, along with the fields required for the request body.

If the request was successful, extract the reference value from the response object.

• Store the payment-session reference in your backend server.
• This payment-session reference will be used later, to populate the payment-session parameter when calling the Web SDK’s payment functions.

If the request was not successful, handle the API error accordingly.

For more information on the format of the API error responses, head to our Web SDK documentation and see the section, Web SDK error responses.
Here it describes the fields, that make up the API error response object.