Pular para o conteúdo principal

Criar Transação com Cartão

Essa rota deve ser usada para criar uma transação com cartã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.

POSTv3/transactions

Request Body Params​

AtributoTipoDescrição
amountint32Valor final a ser cobrado do cliente pagador. 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.
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
soft_descriptorstringDescrição que aparecerá na fatura do seu cliente. Máximo de 13 caracteres, sendo alfanuméricos e espaços.
sub_seller_idstringParâmetro opcional para identificar um sub_seller cadastrado na Marlim anteriormente, responsável pela transação.
splitarrayParâmetro opcional para o array de objetos com os dados do Split de Pagamento.
split[][sub_seller_id]stringParâmetro opcional para passar o ID do parceiro que fará parte do Split de Pagamento.
split[][amount]int32Valor em centavos que o parceiro deverá receber do pagamento. Deve ser passado em centavos.
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.
external_sub_seller_document_numberstringParâmetro opcional para informar o CNPJ do seu parceiro de venda.
external_sub_seller_idstringParâmetro opcional para informar o ID na sua plataforma do seu parceiro de venda.
chargeback_ownerstringParâmetro opcional que define quem será responsável pelo chargeback da transação. Valores aceitos: acquirer ou seller
Default: acquirer
simulate_statusstringParâmetro opcional que pode ser passado em ambiente de teste para simular o fluxo do Antifraude. Valores aceitos: paid, failed, 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.
metadataobjectParâmetro opcional para informações adicionais.
metadata[customer_registration_date]dateTimeParâmetro opcional da data de abertura do cadastro do usuário na sua plataforma no formato ISODateTime.
metadata[customer_first_transaction_date]dateTimeParâmetro opcional da data da primeira operação concretizada (paga) na sua plataforma, independente de ter sido processada pela Marlim ou não, no formato ISODateTime.
metadata[customer_last_transaction_date]dateTimeParâmetro opcional da data da última operação concretizada (paga) na sua plataforma, independente de ter sido processada pela Marlim ou não, no formato ISODateTime.
metadata[customer_paid_proposals]int32Parâmetro opcional da quantidade de propostas concretizadas (pagas) pelo cliente na sua plataforma, independente de ter sido processada pela Marlim ou não.
metadata[sub_seller_social_name]stringParâmetro opcional do nome fantasia do sub_seller.
metadata[sub_seller_document]stringParâmetro opcional do Tax-ID do sub_seller.
metadata[sub_seller_cnae]stringParâmetro opcional do CNAE do sub_seller.
metadata[sub_seller_segment]stringParâmetro opcional do segmento de negócio do sub_seller.
metadata[sub_seller_app_name]stringParâmetro opcional referente ao nome do app do sub_seller, podendo também ser informada a URL do app.
metadata[sub_seller_date_created]dateTimeParâmetro opcional da data de criação do sub_seller no seller no formato ISODateTime.
metadata[sub_seller_country_operation]stringParâmetro opcional do país de operação do sub_seller.
metadata[sub_seller_state_operation]stringParâmetro opcional da UF fiscal de operação do sub_seller somente quando o país de operação for Brasil.
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.

Split de Pagamento​

A Marlim oferece a opção de Split de Pagamento para que sua aplicação possa criar uma transação com múltiplos recebedores, basta passar um array de objetos com sub_seller_id e amount no parâmetro split no corpo da requisição.

🕹  Exemplo de Request Body com Split de Pagamento
  {
    "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"
      }
    },
    "split": [
      {
        "sub_seller_id": "sub_k4m6Rw5rlQszEY7fiuRe",
        "amount": 900
      }
    ]
  }

Chargeback​

O parâmetro chargeback_owner define a responsabilidade pelos chargebacks nas transações:

  • acquirer: a Marlim assume a responsabilidade pelos chargebacks
  • seller: sua Empresa assume a responsabilidade pelos chargebacks
Importante

Quando chargeback_owner for seller, as parcelas são calculadas com taxas específicas para essa modalidade, resultando em valores finais diferentes dos cálculados quando a responsabilidade é da Marlim.

Caso sua empresa repasse a taxa de adquirência para o seu cliente final, utilize o endpoint de Parcelas para que você tenha certeza do valor correto a ser cobrado na transação.

🕹  Exemplo de Request Body com a sua empresa responsável pelo Chargeback
  {
    "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"
      }
    },
    "chargeback_owner": "seller"
  }

Response Object​

PropriedadeTipoDescrição
statusstringRepresenta o estado atual da transação. Valores possíveis: paid, review, rejected, refused e failed.
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.
item_idstringID da transação na sua plataforma.
payment_methodstringMétodo de pagamento utilizado na transação. Valores possíveis: credit_card.
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.
splitarrayArray de objetos com os dados do Split de Pagamento.
split[][sub_seller_id]stringID do parceiro que fará parte do Split de Pagamento.
split[][amount]int32Valor em centavos que o parceiro deverá receber do pagamento.
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",
  "item_id": "ABC123456789",
  "payment_method": "credit_card",
  "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."
}

Error Object​

AtributoTipoDescrição
api_referencestringUrl para a documentação.
errorsarrayArray com todos os erros encontrados ao processar a requisição.
errors[][type]stringTipo de erro ocorrido.
errors[][message]stringMensagem detalhada do erro ocorrido.
Exemplo de um Response com Erro
{
  "api_reference": "https://docs.api.marlim.co/transactions/create/card",
  "errors": [
    {
      "type": "amount",
      "message": "The parameter [ amount ] is missing."
    }
  ]
}

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.
failedTransação com falha no processo de captura na Adquirente.
refundedTransação estornada.
chargebackTransação sofreu chargeback.
Exemplo do BODY de um WEBHOOK 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",
  "item_id": "ABC123456789",
  "payment_method": "credit_card",
  "current_status": "paid",
  "nsu": "98765432",
  "authorization_code": "112233",
  "date_created": "2025-08-27T15:32:46.106Z",
  "date_updated": "2025-08-27T15:32:46.106Z",
  "amount": 1000,
  "paid_amount": 1000,
  "installments": "1",
  "card_holder_name": "Luke Skywalker",
  "card_brand": "visa",
  "card_first_digits": "444455",
  "card_last_digits": "2222",
  "sub_seller_id": "sub_k4m6Rw5rlQszEY7fiuRe",
  "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
}
🕹  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",
  "payment_method": "credit_card",
  "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": "2024-01-01T10:00:00.000Z",
  "date_updated": "2024-01-01T10:00:00.000Z",
  "amount": 1000,
  "paid_amount": 1000,
  "installments": "1",
  "transaction_id": "HcDscltTIVK3VMAAOj7J",
  "item_id": "ABC123456789",
  "payment_method": "credit_card",
  "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",
  "payment_method": "credit_card",
  "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-08-27T15:32:46.107Z",
  "date_updated": "2025-08-27T15:32:46.107Z",
  "amount": 1000,
  "paid_amount": 0,
  "installments": "1",
  "transaction_id": "HcDscltTIVK3VMAAOj7J",
  "item_id": "ABC123456789",
  "payment_method": "credit_card",
  "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",
  "payment_method": "credit_card",
  "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-08-27T15:32:46.107Z",
  "date_updated": "2025-08-27T15:32:46.107Z",
  "amount": 1000,
  "paid_amount": 0,
  "installments": "1",
  "transaction_id": "HcDscltTIVK3VMAAOj7J",
  "item_id": "ABC123456789",
  "payment_method": "credit_card",
  "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!

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.

🕹  Exemplos de simulações utilizando o parâmetro simulate_refused_code 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_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-08-27T15:32:46.107Z",
  "date_updated": "2025-08-27T15:32:46.107Z",
  "amount": 1000,
  "paid_amount": 0,
  "installments": "1",
  "transaction_id": null,
  "item_id": "ABC123456789",
  "payment_method": "credit_card",
  "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).

Exemplos em Transações​

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 (dados de cartão e cliente). Se você utilizar valores fictícios o Antifraude pode não funcionar de forma esperada.

Sucesso​

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",
  "net_value": 1000,
  "amount": 1098,
  "installments": "1",
  "item_id": "ABC123456789",
  "card_hash": "93237fb4c0948881dc99929899f6eda2_CdJrwrJ3iwVk8hTjM0jTVOz4vm7hJUckoPkLGvn+IBexY89sSdRFNozTCj1SopGs7iIhoRqH5FdXDwebIF605jOeURCJjZbv2EhQZPtJdM3689+hIyZWT/bXL2J8db2UHG+DYDqTnu1f8eY+AqsuOphCKw6q916L8M36RErtRFjxtYq9epsipjnG4nAKJRb8tx23xpEY0D1qHQiAMoAtI6FNcTj+tiYzZO757WMC4PbiyRdgSLjlNlSAeaLLKnPidQxLM+62MasL2rFpz8YZQ182vJXWvLE8fL6pXflwhoxqkyDZ9ySWInKEl+ydentxkCZkAj4htXRdF4bTX5KTXLzY11erHh4MaZZYYJk/jymid6dAqGJrTXsGrwVJB0JDVwThSxE6ashxAko9Ic1iLIDapXvUz6J8BZ2PSwAeu0Ed3RgbJ8vHby3R3alvVPNDGjvQqUqxAwhABKXdXRBY6Iw6oUETnMNHyeA9KBq0FcAVKomZS5fH7PIsse9lKqJP6YGUWBhc19H8iFowhbYdvpgDvW4uo4G/fJvLdXUnX1KIDR0wTxgEeI9dV66mwho7sa+EPxzTY/q5g2bGM3GpQDZTGaJyyTBu8IaawOZNEYLls+0T2B9pA0aBBrqV72IKbBC7/WdUcIUM+T9lqJdabCxM5b0g+pijFgkYfMWnmcM=",
  "soft_descriptor": "Marlim Store",
  "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-08-27T15:32:46.107Z",
  "date_updated": "2025-08-27T15:32:46.107Z",
  "amount": 1000,
  "authorized_amount": 1000,
  "paid_amount": 1000,
  "refunded_amount": 0,
  "installments": "1",
  "transaction_id": "HcDscltTIVK3VMAAOj7J",
  "item_id": "ABC123456789",
  "payment_method": "credit_card",
  "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."
}

Erros​

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",
  "net_value": 1000,
  "amount": 1098,
  "installments": "1",
  "item_id": "ABC123456789",
  "card_hash": "93237fb4c0948881dc99929899f6eda2_CdJrwrJ3iwVk8hTjM0jTVOz4vm7hJUckoPkLGvn+IBexY89sSdRFNozTCj1SopGs7iIhoRqH5FdXDwebIF605jOeURCJjZbv2EhQZPtJdM3689+hIyZWT/bXL2J8db2UHG+DYDqTnu1f8eY+AqsuOphCKw6q916L8M36RErtRFjxtYq9epsipjnG4nAKJRb8tx23xpEY0D1qHQiAMoAtI6FNcTj+tiYzZO757WMC4PbiyRdgSLjlNlSAeaLLKnPidQxLM+62MasL2rFpz8YZQ182vJXWvLE8fL6pXflwhoxqkyDZ9ySWInKEl+ydentxkCZkAj4htXRdF4bTX5KTXLzY11erHh4MaZZYYJk/jymid6dAqGJrTXsGrwVJB0JDVwThSxE6ashxAko9Ic1iLIDapXvUz6J8BZ2PSwAeu0Ed3RgbJ8vHby3R3alvVPNDGjvQqUqxAwhABKXdXRBY6Iw6oUETnMNHyeA9KBq0FcAVKomZS5fH7PIsse9lKqJP6YGUWBhc19H8iFowhbYdvpgDvW4uo4G/fJvLdXUnX1KIDR0wTxgEeI9dV66mwho7sa+EPxzTY/q5g2bGM3GpQDZTGaJyyTBu8IaawOZNEYLls+0T2B9pA0aBBrqV72IKbBC7/WdUcIUM+T9lqJdabCxM5b0g+pijFgkYfMWnmcM=",
  "soft_descriptor": "Marlim Store",
  "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"
}'
Response400
{
  "api_reference": "https://docs.api.marlim.co/transactions/create/card",
  "errors": [
    {
      "type": "invalid_card_hash",
      "message": "This card_hash is no longer valid. Create a new one, or use a card_id."
    }
  ]
}