Pay with tokenization

Introduction

Tokenization allows you to store payment details in exchange for a token. The token replaces the payment details in the transaction request.

This toke could be used to process transactions directly without using payment card data again.

How it works :

From a technical point of view, you have to get this integration done within your application with two simple calls to our API. The two calls to achieve this will be:

Call createCardTokenization endpoint (step one):
This step will simply return a token for specific credit card data to be used directly in the payment step. You can call it once and store the information at your end, then use that information in the next call. At the step, you can save created tokens at your end to send it later in the next step. (This step if you are authorized to create collect card data form, rather than this you can use the next step)
Call createCardTokenScreen endpoint (step two):
This step enables you to generate an URL contains collect credit card data form to save card data (check below screen), this URL hosted at Fawaterak end to be used in IFrame at your end or you can redirect customers to it.

After the customer clicks save, Fawaterak collects the data and generates a token, we are sending the generated token back to your end using a WebHook you provides at fawaterk dashboard (check below screen), you can save that token at your end to be used later at direct payment transactions.

Call createTokenizationPayRequest endpoint (step three):
This step will simply will process the payment transaction using the provided token.

Samples :

Step one (Create token)

Create token request example :

<?php
$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://staging.fawaterk.com/api/v2/createCardTokenization',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
    "order": {
        "currency": "EGP"
    },
    "customerData": {
        "customer_unique_id": "222111333",
        "customer_first_name": "Fname",
        "customer_last_name": "Lname",
        "customer_email": "[email protected]",
        "customer_phone": "01111111111"
    },
    "cardData": {
        "card_number": "5123450000000008",
        "expire_year": "2027",
        "expire_month": "12",
        "sec_code": "100"
    }
}',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'Authorization: Bearer d83a5d07aaeb8442dcbe259e6dae80a3f2e21a3a581e1a5acd'
  ),
));
$response = curl_exec($curl);
curl_close($curl);

var axios = require('axios');
var data = JSON.stringify({
    "order": {
        "currency": "EGP"
    },
    "customerData": {
        "customer_unique_id": "222111333",
        "customer_first_name": "Fname",
        "customer_last_name": "Lname",
        "customer_email": "[email protected]",
        "customer_phone": "01111111111"
    },
    "cardData": {
        "card_number": "5123450000000008",
        "expire_year": "2027",
        "expire_month": "12",
        "sec_code": "100"
    }
});

var config = {
  method: 'post',
  url: 'https://staging.fawaterk.com/api/v2/createCardTokenization',
  headers: { 
    'Authorization': 'Bearer d83a5d07aaeb8442dcbe259e6dae80a3f2e21a3a581e1a5acd', 
    'Content-Type': 'application/json'
  },
  data : data
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

curl --location 'https://staging.fawaterk.com//api/v2/createCardTokenization' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer d83a5d07aaeb8442dcbe259e6dae80a3f2e21a3a581e1a5acd' \
--data-raw '{
    "order": {
        "currency": "EGP"
    },
    "customerData": {
        "customer_unique_id": "222111333",
        "customer_first_name": "Fname",
        "customer_last_name": "Lname",
        "customer_email": "[email protected]",
        "customer_phone": "01111111111"
    },
    "cardData": {
        "card_number": "5123450000000008",
        "expire_year": "2027",
        "expire_month": "12",
        "sec_code": "100"
    }
}'

create token response :

{
    "status": "success",
    "token": "9731673377207107",
    "cardNumber": "512345xxxxxx0008"
}

Request parameters:

Parameter	Type	Description
order.currency	String	Currency code.	Mandatory
customerData.customer_unique_id	String	Your customer unique identifier at your system	Mandatory
customerData.customer_first_name	String	customer first name
customerData.customer_last_name	String	customer last name
customerData.customer_email	String	customer email
customerData.customer_phone	String	customer mobile
cardData.card_number	String	Card number	Mandatory
cardData.expire_year	String	Card expiry Year.	Mandatory
cardData.expire_month	String	Card expiry month.	Mandatory
cardData.sec_code	String	Card CCV.	Mandatory

Step two (Create card data screen)

Create card data screen request example :

<?php
$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://staging.fawaterk.com/api/v2/createCardTokenScreen',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
    "order": {
        "currency": "EGP"
    },
    "customerData": {
        "customer_unique_id": "222111333",
        "customer_first_name": "Fname",
        "customer_last_name": "Lname",
        "customer_email": "[email protected]",
        "customer_phone": "01111111111"
    },
    "redirectionUrls": {
        "success_url": "https://domain.com/success",
        "fail_url": "https://domain.com/fail"
    }
}',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'Authorization: Bearer d83a5d07aaeb8442dcbe259e6dae80a3f2e21a3a581e1a5acd'
  ),
));
$response = curl_exec($curl);
curl_close($curl);

var axios = require('axios');
var data = JSON.stringify({
    "order": {
        "currency": "EGP"
    },
    "customerData": {
        "customer_unique_id": "222111333",
        "customer_first_name": "Fname",
        "customer_last_name": "Lname",
        "customer_email": "[email protected]",
        "customer_phone": "01111111111"
    },
    "redirectionUrls": {
        "success_url": "https://domain.com/success",
        "fail_url": "https://domain.com/fail"
    }
});

var config = {
  method: 'post',
  url: 'https://staging.fawaterk.com/api/v2/createCardTokenScreen',
  headers: { 
    'Authorization': 'Bearer d83a5d07aaeb8442dcbe259e6dae80a3f2e21a3a581e1a5acd', 
    'Content-Type': 'application/json'
  },
  data : data
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

curl --location 'https://staging.fawaterk.com//api/v2/createCardTokenScreen' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer d83a5d07aaeb8442dcbe259e6dae80a3f2e21a3a581e1a5acd' \
--data-raw '{
    "order": {
        "currency": "EGP"
    },
    "customerData": {
        "customer_unique_id": "222111333",
        "customer_first_name": "Fname",
        "customer_last_name": "Lname",
        "customer_email": "[email protected]",
        "customer_phone": "01111111111"
    },
    "redirectionUrls": {
        "success_url": "https://domain.com/success",
        "fail_url": "https://domain.com/fail"
    }
}'

Create card data screen response :

Hint: The generated link has expiration time 10 min, after that the link will be redirected to the fail_url in the request body. Also, it saving card failed once! the link won't be valid again.

{
    "status": "success",
    "redirectUrl": "https://staging.fawaterk.com/nbe/storeToken/19941166e94728a4ad6ef3b19e6bfbe31f96bcacfb6f4b4b3804"
}

Created token Webhook request body:

{
    "customerUniqueId": "222111333",
    "customerCard": "512345xxxxxx0008",
    "customerCardToken" : "9731673377207107"
    "hashKey": "f59665d4077............ea2",
    "cardBrand": "MASTERCARD",
    "cardTokenUniqueId": "2345"
}

hashKey here is used to validate the callback is from Fawaterak side,

hashKey generation uses HMAC SHA256 mechanism, you should generate the hash from your side and it is implemented as explained below to compare it with ours:

function generateHashKey($data){
    $secretKey = "FAWATERAK_VENDOR_KEY";
    $queryParam = "customerUniqueId=XYZ&customerCardToken=XYZ";
    $hash = hash_hmac( 'sha256' , $queryParam , $secretKey ,false);
    return $hash;
}

Step three (pay with token)

Pay with token example :

<?php
$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://staging.fawaterk.com/api/v2/createTokenizationPayRequest',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
    "order": {
        "amount": "1000",
        "currency": "EGP"
    },
    "customerData": {
        "customer_token": "9731673377207107"
    }
}',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'Authorization: Bearer d83a5d07aaeb8442dcbe259e6dae80a3f2e21a3a581e1a5acd'
  ),
));
$response = curl_exec($curl);
curl_close($curl);

var axios = require('axios');
var data = JSON.stringify({
    "order": {
        "amount": "1000",
        "currency": "EGP"
    },
    "customerData": {
        "customer_token": "9731673377207107"
    }
});

var config = {
  method: 'post',
  url: 'https://staging.fawaterk.com/api/v2/createTokenizationPayRequest',
  headers: { 
    'Authorization': 'Bearer d83a5d07aaeb8442dcbe259e6dae80a3f2e21a3a581e1a5acd', 
    'Content-Type': 'application/json'
  },
  data : data
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

curl --location 'https://staging.fawaterk.com//api/v2/createTokenizationPayRequest' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer f59665d40772c9c47156cd0bff453b85e489306e849c27eea2' \
--data '{
    "order": {
        "amount": "1000",
        "currency": "EGP"
    },
    "customerData": {
        "customer_token": "9731673377207107"
    }
}'

Pay with token response :

{
    "status": "success",
    "transaction_id": 1011767
}

Delete customer token

Delete customer token example :

<?php
$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://staging.fawaterk.com/api/v2/deleteCustomerToken',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
    "customerUniqueId":"222111333"
    "cardTokenUniqueId":"2345"
}',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'Authorization: Bearer d83a5d07aaeb8442dcbe259e6dae80a3f2e21a3a581e1a5acd'
  ),
));
$response = curl_exec($curl);
curl_close($curl);

var axios = require('axios');
var data = JSON.stringify({
    "order": {
        "amount": "1000",
        "currency": "EGP"
    },
    "customerData": {
        "customer_token": "9731673377207107"
    }
});

var config = {
  method: 'post',
  url: 'https://staging.fawaterk.com/api/v2/createTokenizationPayRequest',
  headers: { 
    'Authorization': 'Bearer d83a5d07aaeb8442dcbe259e6dae80a3f2e21a3a581e1a5acd', 
    'Content-Type': 'application/json'
  },
  data : data
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

curl --location 'https://staging.fawaterk.com//api/v2/createTokenizationPayRequest' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer f59665d40772c9c47156cd0bff453b85e489306e849c27eea2' \
--data '{
    "order": {
        "amount": "1000",
        "currency": "EGP"
    },
    "customerData": {
        "customer_token": "9731673377207107"
    }
}'

Delete customer token response :

{
    "status": "success",
    "message": "token deleted
}