Skip to main content

Refund Transaction

Use this route to refund a previously paid transaction, which can be used to refund transactions created with credit card or pix.

POSTv3/transactions/:transaction_id/refund

Request Variable Path​

AttributeTypeDescription
transaction_idstringMarlim transaction ID.
caution

It is necessary to save the transaction_id that Marlim returns in creation requests in your application. Only with this ID will it be possible to proceed with the refund.

Response Object​

The response object varies according to the payment method used in the original transaction. Below you will find the detailed structure for each transaction type:

Credit Card​

PropertyTypeDescription
statusstringRepresents the current state of the transaction.

Possible values: refunded.
nsustringCode that identifies the transaction in the Acquirer.
date_createddateTimeTransaction creation date in ISODateTime format.
date_updateddateTimeTransaction status update date in ISODateTime format.
authorized_amountint32Amount in cents authorized in the transaction.
paid_amountint32Amount in cents captured in the transaction.
refunded_amountint32Amount in cents refunded in the transaction.
installmentsstringNumber of installments the customer paid in.
transaction_idstringTransaction identifier number in Marlim.
item_idstringTransaction ID in your platform.
payment_methodstringPayment method used in the transaction. Possible values: credit_card.
card_holder_namestringName of the cardholder used in payment.
card_brandstringCard brand used in payment.

Possible values: visa, mastercard, amex, hipercard and elo.
card_first_digitsstringFirst 6 digits of the card used in payment.
card_last_digitsstringLast 4 digits of the card used in payment.
acquirer_status_codestringResponse identifier code from the Issuing Bank.

Possible values: 0000.
acquirer_status_messagestringMessage regarding the Issuing Bank's response code.
Credit card refund response payload example
{
  "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."
}

Pix​

PropertyTypeDescription
statusstringRepresents the current state of the transaction.

Possible values: refund_pending.
date_createddateTimeTransaction creation date in ISODateTime format.
date_updateddateTimeTransaction status update date in ISODateTime format.
item_idstringTransaction ID in your platform.
transaction_idstringMarlim transaction identifier number.
amountint32Amount in cents to be charged in the transaction.
paid_amountint32Amount in cents captured in the transaction.
payout_amountint32Amount in cents to be transferred.
refunded_amountint32Amount in cents refunded in the transaction.
Pix refund response payload example
{
  "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
}

Pix Webhook​

The Pix refund process is asynchronous. When requesting a refund, the transaction will immediately change to refund_pending status while we process the request with the Acquirer. The refund result will be notified through webhook, if you have configured a webhook_url when creating the transaction.

Refund with Failure

If any problem occurs during the refund process, a webhook will be sent where the transaction will continue with paid status but with a new property in the payload named refund_status with value refund_failed.
This scenario indicates that the current refund attempt failed and the transaction remains paid, but a new refund attempt can be made later.

🕹  Examples of successful or failed refund webhook responses.
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": "2025-07-29T11:38:57.894Z",
  "date_updated": "2025-07-29T11:38:57.894Z",
  "amount": 1000,
  "paid_amount": 0,
  "payout_amount": -1000,
  "refunded_amount": 1000
}'

Examples​

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-07-29T11:38:57.894Z",
  "date_updated": "2025-07-29T12:38:57.894Z",
  "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."
}