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.

Você pode realizar a operação utilizando um card_hash ou informando diretamente os dados do cartão. No link a seguir, explicamos o passo a passo de como gerar um card_hash.

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

Ambiente de Produção

Essa versão da API de Criar Cartões (v3) para o ambiente de produção ainda está em desenvolvimento. Para obter informações sobre o cronograma de disponibilização desta funcionalidade, entre em contato com o time da Marlim através dos nossos canais de suporte.

POSTv3/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.
card_hash	string	Hash de um cartão criptografado manualmente usando uma chave pública. Caso inclua um card_holder_name, card_number, card_expiration_date, card_cvv esse campo torna-se dispensável.

Exemplo de Request Body

{
  "card_holder_name": "John Doe",
  "card_number": "1234567890123456",
  "card_expiration_date": "1225",
  "card_cvv": "123"
}

Exemplo de Request Body

{
  "card_hash": "fc417fdc29d7ba484ecb4ba9e40966a1_Q2FyZCBOb3RlOiA0OTAxNzIwMDgwMzQ0NDQ4CkNhcmQgSG9sZGVyIE5hbWU6IEx1a2UgU2t5c2F3a2VyCkNhcmQgRXhwaXJhdGlvbiBEYXRlOiAxMTIyCkNhcmQgQ1ZWOiAxMjM=",
}

Importante

Nossa API não aceita null, undefined ou empty em valores de string em qualquer endpoint. Se passar um parâmetro com qualquer um destes 3 valores, será retornado um erro. Caso o parâmetro não seja obrigatório e você não queira que ele seja computado, basta removê-lo da requisição.

Response Object

Propriedade	Tipo	Descrição
card_id	string	Hash identificador do cartão.
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.

Exemplo de Response

{
  "card_id": "card_princess12leia45organa678",
  "date_created": "2025-01-01T00:00:00.000Z",
  "date_updated": "2025-01-01T00:00:00.000Z",
  "card_holder_name": "Leia S O Solo",
  "card_brand": "mastercard",
  "card_first_digits": "444455",
  "card_last_digits": "3333",
  "card_expiration_date": "1122",
  "valid": true
}

Error Object

Atributo	Tipo	Descrição
api_reference	string	Url para a documentação.
errors	array	Array com todos os erros encontrados ao processar a requisição.
errors[][type]	string	Tipo de erro ocorrido.
errors[][message]	string	Mensagem detalhada do erro ocorrido.

Exemplo de erro

{
    "api_reference": "https://docs.api.marlim.co/cards/read",
    "errors": [
        {
            "type": "card_holder_name",
            "message": "The parameter [ card_holder_name ] is missing."
        },
    ]
}

Exemplos

ATENÇÃO

Os valores utilizados nos exemplos abaixo são apenas para ilustração e não devem ser usados para fazer requests nas APIs da Marlim. Em ambiente de desenvolvimento e testes, utilize dados mais próximos de uma transação real.

Cartão Criado

Request

curl -X POST "https://api.marlim.co/v3/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"
}'

Response200

{
  "card_id": "card_princess12leia45organa678",
  "date_created": "2025-08-27T15:32:45.908Z",
  "date_updated": "2025-08-27T15:32:45.908Z",
  "card_holder_name": "Leia S O Solo",
  "card_brand": "mastercard",
  "card_first_digits": "444455",
  "card_last_digits": "3333",
  "card_expiration_date": "1122",
  "valid": true
}

Faltando parâmetros

Request

curl -X POST "https://api.marlim.co/v3/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"
}'

Response400

{
  "api_reference": "https://docs.api.marlim.co/cards/create",
  "errors": [
    {
      "type": "card_cvv",
      "message": "The parameter [ card_cvv ] is missing."
    }
  ]
}