Invoking checkout API

Invoking checkout API

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/kount
    2. Production: https://checkout.greenpay.me/kount
  2. Get a session and token of a valid payment order (A session and token is valid within 30 minutes from the creation of the order). In order to create them you can review this article Create a payment order.
  3. Include Kount, which is the system used by Greenpay to identify patterns of fraud in transaction processing. This is done by a data collector, which is responsible for obtaining device and location information. The data collector generates a session id (params.MercSessId) that has to be included with the card data when using the GreenPay checkout service. To include the Data Collector, follow these steps:
    1. Data collector for web applications
      1. Include the data collector script
        <script src="https://static.greenpay.me/collector/1.0.1/GDataCollector.min.js"></script>
      2. Initialize the Data collector. The init method of the data collector receives in the first parameter a 'sand' for the sandbox environment or 'prod' for the production environment.

        GDataCollector.init('sand', null, function (result) //sandbox


        GDataCollector.init('prod', null, function (result) //production
        //Ejemplo completo

        <script>
        var collector = null;
        var result;
        GDataCollector.init('sand', null, function (result) {
        collector = result;
        collector.setupCallback({
        // fires when collection has finished
        'collect-end':
        function(params) {
        console.log('collection has ended');
        console.log('SessionId', params.MercSessId);
        result = params.MercSessId;
        },
        // fires when collection has started.
        'collect-begin':
        function() {
        //console.log('collection has started');
        }
        });
        collector.collectData();
        });
        </script>
      3. The value in params.MercSessId must be obtained. This value has to be included in the object with the card data.

Steps for using the service

1. Data structure

1.1. Create json object with card data (It does not apply for credix)

The json object with the card data must have the following structure.
{
"card": {
"cardHolder": "Card owner name",
"expirationDate": {
"month": month number, from 1 to 12,
"year": last two numbers of the year
},
"cardNumber": "card number",
"cvc": "Card security code"
},
"tokenize": true,
"kountSession": "value of params.MercSessId generated by data collector"
}

Mandatory JSON parameters:
  1. cardHolder: String of the name of the card owner.
  2. month: It is an int value. Number that indicates the month of expiration of the card, from 1 to 12..
  3. year: It is an int value. Number that indicates the expiration year of the card. It is last two number of the year.
  4. cardNumber: String of the card number
  5. cvc: String of the card security code.
  6. kountSession: It is the params.MercSessId value obtained from the data collector (See To consider section in point C).
Optional JSON parameters:
  1. tokenize: Boolean type. Parameter that indicates if you want to tokenize the card after making the payment. (true = tokenize the card, false = does not tokenize).
If the merchant will use card tokens (See Tokenization Process) the JSON object must have the following structure:
{
"token":"token obtained from your database",
"kountSession" :"params.MercSessId value generated by data collector"
}

1.2 Create json object with card data and Credix

If transactions are to be processed with Credix, another parameter has to be added to the json called options, as shown below.
{
"card": {
"cardHolder": "Card owner name",
"expirationDate": {
"month": month number, from 1 to 12,
"year": last two numbers of the year
},
"cardNumber": "card number",
"cvc": "Card security code"
},
"tokenize": true,
"options": {
"numberOfPayments": "3"
},
"kountSession": "value of params.MercSessId generated by data collector"
}

2. Encrypt the JSON object that contains the card or token information.

For security reasons, the card or token information is required to be sent encrypted. To encrypt this data, the encryption algorithm “AES-CTR-128” must be used, if this information is not encrypted with this algorithm, the payment service will reject the payment request.

In https://gitlab.com/gp-examples/checkout/checkout_csharp are some AES-CTR-128 encryption examples, developed in C#. One was developed without external libraries and the other one uses the library “BouncyCastle”. The last one was developed in NodeJS with the Aed JS library.

Steps to encrypt the card information.

- Dynamically generate a pair of AES keys (key, counter) which will be used to encrypt card information.

  1. Each key is an array of 16 bytes
  2. The key contains the key to encrypt in AES.
  3. The counter is the counter for AES CTR mode.

- Encrypt the JSON object with the card data, and convert result to hexadecimal format.

  1. The hexadecimal string corresponds to the “Id” value that must be sent in the the payment request “body”
  2. The “Id” value that must sent in the payment request body corresponds to the hexadecimal string that is obtained when encrypting the JSON that contains the information of the card with AES-CTR-128

- Encrypt with RSA the AES keys (key, counter) with the public key provided by “Greenpay” support team 

  1. The base64 format string that is obtained from encrypting the AES key, corresponds to the “Ik” value that must be sent in the payment request “body”.
  2. The “Ik” value that must be sent in the payment request body corresponds to the AES  key encryption in base 64.

Consider the TypeScript / JavaScript example below about card data encryption.
  1. To generate the AES key pair, the JavaScript library 'aes-js' is used:

    public generateAESPairs () {
    let key = []
    var iv = 0;
    for (let k = 0; k < 16; k++) {
    key.push(Math.floor(Math.random() * 255))
    }
    for (let k = 0; k < 16; k++) {
    iv = Math.floor(Math.random() * 255)
    }
    return {
    k: key,
    s: iv
    }
    }


  3. To encrypt the card data, the RSA algorithm is used with the JavaScript library 'jsencrypt':
    The parameters of the function are obj (the object with the card data and the kountSession), session (the session that is generated in the purchase order) and pair_ (an undefined). The function returns the object specified in the next point Create an object of type JSON with the previously encrypted data.

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

3. Create a JSON object with previously encrypted data

Create a JSON object with the encrypted data (Ik, id) and the session obtained in the article “Create payment order”, this JSON must be structure as follows:

Encrypted data JSON example


 {
"session": "session obtained in with de service in Create payment order",
"ld": "card data encrypted with AES-CTR-128 in HEX format",
"lk": "AES keys encrypted with the public key in base64 format"
}

JSON parameters

  1. session: session obtained in the payment order request response body. (String)
  2. Id: hexadecimal obtained in the AES-CTR-128 encrypted card data. 
  3. Ik: Base64 data obtained by encrypting the AES keys with the public key provided by Greenpay. This encryption is done with RSA

4. Send payment request

An HTTP POST request must be sent to the payment endpoint with the JSON object that contains the encrypted data and the session obtained in the previous step.

This request  must have the header “liszt-token”. The header must contain the token obtained in the payment order creation request.

Once the payment request has been sent and it has been successfully made, a JSON object is obtained in response.

When receiving this response, the parameter to be obtained from the JSON object is the “body”, since it contains the payment response.


The following image shows an example of the response after submitting a payment request: 

API HTTP response example


{
"statusCode": 200,
"body": {
"status": 200,
"orderId": "xwr-123455",
"authorization": "533793",
"last4": "7777",
"brand": "Visa",
"result": {
"time_local_tran": "165407",
"systems_trace_audit_number": "000283",
"success": true,
"retrieval_ref_num": "701016540713",
"resp_code": "00",
"reserved_private4": null,
"proc_code": "000000",
"network_international_id": "0003",
"mti": "0210",
"merchant_id": 485,
"date_local_tran": "0110",
"card_acceptor_terminal_id": "00112478",
"authorization_id_resp": "533793"
},
"errors": [],
"_signature": "2e9d23b194905314561b8c750f7a74447aa7ce262c9c4d4589a26bc8aad046bce455f5ab2bfb5c9e5e75da2030550b91627d4020c82e5b
a55f6c7ac4b692b8191655f17831b2bca8bf85eade12d5918bcd9b10fe41bfc1f9115baf6c3b9de13cac7170e350bcc4a46bb58d2abc18396c8377b5e5544809aa
41beab114d717ec6"
},
"headers": {
"...": "..."
},
"request": {
"uri": {
"...": "..."
},
"method": "post",
"headers": {
"...": "..."
}
}
}


HTTP response with card tokenization example

{
"status": 200,
"orderId": "TEST 1",
"authorization": "533793",
"amount": 1,
"currency": "CRC",
"result": {
"time_local_tran": "165407",
"systems_trace_audit_number": "000283",
"success": true,
"retrieval_ref_num": "701016540713",
"resp_code": "00",
"reserved_private4": null,
"proc_code": "000000",
"network_international_id": "0003",
"mti": "0210",
"merchant_id": 1280,
"date_local_tran": "0110",
"card_acceptor_terminal_id": "00112478",
"authorization_id_resp": "533793"
},
"errors": [],
"callback": null,
"_signature": "4899d010ded0a9538fb131a588bc81cd0e1b0c614ce7e28932c7abd8870f913c374f2af86b7aefff490bcd728ee535e3ff1dee0f3f10b282fda102321acd1db665c6dc8af6c48a01b2d38d9f2c86a6
75a6de86deb1caec7402ea1b468f337df01bc22ef0bf64f6df9b032e79bed75a9827455bfe3559715807be47716ecd4ec9",
"last4": "4242",
"brand": "Visa",
"tokenizeResp": {
"status": 201,
"requestId": "TEST 1",
"result": {
"token": "c833e9db-2c0c-4a41-9be9-5253f7d5daf2",
"last_digits": "4242",
"khash": "424242HEQ9IFOU6WIPLI",
"bin": "424242"
},
"expiration_date": "2209",
"brand": "Visa",
"nickname": "Visa-4242",
"cardHolder": "Jhon Doe",
"errors": [],
"_signature": "3896228bc4bd29b62f84793e9ed78392cd6c70b833f4910eb72273aaaa54d75d08a050f2b2195451b0428e4cf85afa51e0985e4ba75e0363ea86633e9bcf9f5846c504f76abf96f5b0d988e
042d5a59107192798bd520847f6665e98d7e34bfe27c917ed53562a936b80e13356e230b0ac3361f1e826cc2f32f1c79f2aa6cd40"
}
}


Javascript example of the payment endpoint request. This function also obtains the JSON “body” received in response.

Request code example


var unirest = require("unirest");
//Pays the order creates in GreenPay gateway
function postCheckout(data, accessToken) {
return new Promise(function (resolve, reject) {
unirest.post(process.env.CHECKOUT_ENDPOINT)
.headers({
"Accept": "application/json",
"Content-Type": "application/json",
"liszt-token": "accessToken"
})
.send(data)
.end(function (response) {
if (response.status === 200) {
console.log("checkout",JSON.stringify(response));
resolve(response.body);
} else {
reject(response.body);
}
});
});
}

With the obtained response, the merchant must update the customer's purchase.

    • Related Articles

    • API Tokenization process

      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/tokenize Production: https://checkout.greenpay.me/tokenize Get a session and token of ...

    • General information

      1. What is the Greenpay checkout or payment Gateway? The checkout is a functionality that allows merchants to charge credit or debit cards of their customers. 2. How to integrate the checkout? This service can be integrated in different ways: ...

    • General Information

      This functionality allows you to create card tokens. Two ways are provided for this service. 1.  Directly call the API where the encrypted card information is sent. 2. Invoke the tokenization form, which is displayed in a browser window. If this form ...

    • FAQ

      1. Which cards can be used in the testing environment?  In the test environment, test cards should be used, preferably "false". Therefore we recommend the following:             1. For succesful transactions you can generate card numbers ...

    • Update card token

      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/tokenize/update Production: https://checkout.greenpay.me/tokenize/update Get ...