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.

Partial Refund​

By default, when requesting a refund the total amount of the transaction is refunded. If you want to refund only part of the amount, provide the amount parameter in the request body.

AttributeTypeDescription
amountint32Amount in cents to be refunded. Must be less than the total transaction amount. When not provided, the total amount will be refunded.
Partial refund request payload example
{
  "amount": 500
}
Partial refund rules

Partial refund is available only for transactions paid with credit card. Pix transactions are always refunded for the total amount.

Partial refund requests are only accepted 24 hours after the transaction is created. Attempts before this period will return an error.

Only a single attempt at partial refund is allowed per transaction. Once requested, it is not possible to try again — neither to repeat the request nor to refund the remaining amount.

Synchronous Response​

The partial refund is processed asynchronously with the Acquirer. Therefore, the request's synchronous response always returns the refund_pending status.

PropertyTypeDescription
statusstringRepresents the current state of the transaction.

Returned value: refund_pending.
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 that remains captured in the transaction, after deducting the amount requested for refund.
refunded_amountint32Amount in cents requested for refund.
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. Returned value: credit_card.
card_holder_namestringName of the cardholder used in payment.
card_brandstringCard brand used in payment.
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.
acquirer_status_messagestringMessage regarding the Issuing Bank's response code.
Partial refund synchronous response example
{
  "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​

The final result of the partial refund can take up to 72 hours to complete. As soon as the Acquirer confirms or declines the refund, you will be notified via webhook — if you have configured a webhook_url when creating the transaction — with the status refunded (success) or refund_failed (failure).

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-08-07T15:40:07.437Z",
  "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​

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 and refund_pending (partial refund, see the Partial Refund section).
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": "2026-08-07T15:40:07.437Z",
  "date_updated": "2026-08-07T15:40:07.437Z",
  "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": "2026-08-07T15:40:07.437Z",
  "date_updated": "2026-08-07T16:40:07.437Z",
  "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."
}