Pular para o conteúdo principal

Estornar Transação

Versão atual

Esta é a versão atual da rota de estorno. Se você ainda usa a v3, migre até 31/12/2026. Veja Migrando da v3.

Use esta rota para estornar uma transação previamente paga, podendo ser utilizada para estornar transações criadas com cartão de crédito ou pix.

POSTv3.1/transactions/:transaction_id/refund
Contas com Cross Border

Esta rota não está disponível para contas com Cross Border habilitado e retorna 403 com o erro forbidden. Use Estornar transação Cross Border.

Request Variable Path​

AtributoTipoDescrição
transaction_idstringID 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.

Migrando da v3​

As adquirentes passaram a confirmar o estorno de forma assíncrona. Para quem já usa a v3, estas são as mudanças:

  • Endpoint: a rota passa de /v3/transactions/:transaction_id/refund para /v3.1/transactions/:transaction_id/refund. O corpo da requisição não muda.
  • Resposta da requisição: na v3, o estorno total de cartão de crédito retornava refunded na hora. Na v3.1, todo estorno retorna refund_pending na resposta síncrona. Estorno parcial e Pix já funcionavam assim e não mudam.
  • Resultado final por webhook: a confirmação (refunded) ou a falha (refund_failed) chega depois, via webhook. Para recebê-lo, é preciso ter informado um webhook_url ao criar a transação.
  • Falha no estorno: se o estorno falhar, a transação continua paga e é possível solicitar um novo estorno.

Estorno parcial​

Por padrão, ao solicitar um estorno o valor total da transação é estornado. Caso deseje estornar apenas uma parte do valor, informe o parâmetro amount no corpo da requisição.

AtributoTipoDescrição
amountint32Valor em centavos a ser estornado. Deve ser menor que o valor total da transação. Quando não informado, o estorno será do valor total.
Exemplo de payload de requisição de estorno parcial
{
  "amount": 500
}
Regras do estorno parcial

O estorno parcial está disponível apenas para transações pagas com cartão de crédito. Transações Pix são sempre estornadas pelo valor total.

Solicitações de estorno parcial só são aceitas 24 horas após a criação da transação. Tentativas antes desse prazo retornarão erro.

Só é permitida uma única tentativa de estorno parcial por transação. Uma vez solicitado, não é possível fazer novas tentativas para a mesma transação.

Caso ocorra alguma falha com o processamento do estorno parcial junto a adquirente, enviaremos um webhook com o status refund_failed, nesses casos é possível fazer uma nova tentativa de estorno parcial.

Resposta síncrona​

O estorno parcial é processado de forma assíncrona junto à Adquirente. Por isso, a resposta síncrona da requisição sempre retorna o status refund_pending.

PropriedadeTipoDescrição
statusstringRepresenta o estado atual da transação.

Valor retornado: refund_pending.
nsustringCódigo que identifica a transação na Adquirente.
date_createddateTimeData de criação da transação no formato ISODateTime.
date_updateddateTimeData de atualização do status da transação no formato ISODateTime.
authorized_amountint32Valor em centavos autorizado na transação.
paid_amountint32Valor em centavos que permanece capturado na transação, já descontado o valor solicitado para estorno.
refunded_amountint32Valor em centavos solicitado para estorno.
installmentsstringNúmero de parcelas em que o cliente pagou.
transaction_idstringNúmero identificador da transação na Marlim.
item_idstringNúmero identificador da transação na sua plataforma.
payment_methodstringMétodo de pagamento utilizado na transação. Valor retornado: credit_card.
card_holder_namestringNome do portador do cartão utilizado no pagamento.
card_brandstringBandeira do cartão utilizado no pagamento.
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.
acquirer_status_codestringCódigo identificador da resposta do Banco Emissor.
acquirer_status_messagestringMensagem referente ao código da resposta do Banco Emissor.
Exemplo de resposta síncrona de estorno parcial
{
  "status": "refund_pending",
  "nsu": "31022400001",
  "date_created": "2024-02-14T10:30:00.000Z",
  "date_updated": "2024-02-15T14:30:00.000Z",
  "authorized_amount": 1000,
  "paid_amount": 500,
  "refunded_amount": 500,
  "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 partial refund request was received and is being processed."
}

Webhook​

O resultado final do estorno parcial pode levar até 72 horas para ser concluído. Assim que a Adquirente confirmar ou recusar o estorno, você será notificado através de webhook, caso tenha configurado um webhook_url quando criou a transação, com o status refunded (sucesso) ou refund_failed (falha).

Request
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" \ 
-H "Authorization: Bearer 123456" \
-d '{
  "event": "transaction_status_changed",
  "current_status": "refunded",
  "transaction_id": "HcDscltTIVK3VMAAOj7J",
  "item_id": "ABC987654321",
  "payment_method": "credit_card",
  "date_created": "2024-02-14T10:30:00.000Z",
  "date_updated": "2026-11-03T17:17:46.951Z",
  "nsu": "31022400001",
  "authorized_amount": 1000,
  "paid_amount": 500,
  "refunded_amount": 500,
  "installments": "1",
  "card_holder_name": "Luke Skywalker",
  "card_brand": "visa",
  "card_first_digits": "555544",
  "card_last_digits": "2222",
  "acquirer_status_code": "0000"
}'

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​

O estorno com cartão de crédito é processado de forma assíncrona junto à Adquirente. A resposta síncrona da requisição sempre retorna o status refund_pending. A confirmação (refunded) ou a falha (refund_failed) chega depois, pelo webhook.

PropriedadeTipoDescrição
statusstringRepresenta o estado atual da transação.

Valor retornado: refund_pending.
nsustring Código que identifica a transação na Adquirente.
date_createddateTimeData de criação da transação no formato ISODateTime.
date_updateddateTimeData de atualização do status da transação no formato ISODateTime.
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.
transaction_idstringNúmero identificador da transação na Marlim.
item_idstringNúmero identificador da transação na sua plataforma.
payment_methodstringMétodo de pagamento utilizado na transação. Valores possíveis: credit_card.
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.
acquirer_status_codestringCódigo identificador da resposta do Banco Emissor.

Valores possíveis: 0000.
acquirer_status_messagestringMensagem referente ao código da resposta do Banco Emissor.
Exemplo de payload de resposta de estorno com cartão
{
  "status": "refund_pending",
  "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 refund request was received and is being processed."
}

Webhook​

Assim que a Adquirente confirmar ou recusar o estorno, você será notificado através de webhook, caso tenha configurado um webhook_url quando criou a transação, com o status refunded (sucesso) ou refund_failed (falha).

Request
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" \ 
-H "Authorization: Bearer 123456" \
-d '{
  "event": "transaction_status_changed",
  "current_status": "refunded",
  "transaction_id": "HcDscltTIVK3VMAAOj7J",
  "item_id": "ABC987654321",
  "payment_method": "credit_card",
  "date_created": "2024-02-14T10:30:00.000Z",
  "date_updated": "2026-11-03T17:17:46.951Z",
  "nsu": "31022400001",
  "authorized_amount": 1000,
  "paid_amount": 0,
  "refunded_amount": 1000,
  "installments": "1",
  "card_holder_name": "Luke Skywalker",
  "card_brand": "visa",
  "card_first_digits": "555544",
  "card_last_digits": "2222",
  "acquirer_status_code": "0000"
}'

Pix​

PropriedadeTipoDescrição
statusstringRepresenta o estado atual da transação.

Valores possíveis: refund_pending.
date_createddateTimeData de criação da transação no formato ISODateTime.
date_updateddateTimeData de atualização do status da transação no formato ISODateTime.
item_idstringID da transação na sua plataforma.
transaction_idstringNúmero identificador Marlim da transação.
amountint32Valor em centavos a ser cobrado na transação.
paid_amountint32Valor em centavos capturado na transação.
payout_amountint32Valor em centavos a ser repassado.
refunded_amountint32Valor em centavos estornado na transação.
Exemplo de payload de resposta de estorno com pix
{
  "status": "refund_pending",
  "date_created": "2025-07-09T14:46:20.598Z", 
  "date_updated": "2025-07-09T14:46:20.598Z",
  "item_id": "ABC123456789",
  "transaction_id": "mMaNRQqDAypdGatmyquR",
  "amount": 1000,
  "payout_amount": 1000,
  "paid_amount": 1000,
  "refunded_amount": 0
}

Webhook Pix​

O processo de estorno Pix é assíncrono. Ao solicitar um estorno, a transação passará imediatamente para o status refund_pending enquanto processamos a solicitação junto à Adquirente. O resultado do estorno será notificado através de webhook, caso você tenha configurado um webhook_url quando criou a transação.

Estorno com Falha

Caso ocorra algum problema durante o processo de estorno, será enviado um webhook onde a transação continuará com o status paid mas com uma nova propriedade no payload com o nome de refund_status com valor refund_failed.
Este cenário indica que a tentativa atual de estorno falhou e a transação permanece paga, mas uma nova tentativa de estorno pode ser feita posteriormente.

🕹  Exemplos de respostas de webhook de estorno com sucesso ou falha.
Request
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" \ 
-H "Authorization: Bearer 123456" \
-d '{
  "event": "transaction_status_changed",
  "current_status": "refunded",
  "transaction_id": "HcDscltTIVK3VMAAOj7J",
  "item_id": "ABC123456789",
  "payment_method": "pix",
  "date_created": "2026-11-03T17:17:46.951Z",
  "date_updated": "2026-11-03T17:17:46.951Z",
  "amount": 1000,
  "paid_amount": 0,
  "payout_amount": -1000,
  "refunded_amount": 1000
}'

Exemplos​

Request
curl -X POST "https://api.marlim.co/v3.1/transactions/HcDscltTIVK3VMAAOj7J/refund" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{}'
Response200
{
  "status": "refund_pending",
  "nsu": "31022400001",
  "date_created": "2026-11-03T17:17:46.951Z",
  "date_updated": "2026-11-03T18:17:46.951Z",
  "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 refund request was received and is being processed."
}