Pular para o conteúdo principal

Criar Transação

Para fazer uma cobrança você deve utilizar essa rota e criar a sua transação.

É possível utilizar um card_hash, card_id ou todos os dados do cartão diretamente (card_holder_name, card_number, card_expiration_date e card_cvv). A primeira opção é a mais indicada, por fatores de segurança.

Toda vez que for realizado uma transação com sucesso em nossos sistemas será retornado um card_id que poderá ser utilizado em compras futuras. Assim utilizando o card_hash na primeira compra e um card_id nas compras futuras você incrementa ainda mais a segurança dos dados do seu cliente, sem precisar expor os dados sensíveis do cartão.

A Marlim é uma empresa PCI Compliance, ou seja, somos auditados para seguir todas as regras de segurança de mercado que visam proteger os dados dos cartões dos seus clientes. Caso seu sistema não esteja habilitado para criar o card_hash, você pode transacionar com segurança com os dados abertos de cartão, uma vez que nossos sistemas criptografam todos os dados e somente nosso Adquirente (quem processa o pagamento junto ao Banco Emissor) é que tem acesso aos dados reais do cartão. No link a seguir, descrevemos o passo a passo de como criar um card_hash.

Nota

Os valores utilizados nos exemplos são apenas para ilustração. Em ambiente Sandbox, utilize dados do cliente pagador mais próximos de uma transação real. Se você utlizar valores fictícios demais, o Antifraude pode não funcionar de forma esperada.

POSTv3/transactions

Request Body Params​

AtributoTipoDescrição
amountint32Valor final a ser cobrado do consumidor final. Deve ser passado em centavos.
installmentsstringNúmero de parcelas da transação, sendo mínimo: 1 e máximo: 12.
item_idstringID da transação na sua plataforma.
soft_descriptorstringDescrição que aparecerá na fatura do seu cliente. Máximo de 13 caracteres, sendo alfanuméricos e espaços.
card_holder_namestringNome do portador do cartão.
Caso inclua um card_id ou card_hash, esse campo torna-se dispensável.
card_numberstringNúmero do cartão.
Caso inclua um card_id ou card_hash, esse campo torna-se dispensável.
card_expiration_datestringData de validade do cartão. Somente números no formato MMAA.
Caso inclua um card_id ou card_hash, esse campo torna-se dispensável.
card_cvvstringCódigo verificador do cartão.
Caso inclua um card_id ou card_hash, esse campo torna-se dispensável.
card_idstringID de um cartão salvo e validado anteriormente.
Caso inclua um card_hash ou os dados abertos do cartão, esse campo torna-se dispensável.
card_hashstringHash de um cartão criptografado manualmente usando uma chave pública.
Caso inclua um card_id ou os dados abertos do cartão, esse campo torna-se dispensável.
customerobjectObjeto Cliente.
customer[name]stringNome do cliente.
customer[email]stringE-mail do cliente.
customer[document_number]stringNúmero do documento do cliente.
customer[phone]objectObjeto número do telefone do cliente.
customer[phone][country_code]stringCódigo do país do telefone do cliente (DDI).
customer[phone][area_code]stringCódigo do estado do telefone do cliente (DDD).
customer[phone][number]stringNúmero do telefone do cliente.
customer[address]objectObjeto Endereço do Cliente.
customer[address][country]stringNacionalidade 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...
Máximo em caracteres: 2
customer[address][state]stringEstado do atual endereço do cliente, no formato sigla do estado. Ex: SP, RJ, MG...
Máximo em caracteres: 2
customer[address][city]stringCidade do endereço do cliente.
Máximo em caracteres: 50
customer[address][neighborhood]stringBairro do endereço do cliente.
Máximo em caracteres: 45
customer[address][street]stringRua do endereço do cliente.
Máximo em caracteres: 54
customer[address][number]stringNúmero do atual endereço do cliente.
Máximo em caracteres: 5
customer[address][complement]stringParâmetro opcional do complemento do atual endereço do cliente.
Máximo em caracteres: 14
customer[address][zipcode]stringCEP do cliente.
Máximo em caracteres: 9
webhook_urlstringParâmetro opcional para passar o endpoint do seu sistema que receberá informações a cada atualização da transação.
webhook_auth_tokenstringParâmetro opcional para autenticar as notificações enviadas para o webhook_url. Caso o parâmetro não seja informado, as notificações serão enviadas sem autenticação.
net_valueint32Parâmetro necessário caso sua plataforma repasse a taxa de adquirência para o consumidor final. Valor líquido a ser recebido pela transação. Deve ser passado em centavos.
dfp_idstringParâmetro opcional do ID da URL que compõe o session_id criado na integração com o Antifraude da Marlim.
sub_seller_document_numberstringParâmetro opcional para informar o CNPJ do seu parceiro de venda.
sub_seller_idstringParâmetro opcional para informar o ID na sua plataforma do seu parceiro de venda.
simulate_statusstringParâmetro opcional que pode ser passado em ambiente de teste para simular o fluxo do Antifraude. Valores aceitos: paid, review e rejected.
simulate_refused_codestringParâmetro opcional que pode ser passado em ambiente de teste para simular o fluxo de retornos negativos do banco emissor. Valores aceitos: 1000, 1011, 1016 e 5000.
Exemplo de Request Body
{
  "amount": 1000,
  "installments": "1",
  "item_id": "ABC123456789",
  "soft_descriptor": "Marlim Store",
  "card_holder_name": "Luke Skywalker",
  "card_number": "5555444433332222", 
  "card_expiration_date": "1225",
  "card_cvv": "123",
  "customer": {
    "name": "Luke Skywalker",
    "email": "luke@jedimaster.sw",
    "document_number": "00099988877",
    "phone": {
      "country_code": "+55",
      "area_code": "11", 
      "number": "999887766"
    },
    "address": {
      "country": "BR",
      "state": "SP",
      "city": "São Paulo",
      "neighborhood": "República",
      "street": "Rua Aurora",
      "number": "123",
      "complement": "Apto 42",
      "zipcode": "01209001"
    }
  }
}
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​

PropriedadeTipoDescrição
statusstringRepresenta o estado atual da transação. Valores possíveis: paid, review, rejected e refused.
amountint32Valor em centavos a ser cobrado na transação.
net_valueint32Parâmetro opcional do valor líquido a ser recebido pela transação.
authorized_amountint32Valor em centavos autorizado na transação.
paid_amountint32Valor em centavos capturado na transação.
refunded_amountint32Valor em centavos estornado na transação.
installmentsstringNúmero de parcelas em que o cliente pagou.
nsustringCódigo que identifica a transação na adquirente.
authorization_codestringCódigo de autorização retornado pelo banco emissor.
transaction_idstringNúmero identificador Marlim da transação.
date_createddateTimeData de criação da transação no formato ISODateTime.
date_updateddateTimeData de atualização do status da transação no formato ISODateTime.
card_holder_namestringNome do portador do cartão utilizado no pagamento.
card_brandstringBandeira do cartão utilizado no pagamento. Valores possíveis: visa, mastercard, amex, hipercard e elo.
card_first_digitsstringPrimeiros 6 dígitos do cartão utilizado no pagamento.
card_last_digitsstringÚltimos 4 dígitos do cartão utilizado no pagamento.
card_idstring | nullAo realizar uma transação com o status paid, retornamos sempre um card_id. Se a transação foi criada usando um card_hash, criamos automaticamente esse id com os dados do cartão criptografado no vault da Marlim. Esse card_id pode ser usado em compras futuras.
acquirer_status_codestringCódigo identificador da resposta do Banco Emissor. Valores possíveis: 0000, 1000, 1011, 1016 e 5000.
acquirer_status_messagestringMensagem referente ao código da resposta do Banco Emissor.
Exemplo de Response
{
  "status": "paid",
  "nsu": "98765432",
  "authorization_code": "112233",
  "date_created": "2025-01-01T00:00:00.000Z",
  "date_updated": "2025-01-01T00:00:00.000Z",
  "amount": 1000,
  "authorized_amount": 1000,
  "paid_amount": 1000,
  "refunded_amount": 0,
  "installments": "1",
  "transaction_id": "HcDscltTIVK3VMAAOj7J",
  "card_holder_name": "Luke Skywalker",
  "card_brand": "visa",
  "card_first_digits": "555544",
  "card_last_digits": "2222",
  "card_id": "card_123456789",
  "acquirer_status_code": "0000",
  "acquirer_status_message": "The acquirer captured the amount on the card."
}

Webhook URL​

Todo o processo de mudança de status de uma transação é assíncrono. Por isso, é importante que você passe um webhook_url durante o processo de criação de uma transação para que sua aplicação receba todas as mudanças de status.

Se for passado algum valor no parâmetro webhook_auth_token a Marlim vai enviar o token para a sua aplicação usando o padrão Authorization: Bearer no Header da requisição:

Authorization: Bearer {webhook_auth_token}

Abaixo, a tabela com os valores possíveis de status recebidos no webhook_url.

StatusSignificado
paidTransação paga e capturada com sucesso.
reviewTransação está em processo de revisão manual pelos nossos especialistas.
O valor foi autorizado e reservado no cartão, mas ainda não foi capturado.
refusedTransação recusada pelo banco emissor.
refundedTransação estornada.
chargebackTransação sofreu chargeback.
Exemplo do BODY de um POST da Marlim para a sua aplicação
curl -X POST "https://suaaplicacao.com.br/pedidos/123456789/webhook" \
-H "Content-Type: application/json" \ 
-H "User-Agent: Marlim/1.0.0" \ 
-H "Marlim-Api-Signature: Star98765Wars43210ANewHope1977" \
-d '{
  "event": "transaction_status_changed",
  "transaction_id": "HcDscltTIVK3VMAAOj7J",
  "current_status": "paid",
  "nsu": "98765432",
  "authorization_code": "112233",
  "date_created": "2025-05-28T13:20:21.275Z",
  "date_updated": "2025-05-28T13:20:21.275Z",
  "amount": 1000,
  "paid_amount": 1000,
  "installments": "1",
  "card_holder_name": "Luke Skywalker",
  "card_brand": "visa",
  "card_first_digits": "444455",
  "card_last_digits": "2222",
  "acquirer_status_code": "0000"
}'

Atenção

Você deve validar a origem do webhook, isto é, se ele foi realmente enviado pelos servidores da Marlim.
Para isso, enviamos no HEADER do POST do dois valores:

• User-Agent: sempre com o valor Marlim/1.0.0
• Marlim-Api-Signature: o final da sua api_key removendo os valores mak_test_ e mak_live_

Antifraude​

Para facilitar durante a fase de desenvolvimento você pode simular os status de uma transação em conjunto com o nossos Antifraude para desenvolver esse fluxo na sua aplicação. Você pode simular os status de uma transação, utilizando o parâmetro simulate_status passando os valores: paid, review ou rejected.

Em ambiente de Produção, uma transação com status review será revisada manualmente pelos nossos especialistas. Após essa análise, a transação poderá passar para o status de paid (ou seja, foi aprovada por um especialista) ou refunded (ou seja, foi rejeitada pelo especialista).

Em ambiente Sandbox, você terá acesso a um endpoint para "emular" o status futuro dessa revisão que acontece em Produção: https://api.marlim.co/v3/antifraud podendo passar os valores accept ou reject e o ID de uma transação, seguindo o payload abaixo:

{
  "transaction_id": "HcDscltTIVK3VMAAYC54",
  "status": "accept" // accept || reject
}

Simular Status​

Abaixo, alguns exemplos de simulações utilizando o parâmetro simulate_status e suas variáveis:

Request
curl -X POST "https://api.marlim.co/v3/transactions" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
  "simulate_status": "paid",
  "amount": 1000,
  "installments": "1",
  "item_id": "ABC123456789",
  "soft_descriptor": "Marlim Store",
  "card_holder_name": "Luke Skywalker",
  "card_number": "5555444433332222",
  "card_expiration_date": "1225",
  "card_cvv": "123",
  "customer": {
    "name": "Luke Skywalker",
    "email": "luke@jedimaster.sw",
    "document_number": "00099988877",
    "phone": {
      "country_code": "+55",
      "area_code": "11",
      "number": "999887766"
    },
    "address": {
      "country": "BR",
      "state": "SP",
      "city": "São Paulo",
      "neighborhood": "República",
      "street": "Rua Aurora",
      "number": "123",
      "complement": "Apto 42",
      "zipcode": "01209001"
    }
  },
  "webhook_url": "https://webhook.site/123-456-789",
  "webhook_auth_token": "seu_token_secreto",
  "dfp_id": "ABC123456789"
}'
Response200
{
  "status": "paid",
  "nsu": "98765432",
  "authorization_code": "112233",
  "date_created": "2025-05-28T13:20:21.275Z",
  "date_updated": "2025-05-28T13:20:21.275Z",
  "amount": 1000,
  "paid_amount": 1000,
  "installments": "1",
  "transaction_id": "HcDscltTIVK3VMAAOj7J",
  "card_holder_name": "Luke Skywalker",
  "card_brand": "visa",
  "card_first_digits": "555544",
  "card_last_digits": "2222",
  "acquirer_status_code": "0000",
  "acquirer_status_message": "The acquirer captured the amount on the card."
}
🕹  Criar uma transação com status review, e emular aceitá-la no nosso Antifraude.
Request
curl -X POST "https://api.marlim.co/v3/transactions" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
  "simulate_status": "review",
  "amount": 1000,
  "installments": "1",
  "item_id": "ABC123456789",
  "soft_descriptor": "Marlim Store",
  "card_holder_name": "Luke Skywalker",
  "card_number": "5555444433332222",
  "card_expiration_date": "1225",
  "card_cvv": "123",
  "customer": {
    "name": "Luke Skywalker",
    "email": "luke@jedimaster.sw",
    "document_number": "00099988877",
    "phone": {
      "country_code": "+55",
      "area_code": "11",
      "number": "999887766"
    },
    "address": {
      "country": "BR",
      "state": "SP",
      "city": "São Paulo",
      "neighborhood": "República",
      "street": "Rua Aurora",
      "number": "123",
      "complement": "Apto 42",
      "zipcode": "01209001"
    }
  },
  "webhook_url": "https://webhook.site/123-456-789",
  "webhook_auth_token": "seu_token_secreto",
  "dfp_id": "ABC123456789"
}'
Response200
{
  "status": "review",
  "nsu": "98765432",
  "authorization_code": "112233",
  "date_created": "2025-05-28T13:20:21.275Z",
  "date_updated": "2025-05-28T13:20:21.275Z",
  "amount": 1000,
  "paid_amount": 0,
  "installments": "1",
  "transaction_id": "HcDscltTIVK3VMAAOj7J",
  "card_holder_name": "Luke Skywalker",
  "card_brand": "visa",
  "card_first_digits": "555544",
  "card_last_digits": "2222",
  "acquirer_status_code": "0000",
  "acquirer_status_message": "The bank has authorized this amount on the card."
}
🕹  Criar uma transação com status review, e emular rejeitá-la no nosso Antifraude.
Request
curl -X POST "https://api.marlim.co/v3/transactions" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
  "simulate_status": "review",
  "amount": 1000,
  "installments": "1",
  "item_id": "ABC123456789",
  "soft_descriptor": "Marlim Store",
  "card_holder_name": "Luke Skywalker",
  "card_number": "5555444433332222",
  "card_expiration_date": "1225",
  "card_cvv": "123",
  "customer": {
    "name": "Luke Skywalker",
    "email": "luke@jedimaster.sw",
    "document_number": "00099988877",
    "phone": {
      "country_code": "+55",
      "area_code": "11",
      "number": "999887766"
    },
    "address": {
      "country": "BR",
      "state": "SP",
      "city": "São Paulo",
      "neighborhood": "República",
      "street": "Rua Aurora",
      "number": "123",
      "complement": "Apto 42",
      "zipcode": "01209001"
    }
  },
  "webhook_url": "https://webhook.site/123-456-789",
  "webhook_auth_token": "seu_token_secreto",
  "dfp_id": "ABC123456789"
}'
Response200
{
  "status": "review",
  "nsu": "98765432",
  "authorization_code": "112233",
  "date_created": "2025-05-28T13:20:21.275Z",
  "date_updated": "2025-05-28T13:20:21.275Z",
  "amount": 1000,
  "paid_amount": 0,
  "installments": "1",
  "transaction_id": "HcDscltTIVK3VMAAOj7J",
  "card_holder_name": "Luke Skywalker",
  "card_brand": "visa",
  "card_first_digits": "555544",
  "card_last_digits": "2222",
  "acquirer_status_code": "0000",
  "acquirer_status_message": "The bank has authorized this amount on the card."
}
Atenção

O parâmetro simulate_status e o endpoint v3/antifraud só são habilitados para api_key do Ambiente Sandbox. Se for utilizado um dos 2 em Ambiente de Produção, será retornado um erro 403 (Forbidden).

Recusa Banco Emissor​

Quando uma transação é recusada pelo Banco Emissor, retornamos o status refused com a propriedade acquirer_status_code contendo o código dessa recusa. Como cada bandeira de cartão bem como o banco emissor pode ter um código diferente, a Marlim agrupa o contexto dessa recusa de acordo com a tabela abaixo. No futuro podem ser incluídos novos códigos, uma vez que esse controle está com as bandeiras e os bancos.

A propriedade acquirer_status_message também é retornada com uma mensagem específica para cada código de recusa, conforme a tabela abaixo.

PrefixoSignificado
1000Transação não aprovada pelo banco.

acquirer_status_message
Transaction not approved by your bank. Please contact your bank and try again.
1011Dados incorretos do cartão.

acquirer_status_message
Some of your card numbers are incorrect. Check the numbers and try again.
1016Cartão sem saldo.

acquirer_status_message
The bank informed us that the card balance is insufficient for that amount.
5000Erro bancário genérico.

acquirer_status_message
Your bank declined this purchase but did not tell us why. Contact us to understand your case!

Simular Recusa Bancária​

O fluxo de banco emissor não existe em ambiente Sandbox, então para facilitar na etapa de desenvolvimento separamos o parâmetro simulate_refused_code, que pode ser usado para passar os códigos de recusa descritos acima, conforme os exemplos abaixo.

Request
curl -X POST "https://api.marlim.co/v3/transactions" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
  "simulate_refused_code": "1000",
  "amount": 1000,
  "installments": "1",
  "item_id": "ABC123456789",
  "soft_descriptor": "Marlim Store",
  "card_id": "card_jedi123master4amidala5son",
  "customer": {
    "name": "Luke Skywalker",
    "email": "luke@jedimaster.sw",
    "document_number": "00099988877",
    "phone": {
      "country_code": "+55",
      "area_code": "11",
      "number": "999887766"
    },
    "address": {
      "country": "BR",
      "state": "SP",
      "city": "São Paulo",
      "neighborhood": "República",
      "street": "Rua Aurora",
      "number": "123",
      "complement": "Apto 42",
      "zipcode": "01209001"
    }
  }
}'
Response200
{
  "status": "refused",
  "nsu": "98765434",
  "authorization_code": null,
  "date_created": "2025-05-28T13:20:21.275Z",
  "date_updated": "2025-05-28T13:20:21.275Z",
  "amount": 1000,
  "paid_amount": 0,
  "installments": "1",
  "transaction_id": null,
  "card_holder_name": "Luke Skywalker",
  "card_brand": "visa",
  "card_first_digits": "555544",
  "card_last_digits": "2222",
  "card_id": "card_jedi123master4amidala5son",
  "acquirer_status_code": "1000",
  "acquirer_status_message": "Transaction not approved by your bank. Please contact your bank and try again."
}
Atenção

O parâmetro simulate_refused_code só está habilitado para a api_key do Ambiente Sandbox. Se você passar esses parâmetros em Ambiente de Produção, será retornado um erro 403 (Forbidden).