Version: v1

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é? 😎

POSTv1/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_number]	string	Número do telefone do cliente.
customer[address]	object	Objeto Endereço do Cliente.
customer[address][zipcode]	string	CEP (clientes nacionais) ou ZIP (clientes estrangeiros) do cliente.
customer[address][country]	string	Nacionalidade do cliente, no formato sigla do país. Só serão aceitos o formato ISO 3166-1 alfa-2 (duas-letras) Ex: br, us, uy...
customer[address][state]	string	Estado do atual endereço do cliente, no formato sigla do estado. 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.
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

Os parâmetros customer[document_number] e customer[phone_number] devem ser tratados e passados de forma diferente entre clientes de nacionalidade brasileira ou estrangeira.

Caso o cliente seja de nacionalidade brasileira (customer[address][country] == 'br')

• Em customer[document_number] deve ser passado o CPF do cliente
• Em customer[phone_number] deve ser passado no formato +55DDXXXXXXXXX

Caso o cliente seja de nacionalidade estrangeira (customer[address][country] != 'br')

• Em customer[document_number] deve ser passado o NIN (national identification number) do cliente
• Em customer[phone_number] deve ser passado deve ser passado no padrão regex /^\+(?:[0-9] ?)14[0-9]$/]]

Response Object

Propriedade	Tipo	Descriçã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_id	string	Hash identificador do cartão.
card_fingerprint	string	Hash que permite comparar dois cartões através de seus fingerprints para saber se são o mesmo.
country	string	País de origem da emissão do cartão.
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.

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/v1/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_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]": "713 Sunset Ave",
  "simulate_card_antifraude_validation": "accepted"
}'

Response200

{
  "status": "accepted",
  "date_created": "2024-02-16T19:58:04.118Z",
  "date_updated": "2024-02-16T19:58:04.118Z",
  "card_holder_name": "Luke Skywalker",
  "card_brand": "visa",
  "card_first_digits": "555544",
  "card_last_digits": "2222",
  "card_id": "card_jedi123master4amidala5son",
  "card_fingerprint": "jedi12knight34anakin56son",
  "country": "USA",
  "valid": true
}

🕹 Criar um cartão com status rejected

Request

curl -X POST "https://api.crypto.marlim.co/v1/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_number]": "+18007770112",
  "customer[address][zipcode]": "95351",
  "customer[address][country]": "us",
  "customer[address][state]": "CA",
  "customer[address][city]": "Modesto",
  "customer[address][neighborhood]": "East Modesto",
  "customer[address][street]": "714 Sunset Ave",
  "simulate_card_antifraude_validation": "rejected"
}'

Response200

{
  "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_id": null,
  "card_fingerprint": null,
  "country": null,
  "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/v1/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_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]": "713 Sunset Ave",
  "simulate_antifraude_env": "production"
}'

Response200

{
  "status": "accepted",
  "date_created": "2024-02-16T19:58:04.118Z",
  "date_updated": "2024-02-16T19:58:04.118Z",
  "card_holder_name": "Luke Skywalker",
  "card_brand": "visa",
  "card_first_digits": "555544",
  "card_last_digits": "2222",
  "card_id": "card_jedi123master4amidala5son",
  "card_fingerprint": "jedi12knight34anakin56son",
  "country": "USA",
  "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/v1/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_number]": "+18007770112",
  "customer[address][zipcode]": "95351",
  "customer[address][country]": "us",
  "customer[address][state]": "CA",
  "customer[address][city]": "Modesto",
  "customer[address][neighborhood]": "East Modesto",
  "customer[address][street]": "714 Sunset Ave"
}'

Response200

{
  "status": "accepted",
  "date_created": "2024-02-16T19:58:04.118Z",
  "date_updated": "2024-02-16T19:58:04.118Z",
  "card_holder_name": "Leia S O Solo",
  "card_brand": "mastercard",
  "card_first_digits": "444455",
  "card_last_digits": "3333",
  "card_id": "card_princess12leia45organa678",
  "card_fingerprint": "naboo999galactic9republic",
  "country": "USA",
  "valid": true
}

Request

curl -X POST "https://api.crypto.marlim.co/v1/cards" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
  "card_holder_name": "Luke Skywalker",
  "card_number": "5555444433332222",
  "card_expiration_date": "0504",
  "card_cvv": "123",
  "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]": "713 Sunset Ave"
}'

Response200

{
  "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_id": null,
  "card_fingerprint": null,
  "country": null,
  "valid": false
}

Request

curl -X POST "https://api.crypto.marlim.co/v1/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]": "+18007770134",
  "customer[address][zipcode]": "95351",
  "customer[address][country]": "us",
  "customer[address][state]": "CA",
  "customer[address][city]": "Modesto",
  "customer[address][neighborhood]": "East Modesto",
  "customer[address][street]": "714 Sunset Ave"
}'

Response400

{
  "errors": {
    "type": "parameter",
    "message": "One of the parameters is missing."
  }
}

Request

curl -X POST "https://api.crypto.marlim.co/v1/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_number]": "+18007770122",
  "customer[address][zipcode]": "95351",
  "customer[address][country]": "us",
  "customer[address][state]": "CA",
  "customer[address][city]": "Modesto",
  "customer[address][neighborhood]": "East Modesto",
  "customer[address][street]": "200 BBY"
}'

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

Response Object​

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