Cancel Authorization

Sandbox Only

This endpoint is available in the Sandbox environment only. Authorization cancellation is not supported in production at this time.

Use this route to cancel a transaction previously authorized with the POST v3/transactions/authorize endpoint. Canceling releases the reserved amount on the customer's card without making any charge, moving the transaction status from authorized to canceled.

Cancel vs. Refund

Canceling (cancel) applies only to transactions with authorized status — meaning the amount was reserved but not yet captured. No amount is charged to the customer.

Refunding (refund) applies to transactions with paid status — the amount has already been captured and the refund returns the money to the customer. See Refund Transaction.

Attention

Only transactions with authorized status can be canceled. Attempting to cancel a transaction with any other status will return a 403 error.

POSTv3/transactions/:transaction_id/cancel

Request Variable Path

Attribute	Type	Description
transaction_id	string	Marlim transaction ID with authorized status.

caution

It is necessary to save the transaction_id that Marlim returns in the authorization request in your application. Only with this ID will it be possible to proceed with the cancellation.

This endpoint does not require a body in the request.

Response Object

Property	Type	Description
status	string	Represents the current state of the transaction. For this endpoint, the returned value will be canceled.
amount	int32	Amount in cents of the transaction.
net_value	int32	Optional parameter for the net value to be received for the transaction.
authorized_amount	int32	Amount in cents that had been authorized in the transaction.
paid_amount	int32	Amount in cents captured in the transaction. Returns 0 as the transaction was canceled before capture.
refunded_amount	int32	Amount in cents refunded in the transaction.
installments	string	Number of installments the customer paid in.
nsu	string	Code that identifies the transaction in the Acquirer.
authorization_code	string	Authorization code returned by the issuing bank.
transaction_id	string	Marlim transaction identifier number.
item_id	string	Transaction ID in your platform.
payment_method	string	Payment method used in the transaction. Possible values: credit_card.
date_created	dateTime	Transaction creation date in ISODateTime format.
date_updated	dateTime	Transaction status update date in ISODateTime format.
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.
acquirer_status_message	string	Message regarding the Issuing Bank's response code.

Response example

{
  "status": "canceled",
  "nsu": "98765432",
  "authorization_code": "112233",
  "date_created": "2025-01-01T00:00:00.000Z",
  "date_updated": "2025-01-01T00:00:01.000Z",
  "amount": 1000,
  "authorized_amount": 1000,
  "paid_amount": 0,
  "refunded_amount": 0,
  "installments": "1",
  "transaction_id": "HcDscltTIVK3VMAAOj7J",
  "item_id": "ABC123456789",
  "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 authorization has been canceled."
}

Error Object

Attribute	Type	Description
api_reference	string	URL for the documentation.
errors	array	Array with all errors found when processing the request.
errors[][type]	string	Type of error that occurred.
errors[][message]	string	Detailed message of the error that occurred.

Error Response example — Transaction not authorized

{
  "api_reference": "https://docs.api.marlim.co/transactions/create/card",
  "errors": [
    {
      "type": "status",
      "message": "Only transactions with authorized status can be canceled."
    }
  ]
}

Examples

Successful Cancellation

Request

curl -X POST "https://api.marlim.co/v3/transactions/HcDscltTIVK3VMAAOj7J/cancel" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{}'

Response200

{
  "status": "canceled",
  "nsu": "98765432",
  "authorization_code": "112233",
  "date_created": "2026-06-09T12:37:17.142Z",
  "date_updated": "2026-06-09T12:37:17.142Z",
  "amount": 1000,
  "authorized_amount": 1000,
  "paid_amount": 0,
  "refunded_amount": 0,
  "installments": "1",
  "transaction_id": "HcDscltTIVK3VMAAOj7J",
  "item_id": "ABC123456789",
  "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 authorization has been canceled."
}

Invalid status

Request

curl -X POST "https://api.marlim.co/v3/transactions/HcDscltTIVK3VMAAOj7J/cancel" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{}'

Response403

{
  "api_reference": "https://docs.api.marlim.co/transactions/create/card",
  "errors": [
    {
      "type": "status",
      "message": "Only transactions with authorized status can be canceled."
    }
  ]
}