Version: v2

Criar Cartão

Essa rota é usada para validar os dados de um cliente em conjunto com o seu cartão no nosso Antifraude. Uma vez validado, esse cartão é salvo com segurança no vault da Marlim a fim de utilizá-lo em compras futuras. Após salvar o cartão, você recebe um objeto contendo um hash na propriedade card_id.

One Click Buy

Essa é a melhor forma de implementar One Click Buy. Com o card_id em nosso servidor, o seu cliente não precisará digitar os dados do cartão novamente e conseguirá comprar com apenas um clique evitando transitar dados sensíveis online.
Irado né? 😎

POSTv2/cards

Request Body Params

Atributo	Tipo	Descrição
card_holder_name	string	Nome do portador do cartão.
card_number	string	Número do cartão.
card_expiration_date	string	Data de validade do cartão. Somente números no formato MMAA.
card_cvv	string	Código verificador do cartão.
customer	object	Objeto Cliente.
customer[name]	string	Nome do cliente.
customer[email]	string	E-mail do cliente.
customer[document_number]	string	Número do documento do cliente.
customer[phone]	string	Objeto Telefone do Cliente.
customer[phone][area]	string	Código de operadora local (DDD) do telefone do cliente.
customer[phone][number]	string	Número do telefone do cliente.
customer[address]	object	Objeto Endereço do Cliente.
customer[address][zipcode]	string	CEP do atual endereço do cliente.
customer[address][state]	string	Estado do atual endereço do cliente, no formato sigla do estado no padrão ISO 3166-2 Ex: SP, RJ, MG...
customer[address][city]	string	Cidade do endereço do cliente.
customer[address][neighborhood]	string	Bairro do endereço do cliente.
customer[address][street]	string	Rua do endereço do cliente. Não é necessário passar número ou complemento.
customer[address][number]	string	Número do atual endereço do cliente.
customer[address][complement]	string	Parâmetro opcional do complemento do atual endereço do cliente.
simulate_card_antifraude_validation	string	Parâmetro opcional que pode ser passado em ambiente de teste para simular o fluxo do Antifraude. Valores aceitos: `accepted` e `rejected`.
simulate_antifraude_env	string	Parâmetro opcional que pode ser passado em ambiente de teste para simular o fluxo do Antifraude. Valores aceitos: `production` e `sandbox`. Default sandbox.

:::

Importante

Diferenças entre a V1 e V2:

• Removido o parâmetro customer[address][country], não sendo mais necessário enviar esses valores no body da request;

• O parâmetro customer[phone_number] mudou para o objeto customer[phone] e seus subsequentes: customer[phone][area] e customer[phone][number];

• Acrescentados os parâmetros customer[address][number] (obrigatório) e customer[address][complement] (opcional) referentes ao endereço do cliente;

• Nessa versão não serão aceitos dados de compradores estrangeiros, logo não há necessidade de tratar de forma diferente os valores relacionados ao documento e o telefone do cliente como na V1;

Info

Diferente da API de Transações, na API de Criar Cartões não é necessário passar o tipo de telefone do cliente (customer[phone][type]).

Response Object

Propriedade	Tipo	Descrição
card_id	string	Hash identificador do cartão.
status	string	Representa o estado atual da requisição. Valores possíveis: `accepted` e `rejected`.
date_created	dateTime	Data de criação do cartão no formato ISODateTime.
date_updated	dateTime	Data de atualização do cartão no formato ISODateTime.
card_holder_name	string	Nome do portador do cartão.
card_brand	string	Bandeira do cartão. Valores possíveis: `visa`, `mastercard`, `amex`, `hipercard` e `elo`.
card_first_digits	string	Primeiros 6 dígitos do cartão.
card_last_digits	string	Últimos 4 dígitos do cartão.
card_expiration_date	string	Data de validade do cartão, no formato MMAA.
valid	boolean	Propriedade para verificar a validade do cartão, ou seja, caso `true`, é possível cobrar o cartão em condições normais, para `false`, não pode ser utilizado.

Importante

Diferenças entre a V1 e V2:

• Adicionado o parâmetro card_expiration_date;

• Removidos os parâmetros card_fingerprint e country;

Antifraude

Atenção

O nosso antifraude é composto por uma série de regras, entre elas a confirmação de que o cartão utilizado realmente pertence ao cliente em questão. Por conta disso é de extrema importância que na UI do checkout tenha um aviso/disclaimer informando aos clientes para não utilizar cartões virtuais e/ou de terceiros, uma vez que esta validação irá falhar e a operação será recusada. Ou seja, deixe evidente para o seu cliente uma mensagem solicitando para ele utilizar os dados do cartão físico expedido pelo banco emissor e do próprio cliente que está efetuando a compra, evitando surpresas 😎

Simular Validação

Para facilitar durante a fase de desenvolvimento você pode simular o status da criação do cartão. Passando os valores accepted ou rejected na propriedade simulate_card_antifraude_validation. Em ambiente sandbox como não existe a validação no Banco Emissor do cartão, caso não seja emulado nenhum status, ele se torna randômico.

🕹 Criar um cartão com status accepted

Request

curl -X POST "https://api.crypto.marlim.co/v2/cards" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
  "card_holder_name": "Luke Skywalker",
  "card_number": "5555444433332222",
  "card_expiration_date": "1122",
  "card_cvv": "123",
  "customer[name]": "Luke Skywalker",
  "customer[email]": "luke@jedimaster.sw",
  "customer[document_number]": "00099988877",
  "customer[phone][area]": "11",
  "customer[phone][number]": "999887766",
  "customer[address][zipcode]": "00099887",
  "customer[address][state]": "SP",
  "customer[address][city]": "São Paulo",
  "customer[address][neighborhood]": "Centro",
  "customer[address][street]": "Rua de Ali",
  "customer[address][number]": "9988",
  "simulate_card_antifraude_validation": "accepted"
}'

Response200

{
  "card_id": "card_jedi123master4amidala5son",
  "status": "accepted",
  "date_created": "2024-02-16T19:58:04.360Z",
  "date_updated": "2024-02-16T19:58:04.360Z",
  "card_holder_name": "Luke Skywalker",
  "card_brand": "visa",
  "card_first_digits": "555544",
  "card_last_digits": "2222",
  "card_expiration_date": "1122",
  "valid": true
}

🕹 Criar um cartão com status rejected

Request

curl -X POST "https://api.crypto.marlim.co/v2/cards" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
  "card_holder_name": "Leia S O Solo",
  "card_number": "4444555566663333",
  "card_expiration_date": "0504",
  "card_cvv": "999",
  "customer[name]": "Leia Skywalker Organa Solo",
  "customer[email]": "princess@alderaan.sw",
  "customer[document_number]": "11199988877",
  "customer[phone][area]": "11",
  "customer[phone][number]": "999887766",
  "customer[address][zipcode]": "00099887",
  "customer[address][state]": "SP",
  "customer[address][city]": "São Paulo",
  "customer[address][neighborhood]": "Centro",
  "customer[address][street]": "Rua de Ali",
  "customer[address][number]": "9988",
  "simulate_card_antifraude_validation": "rejected"
}'

Response200

{
  "card_id": null,
  "status": "rejected",
  "date_created": null,
  "date_updated": null,
  "card_holder_name": "Leia S O Solo",
  "card_brand": "mastercard",
  "card_first_digits": "444455",
  "card_last_digits": "3333",
  "card_expiration_date": "0504",
  "valid": false
}

Simular em Produção

O Antifraude Marlim contém como parte dos mecanismos de validação uma verificação do cartão junto ao banco emissor. Como o fluxo de banco emissor não existe em ambiente sandbox, preparamos o parâmetro simulate_antifraude_env que pode ser usado durante a fase de desenvolvimento para simular a validação acurada do Antifraude em produção.

🕹 Simulando Antifraude em Produção

Request

curl -X POST "https://api.crypto.marlim.co/v2/cards" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
  "card_holder_name": "Luke Skywalker",
  "card_number": "5555444433332222",
  "card_expiration_date": "1122",
  "card_cvv": "123",
  "customer[name]": "Luke Skywalker",
  "customer[email]": "luke@jedimaster.sw",
  "customer[document_number]": "00099988877",
  "customer[phone][area]": "11",
  "customer[phone][number]": "999887766",
  "customer[address][zipcode]": "00099887",
  "customer[address][state]": "SP",
  "customer[address][city]": "São Paulo",
  "customer[address][neighborhood]": "Centro",
  "customer[address][street]": "Rua de Ali",
  "customer[address][number]": "9988",
  "simulate_antifraude_env": "production"
}'

Response200

{
  "card_id": "card_jedi123master4amidala5son",
  "status": "accepted",
  "date_created": "2024-02-16T19:58:04.360Z",
  "date_updated": "2024-02-16T19:58:04.360Z",
  "card_holder_name": "Luke Skywalker",
  "card_brand": "visa",
  "card_first_digits": "555544",
  "card_last_digits": "2222",
  "card_expiration_date": "1122",
  "valid": true
}

Nota

Se você utlizar o parâmetro simulate_antifraude_env com o valor production o parâmetro opcional simulate_card_antifraude_validation se torna inutilizável.

Atenção

Os parâmetros simulate_card_antifraude_validation e simulate_antifraude_env só são habilitados para api_key do ambiente sandbox. Se você passar algum desses dois parâmetros em ambiente de produção, será retornado um erro 403 (Forbidden).

Exemplos

Nota

Os valores utilizados nos exemplos abaixo são apenas para ilustração. Em ambiente de desenvolvimento ou testes, utilize dados mais próximos de uma transação real (dados de cartão e cliente). Se você utlizar valores fictícios o Antifraude pode não funcionar de forma esperada.

Cartão Aprovado
Cartão Recusado
Faltando Dados do Cliente
Erro ao Salvar o Cartão

Request

curl -X POST "https://api.crypto.marlim.co/v2/cards" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
  "card_holder_name": "Leia S O Solo",
  "card_number": "4444555566663333",
  "card_expiration_date": "0504",
  "card_cvv": "999",
  "customer[name]": "Leia Skywalker Organa Solo",
  "customer[email]": "princess@alderaan.sw",
  "customer[document_number]": "11199988877",
  "customer[phone][area]": "11",
  "customer[phone][number]": "999887766",
  "customer[address][zipcode]": "00099887",
  "customer[address][state]": "SP",
  "customer[address][city]": "São Paulo",
  "customer[address][neighborhood]": "Centro",
  "customer[address][street]": "Rua de Ali",
  "customer[address][number]": "9988"
}'

Response200

{
  "card_id": "card_princess12leia45organa678",
  "status": "accepted",
  "date_created": "2024-02-16T19:58:04.360Z",
  "date_updated": "2024-02-16T19:58:04.360Z",
  "card_holder_name": "Leia S O Solo",
  "card_brand": "mastercard",
  "card_first_digits": "444455",
  "card_last_digits": "3333",
  "card_expiration_date": "1122",
  "valid": true
}

Request

curl -X POST "https://api.crypto.marlim.co/v2/cards" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
  "card_holder_name": "Luke Skywalker",
  "card_number": "5555444433332222",
  "card_expiration_date": "1122",
  "card_cvv": "123",
  "customer[name]": "Luke Skywalker",
  "customer[email]": "luke@jedimaster.sw",
  "customer[document_number]": "00099988877",
  "customer[phone][area]": "11",
  "customer[phone][number]": "999887766",
  "customer[address][zipcode]": "00099887",
  "customer[address][state]": "SP",
  "customer[address][city]": "São Paulo",
  "customer[address][neighborhood]": "Centro",
  "customer[address][street]": "Rua de Ali",
  "customer[address][number]": "9988"
}'

Response200

{
  "card_id": null,
  "status": "rejected",
  "date_created": null,
  "date_updated": null,
  "card_holder_name": "Luke Skywalker",
  "card_brand": "visa",
  "card_first_digits": "555544",
  "card_last_digits": "2222",
  "card_expiration_date": "1122",
  "valid": false
}

Request

curl -X POST "https://api.crypto.marlim.co/v2/cards" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
  "card_holder_name": "Han Solo",
  "card_number": "1243291243298888",
  "card_expiration_date": "0504",
  "card_cvv": "765",
  "customer[email]": "han@cadet124329.sw",
  "customer[document_number]": "00099988888",
  "customer[phone][number]": "999887766",
  "customer[address][zipcode]": "00099887",
  "customer[address][state]": "SP",
  "customer[address][city]": "São Paulo",
  "customer[address][neighborhood]": "Centro",
  "customer[address][street]": "Rua de Ali",
  "customer[address][number]": "9988"
}'

Response401

{
  "errors": {
    "type": "parameter",
    "message": "The parameter [ customer.phone.area ] is missing."
  }
}

Request

curl -X POST "https://api.crypto.marlim.co/v2/cards" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
  "card_holder_name": "Chewbacca Chewie",
  "card_number": "4444555566661234",
  "card_expiration_date": "0504",
  "card_cvv": "888",
  "customer[name]": "Wookiee Chewbacca Chewie",
  "customer[email]": "chewie@wookiee.sw",
  "customer[document_number]": "20099988877",
  "customer[phone][area]": "11",
  "customer[phone][number]": "999887766",
  "customer[address][zipcode]": "00099887",
  "customer[address][state]": "SP",
  "customer[address][city]": "São Paulo",
  "customer[address][neighborhood]": "Centro",
  "customer[address][street]": "Rua de Ali",
  "customer[address][number]": "9988"
}'

Response400

{
  "errors": {
    "type": "crate_card",
    "message": "There was a problem while saving the card, please try again in a few minutes or contact us."
  }
}

One Click Buy

Request Body Params​

Importante

Info

Response Object​

Importante

Antifraude​

Atenção

Simular Validação​

Simular em Produção​

Nota

Atenção

Exemplos​

Nota

Request Body Params

Response Object

Antifraude

Simular Validação

Simular em Produção

Exemplos