Integrate your applications with simple calls
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
}