card-payment Tokenization

Tokenization is a feature that can be used through our API to save your client's credit card encrypted and hashed into a unique identifier token which is called card_token. This token contains alphanumeric and special characters like (+/\|). If you save a card token connected to your client's account, your client won't have to enter his card details on each purchase.

The card token has an expiration date: Issued token will become no longer valid after six months, or when you request deactivate card token API.

Tokenization is available for credit card payments and multi-currency credit card payments. You can use just a credit card for Tokenization.

How to generate card token:

The card token is generated just by passing the save_token with true value to the Standard Checkout API. The card token is returned when a payment transaction is successful, and is shown in the query parametres in the URL of the success page. Using the card_token, to collect new payments becomes very simple to achieve.

Collect Tokenized Payment API

The following endpoint is used to request the collect a new payment in your (backend) server.

https://api.fatora.io/v1/payments/collect-payment
curl -X POST 'https://api.fatora.io/v1/payments/collect-payment' \
--header 'Content-Type: application/json' \
--header 'api_key:  E4B73FEE-F492-4607-A38D-852B0EBC91C9' \
--data-raw '{
    "card_token" : "123456789",
    "order_id" : "123456789",
    "amount" : 123.45
}'
 'https://api.fatora.io/v1/payments/collect-payment',
  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_HTTPHEADER => array(
    'Content-Type: application/json',
    'api_key:  E4B73FEE-F492-4607-A38D-852B0EBC91C9'
  ),
  CURLOPT_POSTFIELDS =>'{
    "card_token" : "123456789",
    "order_id" : "123456789",
    "amount" : 123.45
}'

));

$response = curl_exec($curl);

curl_close($curl);
echo $response;
using (var httpClient = new HttpClient())
{
    using (var request = new HttpRequestMessage(new HttpMethod("POST"), "https://api.fatora.io/v1/payments/collect-payment"))
    {
        request.Headers.Add("api_key", "E4B73FEE-F492-4607-A38D-852B0EBC91C9");
        request.Content.Headers.ContentType = MediaTypeHeaderValue.Parse("application/json");
        TokenizPayment tokenizPayment = new TokenizPayment(){
            {
                card_token = "123456",
                order_id = "123456",
                amount = 123.45
            };

        string payload = JsonConvert.SerializeObject(payment);
        request.Content = new StringContent(payload);
        var response = httpClient.SendAsync(request);
    }
}
{
status: "SUCCESS" | "FAILURE",
"result": {
    "status_code" : XXX,
    "transaction_id": XXXX,
    "auth_code" : XXX,
    "mode" : XXXX,
    "description" : XXXXXXXXX
} }

Try it now: Collect tokenized payment API

Header Parameters

Header Value
api_key REQUIRED Use the valid API key of your Fatora account. Read more information about Authentication.
Content-Type REQUIRED application/json

Request Body

Parameter Description
card_token REQUIRED

stringIt is recieved after successfull payment when pass save_token=true in Standard Checkout API.
You must keep this token for future requests.

order_id REQUIRED stringA unique identifier for order in your application
amount OPTIONAL decimalIndicates the amount of the payment. If it does not provided, The same amount of first payment related to this card token will be paid (deduct).

Response

The successful request returns the HTTP 200 OK status code and a JSON response body that shows details about if Fatora could collect new payment from the client. The possible values for the status field are "SUCCESS" and "FAILURE", the status "SUCCESS" means that the collecting process was processed successfully. the status is "FAILURE" means the collecting process has failed for one of the following reasons:

  1. Token invalid, this happens when the token is expired.
  2. Transaction Blocked, this happens when not all parameters of risk and checks are passed.
  3. Transaction Declined, Contact issuing Bank declined.
  4. Transaction Declined, Insufficient credit - insufficient+Funds.

Response Schema: application/json
status string the status of response. enum values
[SUCCESS,FAILURE]
result arrayThe result array contins the following values:
  • status_code string, xxxxxxxxxxxxxxx.
  • transaction_id string, The transaction id of payment issued from the bank.
  • auth_code string, The auth_code of payment issued from the bank.
  • mode string, The value of your integration mode, enum values ["test", "live"].
  • description string, Additional information about transaction.

Otherwise if there was a problem with your request, you'll receive an error response such as 400 status code, and the response will include an error object describing why this request failed.

Response Schema: application/json
status string The status of response.
error object:
  • error_code string, the naumber of error: e.g: 400, For more information
    see Response Code
  • description string, the description of error: e.g: bad request

no-credit-cards Deactivate Card Token API

The following endpoint is used when you need to stop collecting new payments using card_token.

Card Token becomes disabled automatically when the client card expires, so you have to get a new card token from the client.
https://api.fatora.io/api/v1/payments/deactivate-card-token
curl -X POST 'https://api.fatora.io/api/v1/payments/deactivate-card-token' \
--header 'Content-Type: application/json' \
--header 'api_key:  E4B73FEE-F492-4607-A38D-852B0EBC91C9' \
--data-raw '{
    "card_token" : "123456789",
    "order_id" : "123456789"
}'
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.fatora.io/api/v1/payments/deactivate-card-token',
  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_HTTPHEADER => array(
    'Content-Type: application/json',
    'api_key:  E4B73FEE-F492-4607-A38D-852B0EBC91C9'
  ),
  CURLOPT_POSTFIELDS =>'{
    "card_token" : "123456789",
    "order_id" : "123456789"
}'
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;
using (var httpClient = new HttpClient())
{
    using (var request = new HttpRequestMessage(new HttpMethod("POST"), "https://api.fatora.io/api/v1/payments/deactivate-card-token"))
    {
        request.Headers.Add("api_key", "E4B73FEE-F492-4607-A38D-852B0EBC91C9");
        request.Content.Headers.ContentType = MediaTypeHeaderValue.Parse("application/json");

        TokenizPayment tokenizPayment = new TokenizPayment(){
            {
                card_token = "123456",
                order_id = "123456"
            };

        string payload = JsonConvert.SerializeObject(payment);
        request.Content = new StringContent(payload);
        var response = httpClient.SendAsync(request);
    }
}
{ "result": 1
}

Try it now: Deactivate card token API

Request Body

Parameter Description
card_token REQUIRED

string The card token issued from Fatora payment gateway. You must keep this token for future requests.

order_id REQUIRED stringA unique identifier for order in your application

Response

The successful request returns the HTTP 204 OK status code with NO Content.

Otherwise if there was a problem with your request, you'll receive an error response such as 400 status code, and the response will include an error object describing why this request failed.

Response Schema: application/json
status string The status of response.
errors object:
  • error_code string, the naumber of error: e.g: 400, For more information
    see Response Code
  • description string, the description of error: e.g: bad request
technical-support

🛠️ Technical Support