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

Uma transação Cross Border pode ser estornada somente enquanto ainda não tiver sido liquidada.

Após a liquidação da transação, o estorno não estará mais disponível e a operação é considerada irreversível através desta API.

Antes de solicitar o estorno, certifique-se de que a transação ainda esteja elegível para essa operaçã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-09-16T13:47:36.794Z",
  "date_updated": "2026-09-16T14:47:36.794Z",
  "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 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."
  }
}