Card Hash Key

The card_hash represents an encrypted version of the card_holder_name, card_number, card_expiration_date, and card_cvv data.

In this section, you will learn more about how the hash is created and which algorithms to use.

The card_hash consists of a string generated from credit card data. This string is encrypted using RSA with a public key that must be requested from the Marlim server for each new card_hash generated. This key is invalidated and destroyed as soon as the server reads the information contained in the card_hash, and therefore can only be used once. It is also temporary, expiring 30 minutes after being generated.

1. Generating a new key

Below is an example of the route that should be used to obtain a public encryption key for your customer's card data:

Request

curl -X GET -G "https://api.marlim.co/v3/card_hash_key" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \

Response200

{
  "public_key_id": "fc417fdc29d7ba484ecb4ba9e40966a1",
  "public_key": "-----BEGIN RSA PUBLIC KEY-----\nMIICCgKCAgEAmxxkyU71w+0bmVc4wN7ORc6lq6Xd9+jOlOwzgaXX12qLhTABZCb/\n0YgwXPAvfzmgRBgdxVnOiWHSDgWD/8usQ87MG679tj3sc+g6JujLgKaVhue7ET38\nplElx4f20zHb+so8S1hnrtN0N8ZhgMmsMlEq6j70kHXnFMa3lEkK2tmr/QKYergw\nwzETGb7SG/kKlNydNZ/QTafCpRrCNd4kO8R6GMuufoLxPsA5WdK7e3yE2tVSpddv\nQtUawDWHIWEDTNjgBL2hx4DK06FiVzz2QvY4za6DBjuOQvSw+i5jfIYysXS/lpcy\n5e5qkKMfpLfalqTtRAz4ou6ITuoweqpWnjQuqwa2odm26+V0wEPjfHWsDeptZDOR\nvGmHfVcl8UbOj0tuJNhpsqfEYGwCcVJ2TwKsF9Ux7wHv7qptk5FV4tcvdLmxH2r4\nUlNa0l+5dtA8AbKEHt5f+OhGNVgqZxgMwLVoKgW46Jx/LHznBDQEyCE6Zr6oDyBF\nxYlp3AsAzE9nfXIb435V03lqJfNc4DitxiW3+jcrgnoRoVUd3+7awC+wiyOwmgis\n3pQuSSreeYv6XtOZ/AX8RQGf3YqSLAZrT/LH6gzl32ldzCwP2XA3UrVFbMFpvhuL\nVsfAwjPlyGvX7ra6Op17l/nqq/jHqdgkuBK5I5eXJNJq4bgnZEXtF2sCAwEAAQ==\n-----END RSA PUBLIC KEY-----\n",
  "created_at": 1668978045960,
  "expires_at": 1668979845960
}

Property	Meaning
public_key_id	ID returned that will be used to compose the card_hash, so it's important that you save it.
public_key	Public key used to encrypt the card data.
created_at	UnixTimestamp of key creation.
expires_at	UnixTimestamp of key expiration.

2. Encrypting card data

Now you'll need to create a QueryString with URLEncoded values for the credit card parameters. Let's use the following data as an example:

Card Data

"card_number": "4901720080344448",
"card_holder_name": "Luke Skywalker",
"card_expiration_date": "1122",
"card_cvv": "123",

The QueryString will be composed in the following way:

Querystring Data

card_number=4901720080344448&card_holder_name=Luke%20Skywalker&card_expiration_date=1122&card_cvv=123

Now you will perform public encryption with RSA and PKCS1OAEPPadding (RSA_PKCS1_OAEP_PADDING) padding using the public_key you received in the request, passing the constructed QueryString.

After encrypting this data, you must convert the result to base64. As a result, you will have:

Hash created from RSA and PKCS1OAEPPadding (RSA_PKCS1_OAEP_PADDING)

Q2FyZCBOb3RlOiA0OTAxNzIwMDgwMzQ0NDQ4CkNhcmQgSG9sZGVyIE5hbWU6IEx1a2UgU2t5c2F3a2VyCkNhcmQgRXhwaXJhdGlvbiBEYXRlOiAxMTIyCkNhcmQgQ1ZWOiAxMjM=

Now with the public_key_id from the initial request, and the encrypted data converted to base64, your card_hash should be formatted as follows: card_hash = public_key_id + "_" + encrypted_string_base64, with the result in the following form:

The final Card HASH (card_hash)

fc417fdc29d7ba484ecb4ba9e40966a1_Q2FyZCBOb3RlOiA0OTAxNzIwMDgwMzQ0NDQ4CkNhcmQgSG9sZGVyIE5hbWU6IEx1a2UgU2t5c2F3a2VyCkNhcmQgRXhwaXJhdGlvbiBEYXRlOiAxMTIyCkNhcmQgQ1ZWOiAxMjM=

Note

Pay attention to the UNDERLINE between the public_key_id and encrypted_string_base64.
Above we mentioned the format using QUOTES during concatenation only for illustration.

3. Creating a transaction

With the HASH in hand, create a transaction in Marlim, using the generated string in the card_hash parameter, following the example below:

Request

curl -X POST "https://api.marlim.co/v3/transactions" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
  "net_value": 1000000,
  "amount": 1039501,
  "installments": "1",
  "type": "remittance",
  "item_id": "#123456789",
  "card_hash": "fc417fdc29d7ba484ecb4ba9e40966a1_Q2FyZCBOb3RlOiA0OTAxNzIwMDgwMzQ0NDQ4CkNhcmQgSG9sZGVyIE5hbWU6IEx1a2UgU2t5c2F3a2VyCkNhcmQgRXhwaXJhdGlvbiBEYXRlOiAxMTIyCkNhcmQgQ1ZWOiAxMjM=",
  "customer[name]": "Luke Skywalker",
  "customer[email]": "luke@jedimaster.sw",
  "customer[document_number]": "00099988877",
  "customer[phone_number]": "+18007770133",
  "customer[address][zipcode]": "95351",
  "customer[address][country]": "us",
  "customer[address][state]": "CA",
  "customer[address][city]": "Modesto",
  "customer[address][neighborhood]": "East Modesto",
  "customer[address][street]": "Sunset Ave",
  "customer[address][number]": "713",
  "soft_descriptor": "Star Wars"
}'

4. NODE Example

One way to create the HASH is using the NodeJS crypto library.
Below is an example of how to create the card_hash using this library:

Using the NodeJS Crypto Library

  const crypto = require("crypto");

  // 1 - Create a helper function
  const encryptCardHash = (card_data, public_key_id, public_key) => {

    const esc = encodeURIComponent;
    const queryString = Object.keys(card_data).map(key => `${esc(key)}=${esc(card_data[key]).trim()}`).join('&');

    const encryptBuffer = crypto.publicEncrypt({
      key: public_key,
      padding: crypto.constants.RSA_PKCS1_OAEP_PADDING,
      passphrase: public_key_id
    }, Buffer.from(queryString))

    const encryptedString = encryptBuffer.toString('base64');

    return `${public_key_id}_${encryptedString}`;

  }

  // 2 - Pass the card data, public_key_id, and public_key to the function
  const card_hash = encryptCardHash({
    card_number: "4901720080344448",
    card_holder_name: "Luke Skywalker",
    card_expiration_date: "1122",
    card_cvv: "123",
  }, "fc417fdc29d7ba484ecb4ba9e40966a1", JSON.parse("-----BEGIN RSA PUBLIC KEY ... END RSA PUBLIC KEY-----"))

  // 3 - The result should be something similar to the value below
  card_hash: "fc417fdc29d7ba484ecb4ba9e40966a1_Q2FyZCBOb3RlOiA0OTAxNzIwMDgwMzQ0NDQ4CkNhcmQgSG9sZGVyIE5hbWU6IEx1a2UgU2t5c2F3a2VyCkNhcmQgRXhwaXJhdGlvbiBEYXRlOiAxMTIyCkNhcmQgQ1ZWOiAxMjM="