Estornar Transação

Use esta rota para estornar uma transação previamente paga.

POSTv3/transactions/:transaction_id/refund

Request Variable Path

Atributo	Tipo	Descrição
transaction_id	string	ID Marlim da transação.

cuidado

É necessário salvar o transaction_id que a Marlim retorna nas solicitações de criação na sua aplicação. Somente com este id será possível para prosseguir com o estorno.

Response Object

Propriedade	Tipo	Descrição
status	string	Representa o estado atual da transação. Valores possíveis: refunded.
nsu	string	Código que identifica a transação na Adquirente.
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.
authorized_amount	int32	Valor em centavos autorizado na transação.
paid_amount	int32	Valor em centavos capturado na transação.
refunded_amount	int32	Valor em centavos estornado na transação.
installments	string	Número de parcelas em que o cliente pagou.
transaction_id	string	Número identificador da transação na Marlim.
item_id	string	Número identificador da transação na sua plataforma.
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. Valores possíveis: 0000.
acquirer_status_message	string	Mensagem referente ao código da resposta do Banco Emissor.

Exemplos

Estorno com Sucesso

Request

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

Response200

{
  "status": "refunded",
  "nsu": "31022400001",
  "date_created": "2025-05-28T13:20:21.548Z",
  "date_updated": "2025-05-28T14:20:21.548Z",
  "authorized_amount": 1000,
  "paid_amount": 0,
  "refunded_amount": 1000,
  "installments": "1",
  "transaction_id": "HcDscltTIVK3VMAAOj7J",
  "item_id": "ABC987654321",
  "card_holder_name": "Luke Skywalker",
  "card_brand": "visa",
  "card_first_digits": "555544",
  "card_last_digits": "2222",
  "acquirer_status_code": "0000",
  "acquirer_status_message": "The amount has been refunded to the card."
}

Estorno sem Sucesso

Request

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

Response400

{
  "errors": {
    "type": "status",
    "message": "Only transactions with paid status can be refunded."
  }
}

Transação não encontrada

Request

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

Response404

{
  "errors": {
    "type": "Transaction with id [ AABBCCDD ] was not found."
  }
}