Skip to main content

Refund Transaction

Current version

This is the current version of the refund route. If you still use v3, migrate by 31/12/2026. See Migrating from v3.

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

POSTv3.1/transactions/:transaction_id/refund
Accounts with Cross Border

This route is not available for accounts with Cross Border enabled and returns 403 with the forbidden error. Use Refund Cross Border transaction instead.

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.

Migrating from v3​

The acquirers now confirm refunds asynchronously. If you already use v3, these are the changes:

  • Endpoint: the route changes from /v3/transactions/:transaction_id/refund to /v3.1/transactions/:transaction_id/refund. The request body does not change.
  • Request response: in v3, a full credit card refund returned refunded right away. In v3.1, every refund returns refund_pending in the synchronous response. Partial and Pix refunds already worked this way and do not change.
  • Final result via webhook: the confirmation (refunded) or the failure (refund_failed) arrives later via webhook. To receive it, you must have provided a webhook_url when creating the transaction.
  • Refund failure: if the refund fails, the transaction remains paid and a new refund can be requested.

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 for the same transaction.

If the partial refund fails to be processed by the acquirer, we will send a webhook with the status refund_failed. In these cases, a new partial refund attempt can be made.

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-10-30T18:58:54.418Z",
  "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​

Credit card refunds are processed asynchronously with the Acquirer. The synchronous response always returns the refund_pending status. Confirmation (refunded) or failure (refund_failed) arrives later, through the webhook.

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 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": "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​

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-10-30T18:58:54.418Z",
  "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​

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-10-30T18:58:54.418Z",
  "date_updated": "2026-10-30T18:58:54.418Z",
  "amount": 1000,
  "paid_amount": 0,
  "payout_amount": -1000,
  "refunded_amount": 1000
}'

Examples​

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-10-30T18:58:54.418Z",
  "date_updated": "2026-10-30T19:58:54.418Z",
  "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."
}