Card Hash Key
O card_hash representa uma versão criptografada das dados card_holder_name, card_number, card_expiration_date e card_cvv.
Nesta seção você vai aprender mais sobre como o hash é criado, e quais algoritmos utilizar.
O card_hash consiste de uma string gerada a partir dos dados do cartão de crédito. Essa string é encriptada por RSA usando uma chave pública que deve ser requisitada ao servidor da Marlim a cada novo card_hash gerado. Essa chave é invalidada e destruída assim que o servidor lê as informações contidas no card_hash, e por isso só pode ser utilizada uma única vez. Ela também é temporária, expirando 30 minutos após ter sido gerada.
1. Gerando uma nova chave
Abaixo, um exemplo da rota que deverá ser utilizada para obtenção de uma chave pública de encriptação dos dados do cartão de seu cliente:
curl -X GET -G "https://api.marlim.co/v2/card_hash_key" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
{
"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
}
| Propriedade | Significado |
|---|---|
public_key_id | Id retornado e que será utilizado para compor o card_hash, logo, é importante que você o reserve. |
public_key | Chave pública utilizada para criptografar os dados do cartão. |
created_at | UnixTimestamp da criação da chave. |
expires_at | UnixTimestamp de expiração da chave. |
2. Encriptando os dados do cartão
Agora você vai ter que criar uma QueryString com valores URLEncoded para os parâmetros do cartão de crédito. Vamos pegar os seguintes dados abaixo como exemplo:
"card_number": "4901720080344448",
"card_holder_name": "Luke Skywalker",
"card_expiration_date": "1122",
"card_cvv": "123",
A QueryString ficará composta na seguinte forma:
card_number=4901720080344448&card_holder_name=Luke%20Skywalker&card_expiration_date=1122&card_cvv=123
Agora você vai fazer uma criptografia pública com RSA e o padding PKCS1Padding usando a public_key que você recebeu na request passando a QueryString construída.
Após criptografar esses dados você deve converter o resultado para base64. Como resultado você terá:
Q2FyZCBOb3RlOiA0OTAxNzIwMDgwMzQ0NDQ4CkNhcmQgSG9sZGVyIE5hbWU6IEx1a2UgU2t5c2F3a2VyCkNhcmQgRXhwaXJhdGlvbiBEYXRlOiAxMTIyCkNhcmQgQ1ZWOiAxMjM=
Agora com o public_key_id vindo da request inicial, e os dados criptografados convertidos para base64, seu card_hash deverá ser formatado da seguinte maneira: card_hash = public_key_id + "_" + encrypted_string_base64, com o resultado na seguinte forma:
fc417fdc29d7ba484ecb4ba9e40966a1_Q2FyZCBOb3RlOiA0OTAxNzIwMDgwMzQ0NDQ4CkNhcmQgSG9sZGVyIE5hbWU6IEx1a2UgU2t5c2F3a2VyCkNhcmQgRXhwaXJhdGlvbiBEYXRlOiAxMTIyCkNhcmQgQ1ZWOiAxMjM=
Fique atento ao UNDERLINE entre o public_key_id e o encrypted_string_base64.
Acima citamos o formato utilizando ASPAS durante a concatenação somente para ilustração.
3. Criando uma transação
Com o HASH em mãos, crie uma transação na Marlim, utlizando a string gerada no parâmetro card_hash, seguindo o exemplo abaixo:
curl -X POST "https://api.marlim.co/v2/transactions/nomad" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
"net_value": 1000000,
"amount": 1039501,
"installments": "1",
"type": "remittance",
"currency_amount": 150000,
"currency_abbreviation": "EUR",
"item_id": "#123456789",
"item_url": "123456789",
"card_hash": "fc417fdc29d7ba484ecb4ba9e40966a1_Q2FyZCBOb3RlOiA0OTAxNzIwMDgwMzQ0NDQ4CkNhcmQgSG9sZGVyIE5hbWU6IEx1a2UgU2t5c2F3a2VyCkNhcmQgRXhwaXJhdGlvbiBEYXRlOiAxMTIyCkNhcmQgQ1ZWOiAxMjM=",
"customer[external_id]": "111222333",
"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. Exemplo em NODE
Uma forma de criar o HASH é utilizando a biblioteca crypto do NodeJS.
Abaixo um exemplo de como criar o card_hash utilizando essa biblioteca:
const crypto = require("crypto");
// 1 - Crie uma função auxiliadora
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_PADDING,
passphrase: public_key_id
}, Buffer.from(queryString))
const encryptedString = encryptBuffer.toString('base64');
return `${public_key_id}_${encryptedString}`;
}
// 2 - Passe os dados do cartão, a public_key_id e a public_key para a função
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 - O resultado deve ser algo similar ao valor abaixo
card_hash: "fc417fdc29d7ba484ecb4ba9e40966a1_Q2FyZCBOb3RlOiA0OTAxNzIwMDgwMzQ0NDQ4CkNhcmQgSG9sZGVyIE5hbWU6IEx1a2UgU2t5c2F3a2VyCkNhcmQgRXhwaXJhdGlvbiBEYXRlOiAxMTIyCkNhcmQgQ1ZWOiAxMjM="