API Tokenization process

API Tokenization process

To consider

To invoke the payments api, the following aspects should be considered:
  1. Use the service on the endpoints:
    1. Sandbox: https://sandbox-checkout.greenpay.me/tokenize
    2. Production: https://checkout.greenpay.me/tokenize
  2. Get a session and token of a valid tokenization order (A session and token is valid within 30 minutes from the creation of the order). In order to create session and token you can check this article Create a tokenization order.

Step to use the service

1. Data structure

The json object with the card data must have the following structure.
  1. {
  2.     "card": {
  3.       "cardHolder": "cardholder name",
  4.       "expirationDate": {
  5.         "month": numberMonth,
  6.         "year": twoLastNumberOfYear
  7.       },
  8.       "cardNumber": "complete card number",
  9.       "cvc": "security code",
  10.       "nickname": "nickname, it has to be longer than 5 chars and shorter than 50 chars"
  11.     }
  12. }
The require params are the following:
  1. cardHolder: Card holder name
  2. expirationDate: Object with de card expiration date.
  3. cardNumber: Complete debit or credit card number.
  4. cvc: Security code.
  5. nickname: It has to be longer than 5 chars and shorter than 50 chars.


2. Encrypt the card data

For security, the card data must be encrypted. To encrypt this data, the algorithm “AES-CTR-128” have to be used. If this information is not encrypted with this algorithm the tokenization service will reject the request.

Below you can find the steps to encrypt the card information.
  1. Dynamically generate a pair of AES keys (Key, Counter), which will be used to encrypt the card information.
    1. Each key is a 16 bytes array.
    2. The key contains the data to encrypt in AES
    3. The counter is the initialization vector for AES CTR mode. 
  2. Encrypt the JSON object with the card data, and convert the encryption result to hexadecimal format.
    1. The string in hexadecimal format corresponds to the value “Id” that must be sent in the payment request “body”
    2. The “Id” value that must be sent in the payment request body, corresponds to the string obtained when encrypting the JSON containing the card information.
  3. Encrypt with RSA the AES keys (key, counter) with the public key provided by “Greenpay support team
    1. The string in base64 format obtained from encrypting the AES key pair, corresponds to the value “Ik” that must be sent in the payment request “body”
    2. The value “Ik” that must be sent in the payment request “body” corresponds to the base64 encoding of the AES key encryption

2.1 Encryption example

  1. C# encryption: Two examples of card data encryption with external libraries and BouncyCastle. Check the example in C# encryption.
  2. JavaScript encryption: The card data encryption with javascript works with aes-js and jencrypt libraries. The following is the code example.
    <!---->
    <!doctype html>
    <html>
    <head>
    <title>GP LD LK</title>
    <script type="text/javascript" src="https://cdn.rawgit.com/ricmoo/aes-js/e27b99df/index.js"></script>
    <script type="text/javascript">
    //init jsencryp
    var encrypt = new JSEncrypt();
    //add publib key provided byu greenpay with no \n
    encrypt.setPublicKey("MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCT9eWb6pWcK7Pr5JoUrvfNRgxEcQcXOdp/WtQlCCX35xFpM4W3N5aeqSTa3ZRG9e8sPH4NcO69kO21zVRxoaAYTiARfGPTbR8c/Y/osl9J9u6jWbolXALuDQNwTWJyyScHvjr6fV15q0aOJWETegk2GxSo9NE+/ecrd9WFEb8XcQIDAQAB");

    $(function() {
    // cardDataObject is the object that must be encrypted when you are going to create a token
    var cardDataObject = {
    "card":{
    "cardHolder": "Tico payment user", //must have more tha 5 chars
    "expirationDate": {
    "month": 12,
    "year": 23
    },
    "cardNumber": "4242424242424242",
    "cvc": "123",
    "nickname": "nickname" //more than 5 chars and less tan 50 chars
    }
    };

    // encrypt the card data and print the log in console
    var cardDataEcrypted = pack(cardDataObject, undefined);
    console.log('Card data encrypted:', JSON.stringify(cardDataEcrypted));
    });

    function pack(obj, pair_) {
    var pair = (pair_ !== undefined) ? pair_ : this.generateAESPairs();
    var textBytes = aesjs.utils.utf8.toBytes(JSON.stringify(obj));
    var aesCtr = new aesjs.ModeOfOperation.ctr(pair.k, new aesjs.Counter(pair.s));
    var encryptedBytes = aesCtr.encrypt(textBytes);
    var encryptedHex = aesjs.utils.hex.fromBytes(encryptedBytes);
    var returnObj = {
    ld:encryptedHex,
    lk:encrypt.encrypt(JSON.stringify(pair))
    };
    return returnObj;
    }

    function generateAESPairs () {
    var key = []
    var iv = 0;
    for (var k = 0; k < 16; k++) {
    key.push(Math.floor(Math.random() * 255))
    }
    for (var k = 0; k < 16; k++) {
    iv = Math.floor(Math.random() * 255)
    }
    return {
    k: key,
    s: iv
    }
    }
    </script>
    </head>
    <body>
    </body>
    </html>

2.2 Encryption result

The result of the encryption process is an ld and lk strings. An JSON object have to be created with these values as the following example:
  1. {
  2.     "session": "session from create tokenization order",
  3.     "ld": "ld from encryption process",
  4.     "lk": "lk from encryption process"
  5. }

3. Send a POST request with the encrypted data

To send de POST request correctly, check the following steps:
  1. Set de object that contains the session from tokenization order and the encrypted datas as the request body.
    {
    "session": "session from create tokenization order",
    "ld": "ld from encryption process",
    "lk": "lk from encryption process"
    }
  2. Set a new header called liszt-token. The value of this header is the token from tokenization order.
    "liszt-token":"token uuid"
  3. Check the POSTMAN documentation that contains a request example in this link.
Below, there is a POST request example with javascript.

var data= {
"session": "sesión obtenida en 'Crear una orden de tokenización' ",
"ld": "datos de la tarjeta cifrados con AES-CTR-128 en formato HEX",
"lk": "Llaves AES cifradas con llave pública en formato base64"
}

var unirest = require("unirest");
//Tokenize the order created in GreenPay gateway
function postTokenize(data, accessToken) {
return new Promise(function (resolve, reject) {
unirest.post("https://sandbox-checkout.greenpay.me/" + 'tokenize')
.headers({
"Accept": "application/json",
"Content-Type": "application/json",
"liszt-token": "token from tokenization order'"
})
.send(data)
.end(function (response) {
if (response.status === 200) {
console.log("response: ",JSON.stringify(response));
resolve(response.body);
} else {
reject(response.body);
}
});
});
}
 
Below, there is an example of Greenpay api response. 

{
    "statusCode": 200,
"body": {
"status": 201,
"requestId": 1,
"result": {
"token": "fb3d1a7b-9cb1-45b7-b49d-b2a3efd98371",
"last_digits": "7777",
"bin": "477777"
},
"expiration_date": "2109",
"brand": "Visa",
"nickname": "Visa",
"errors": [],
"_signature": "5005b0d596e607825ea4385d48b1c2f39aaae2a1965e135e47a050e00018e7f799aea524f489fe4d77416f4e2534d308e9bf967333ed695b0b1d73a0ce751e85f9b04edb12ec06096352535934f993ae4d68644896470f619cba8aa0fd5e7b7cb12b75fdb11bcc4d70da915c3c47dc835bf68e6f60c35bbbd9dcd44431100"
},
"headers": {
"...": "..."
},
"request": {
"uri": {
"...": "..."
},
"method": "post",
"headers": {
"...": "..."
}
}
}

4. Charge a card token

In order to charge a card token check this article.


    • Related Articles

    • Create tokenization order

      To consider A tokenization order is created to prepare the Greenpay API for create a token from credit or debit card data. The following aspects have to be consider for it: Use these endpoints: Sandbox: https://sandbox-merchant.greenpay.me/tokenize ...

    • Tokenization form process

      To consider To use the card tokenization form, the following aspects should be considered: The form is available at: Sandbox: http://sandbox-tokenizeform.greenpay.me/ Producción: https://tokenizeform.greenpay.me/ Get a session and token of a valid ...

    • Invoking checkout API

      To consider To invoke the payments api, the following aspects should be considered: Use the service on the endpoints: Sandbox: https://sandbox-checkout.greenpay.me/kount Production: https://checkout.greenpay.me/kount Get a session and token of a ...

    • Widget payment process

      To consider Para utilizar el widget de pago de Greenpay, se debe considerar los siguiente: You must have a sandbox or production account, to obtain a sandbox account visit About sandbox or test account. The payment widget is a web element that can be ...

    • Webform payment process

      To consider To use the card payment form, the following aspects should be considered: The form is available at: Sandbox: https://sandbox-checkoutform.greenpay.me/ Producción: https://checkout-form.greenpay.me/ Get a session and token of a valid ...