Cancelar Transação

Disponibilidade

O cancelamento de autorização de cartão está disponível somente no ambiente Sandbox. Não há suporte para cancelamento de autorização em produção no momento.

Esta rota cancela uma transação previamente criada e ainda não finalizada, liberando o valor reservado sem efetuar cobrança. As regras e o objeto de resposta variam de acordo com o método de pagamento da transação:

• Cartão — cancela uma autorização, movendo o status de authorized para canceled. Veja Cancelamento de Cartão.

POSTv3/transactions/:transaction_id/cancel

Request Variable Path

Atributo	Tipo	Descrição
transaction_id	string	ID Marlim da transação com status authorized (cartão).

cuidado

É necessário salvar o transaction_id que a Marlim retorna na solicitação de autorização na sua aplicação. Somente com este id será possível prosseguir com o cancelamento.

Este endpoint não requer body na requisição.

---

Cancelamento de Cartão

Use esta rota para cancelar uma transação de cartão previamente autorizada com o endpoint POST v3/transactions/authorize. O cancelamento libera o valor reservado no cartão do cliente sem efetuar a cobrança, movendo o status da transação de authorized para canceled.

Cancelar vs. Estornar

O cancelamento (cancel) é aplicável a transações de cartão com status authorized — ou seja, o valor foi reservado mas ainda não foi capturado. Nenhum valor é debitado do cliente.

O estorno (refund) é aplicável a transações com status paid — o valor já foi capturado e o estorno devolve o dinheiro ao cliente. Consulte Estornar Transação.

Atenção

Somente transações de cartão com status authorized podem ser canceladas. Tentar cancelar uma transação com qualquer outro status retornará um erro 403.

Response Object — Cartão

Propriedade	Tipo	Descrição
status	string	Representa o estado atual da transação. Para este endpoint, o valor retornado será canceled.
amount	int32	Valor em centavos da transação.
net_value	int32	Parâmetro opcional do valor líquido a ser recebido pela transação.
authorized_amount	int32	Valor em centavos que havia sido autorizado na transação.
paid_amount	int32	Valor em centavos capturado na transação. Retorna 0 pois a transação foi cancelada antes da captura.
refunded_amount	int32	Valor em centavos estornado na transação.
installments	string	Número de parcelas em que o cliente pagou.
nsu	string	Código que identifica a transação na adquirente.
authorization_code	string	Código de autorização retornado pelo banco emissor.
transaction_id	string	Número identificador Marlim da transação.
item_id	string	ID da transação na sua plataforma.
payment_method	string	Método de pagamento utilizado na transação. Valores possíveis: credit_card.
date_created	dateTime	Data de criação da transação no formato ISODateTime.
date_updated	dateTime	Data de atualização do status da transação no formato ISODateTime.
card_holder_name	string	Nome do portador do cartão utilizado no pagamento.
card_brand	string	Bandeira do cartão utilizado no pagamento. Valores possíveis: visa, mastercard, amex, hipercard e elo.
card_first_digits	string	Primeiros 6 dígitos do cartão utilizado no pagamento.
card_last_digits	string	Últimos 4 dígitos do cartão utilizado no pagamento.
acquirer_status_code	string	Código identificador da resposta do Banco Emissor.
acquirer_status_message	string	Mensagem referente ao código da resposta do Banco Emissor.

Exemplo de Response

{
  "status": "canceled",
  "nsu": "98765432",
  "authorization_code": "112233",
  "date_created": "2025-01-01T00:00:00.000Z",
  "date_updated": "2025-01-01T00:00:01.000Z",
  "amount": 1000,
  "authorized_amount": 1000,
  "paid_amount": 0,
  "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",
  "acquirer_status_code": "0000",
  "acquirer_status_message": "The authorization has been canceled."
}

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 Response — Transação não autorizada

{
  "api_reference": "https://docs.api.marlim.co/transactions/create/card",
  "errors": [
    {
      "type": "status",
      "message": "Only transactions with authorized status can be canceled."
    }
  ]
}

Exemplos — Cartão

Cancelamento com Sucesso

Request

curl -X POST "https://api.marlim.co/v3/transactions/HcDscltTIVK3VMAAOj7J/cancel" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{}'

Response200

{
  "status": "canceled",
  "nsu": "98765432",
  "authorization_code": "112233",
  "date_created": "2026-08-04T15:09:06.146Z",
  "date_updated": "2026-08-04T15:09:06.146Z",
  "amount": 1000,
  "authorized_amount": 1000,
  "paid_amount": 0,
  "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",
  "acquirer_status_code": "0000",
  "acquirer_status_message": "The authorization has been canceled."
}

Status inválido

Request

curl -X POST "https://api.marlim.co/v3/transactions/HcDscltTIVK3VMAAOj7J/cancel" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{}'

Response403

{
  "api_reference": "https://docs.api.marlim.co/transactions/create/card",
  "errors": [
    {
      "type": "status",
      "message": "Only transactions with authorized status can be canceled."
    }
  ]
}