Estornar Transação

Atenção

As rotas de Cross Border não estão habilitadas por padrão. Antes de integrar, é necessário alinhamento prévio com os times de Risco e Desenvolvimento da Marlim.

Use esta rota para solicitar o estorno total de uma transação Cross Border elegível, criada com cartão de crédito. Transações que já tenham sido liquidadas não podem ser estornadas.

Transações liquidadas

O estorno de uma transação Cross Border só é possível antes da liquidação. Depois de liquidada, a transação não pode mais ser estornada por esta API.

Antes de solicitar o estorno, confirme que a transação ainda está elegível: o campo crossborder_liquidation, retornado em Retornar Transações, precisa estar false. Se estiver true, o estorno é recusado com o erro 403 do tipo crossborder_liquidation.

No Ambiente Sandbox, é possível criar uma transação já liquidada com o parâmetro simulate_crossborder_liquidation. Veja Simular Liquidação.

Somente estorno total

O Cross Border suporta apenas o estorno total. Quando permitido, o estorno é realizado sobre o valor total da transação.

O estorno parcial não é suportado e, por isso, não é necessário informar nenhum parâmetro no corpo da requisição.

POSTv3/crossborder/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

O objeto de resposta varia de acordo com o método de pagamento utilizado na transação original. Abaixo você encontra a estrutura detalhada para cada tipo de transação:

Credit Card

Propriedade	Tipo	Descrição
status	string	Representa o estado atual da transação. Valor retornado: 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.
payment_method	string	Método de pagamento utilizado na transação. Valores possíveis: credit_card.
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.

Exemplo de payload de resposta de estorno com cartão

{
  "status": "refunded",
  "nsu": "31022400001", 
  "date_created": "2024-02-15T10:30:00.000Z",
  "date_updated": "2024-02-15T11:30:00.000Z",
  "authorized_amount": 1000,
  "paid_amount": 0,
  "refunded_amount": 1000,
  "installments": "1",
  "transaction_id": "HcDscltTIVK3VMAAOj7J",
  "item_id": "ABC987654321",
  "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 amount has been refunded to the card."
}

Exemplos

Estorno Cartão

Request

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

Response200

{
  "status": "refunded",
  "nsu": "31022400001",
  "date_created": "2026-11-04T14:35:14.983Z",
  "date_updated": "2026-11-04T15:35:14.983Z",
  "authorized_amount": 1000,
  "paid_amount": 0,
  "refunded_amount": 1000,
  "installments": "1",
  "transaction_id": "HcDscltTIVK3VMAAOj7J",
  "item_id": "ABC987654321",
  "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 amount has been refunded to the card."
}

Estorno sem Sucesso

Request

curl -X POST "https://api.marlim.co/v3/crossborder/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 já liquidada

Request

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

Response403

{
  "api_reference": "https://docs.api.marlim.co/crossborder/transactions",
  "errors": [
    {
      "type": "crossborder_liquidation",
      "message": "This transaction cannot be refunded because it has already been liquidated."
    }
  ]
}

Transação não encontrada

Request

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