Refund Transaction

Attention

Cross Border routes are not enabled by default. Before integrating, prior alignment with Marlim's Risk and Development teams is required.

Use this route to request the full refund of an eligible Cross Border transaction, created with credit card. Transactions that have already been settled cannot be refunded.

Settled transactions

A Cross Border transaction can only be refunded before settlement. Once settled, the transaction can no longer be refunded through this API.

Before requesting a refund, confirm that the transaction is still eligible: the crossborder_liquidation field, returned by Return Transactions, must be false. If it is true, the refund is refused with a 403 error of type crossborder_liquidation.

In the Sandbox Environment, you can create an already settled transaction with the simulate_crossborder_liquidation parameter. See Simulate Settlement.

Full refund only

Cross Border supports full refunds only. When allowed, the refund is performed on the total amount of the transaction.

Partial refund is not supported and, therefore, no parameter needs to be provided in the request body.

POSTv3/crossborder/transactions/:transaction_id/refund

Request Variable Path

Attribute	Type	Description
transaction_id	string	Marlim 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

Property	Type	Description
status	string	Represents the current state of the transaction. Returned value: refunded.
nsu	string	Code that identifies the transaction in the Acquirer.
date_created	dateTime	Transaction creation date in ISODateTime format.
date_updated	dateTime	Transaction status update date in ISODateTime format.
authorized_amount	int32	Amount in cents authorized in the transaction.
paid_amount	int32	Amount in cents captured in the transaction.
refunded_amount	int32	Amount in cents refunded in the transaction.
installments	string	Number of installments the customer paid in.
transaction_id	string	Transaction identifier number in Marlim.
item_id	string	Transaction ID in your platform.
payment_method	string	Payment method used in the transaction. Possible values: credit_card.
card_holder_name	string	Name of the cardholder used in payment.
card_brand	string	Card brand used in payment. Possible values: visa, mastercard, amex, hipercard and elo.
card_first_digits	string	First 6 digits of the card used in payment.
card_last_digits	string	Last 4 digits of the card used in payment.
acquirer_status_code	string	Response identifier code from the Issuing Bank. Possible values: 0000.
acquirer_status_message	string	Message 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."
}

Examples

Card Refund

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

Unsuccessful Refund

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."
  }
}

Transaction already settled

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 '{}'

Response403

{
  "api_reference": "https://docs.api.marlim.co/crossborder/transactions",
  "errors": [
    {
      "type": "crossborder_liquidation",
      "message": "This transaction cannot be refunded because it has already been liquidated."
    }
  ]
}

Transaction not found

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."
  }
}