Skip to main content

Authorize Transaction

Sandbox Only

This endpoint is available in the Sandbox environment only. Pre-authorization is not supported in production at this time.

Use this route to authorize a card transaction without immediately capturing it. The amount is reserved on the customer's card, but the actual debit only occurs when the capture is executed.

This flow is recommended when your application needs to confirm the availability of funds before completing the charge — for example, in hotel reservation scenarios, vehicle rentals, or any operation where service confirmation happens after authorization.

After authorization, you must choose between:

POSTv3/transactions/authorize

Request Body Params​

Attention

All fields of type string must be provided with alphanumeric characters without accents or special characters.

The parameters accepted by this endpoint are identical to those of POST v3/transactions. Refer to the transaction creation documentation for the complete list of available fields.

AttributeTypeDescription
amountint32Final amount to be charged to the paying customer. Must be passed in cents.
installmentsstringNumber of transaction installments, with minimum: 1 and maximum: 12.
item_idstringTransaction ID in your platform.
card_holder_namestringName of the cardholder, only letters and spaces without accents or special characters.
If you include a card_id or card_hash, this field becomes optional.
card_numberstringCard number.
If you include a card_id or card_hash, this field becomes optional.
card_expiration_datestringCard expiration date. Numbers only in MMYY format.
If you include a card_id or card_hash, this field becomes optional.
card_cvvstringCard verification code.
If you include a card_id or card_hash, this field becomes optional.
card_idstringID of a previously saved and validated card.
If you include a card_hash or open card data, this field becomes optional.
card_hashstringHash of a card manually encrypted using a public key.
If you include a card_id or open card data, this field becomes optional.
customerobjectCustomer object.
customer[name]stringCustomer name.
customer[email]stringCustomer email.
customer[document_number]stringCustomer document number.
customer[phone]objectCustomer phone number object.
customer[phone][country_code]stringCustomer phone country code (DDI), e.g.: +55.
customer[phone][area_code]stringCustomer phone area code (DDD).
customer[phone][number]stringCustomer phone number.
customer[address]objectCustomer billing or residential address object.
customer[address][country]stringCustomer nationality in country abbreviation format. Only ISO 3166-1 alpha-2 (two-letter) format accepted. E.g.: BR, US, UY...
Maximum characters: 2
customer[address][state]stringState abbreviation of the customer's billing or residential address. E.g.: SP, RJ, MG...
Maximum characters: 2
customer[address][city]stringCity of the customer's billing or residential address.
Maximum characters: 50
customer[address][neighborhood]stringNeighborhood of the customer's billing or residential address.
Maximum characters: 45
customer[address][street]stringStreet of the customer's billing or residential address.
Maximum characters: 54
customer[address][number]stringNumber of the customer's billing or residential address.
Maximum characters: 5
customer[address][complement]stringOptional parameter for the complement of the customer's billing or residential address.
Maximum characters: 14
customer[address][zipcode]stringCustomer's billing or residential address zip code.
Maximum characters: 9
soft_descriptorstringDescription that will appear on your customer's billing statement. Maximum of 13 characters, alphanumeric and spaces.
sub_seller_idstringOptional parameter to identify a sub_seller previously registered with Marlim, responsible for the transaction.
splitarrayOptional parameter for the array of objects with Payment Split data.
split[][sub_seller_id]stringOptional parameter to pass the ID of the partner that will be part of the Payment Split.
split[][amount]int32Amount in cents the partner should receive from the payment. Must be passed in cents.
webhook_urlstringOptional parameter to pass the endpoint of your system that will receive information with each transaction update.
webhook_auth_tokenstringOptional parameter to authenticate notifications sent to webhook_url.
net_valueint32Required parameter if your platform passes on acquirer fees to the end consumer. Net value to be received for the transaction. Must be passed in cents.
dfp_idstringURL ID that makes up the session_id created in the integration with Marlim's Antifraud.
threeds_authentication_idstringOptional parameter that defines the 3DS authentication ID returned by the SDK.
chargeback_ownerstringOptional parameter that defines who will be responsible for chargebacks on the transaction. Accepted values: acquirer or seller. Default: acquirer
Request Body example
{
  "amount": 1000,
  "installments": "1",
  "item_id": "ABC123456789",
  "soft_descriptor": "Marlim Store",
  "card_holder_name": "Luke Skywalker",
  "card_number": "5555444433332222",
  "card_expiration_date": "1225",
  "card_cvv": "123",
  "customer": {
    "name": "Luke Skywalker",
    "email": "luke@jedimaster.sw",
    "document_number": "00099988877",
    "phone": {
      "country_code": "+55",
      "area_code": "11",
      "number": "999887766"
    },
    "address": {
      "country": "BR",
      "state": "SP",
      "city": "São Paulo",
      "neighborhood": "República",
      "street": "Rua Aurora",
      "number": "123",
      "complement": "Apto 42",
      "zipcode": "01209001"
    }
  }
}
Important

Our API does not accept null, undefined or empty string values in any endpoint. If you pass a parameter with any of these 3 values, an error will be returned. If the parameter is not required and you don't want it to be processed, simply remove it from the request.

Response Object​

The response object is identical to POST v3/transactions, with the difference that the status field will return authorized instead of paid.

PropertyTypeDescription
statusstringRepresents the current state of the transaction. For this endpoint, the returned value will always be authorized.
amountint32Amount in cents to be charged in the transaction.
net_valueint32Optional parameter for the net value to be received for the transaction.
authorized_amountint32Amount in cents authorized in the transaction.
paid_amountint32Amount in cents captured in the transaction. Returns 0 while the transaction has authorized status.
refunded_amountint32Amount in cents refunded in the transaction.
installmentsstringNumber of installments the customer paid in.
nsustringCode that identifies the transaction in the Acquirer.
authorization_codestringAuthorization code returned by the issuing bank.
transaction_idstringMarlim transaction identifier number. Save this value to use in the capture and cancel endpoints.
item_idstringTransaction ID in your platform.
payment_methodstringPayment method used in the transaction. Possible values: credit_card.
date_createddateTimeTransaction creation date in ISODateTime format.
date_updateddateTimeTransaction status update date in ISODateTime format.
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.
card_idstring | nullCard ID generated by Marlim after authorization.
acquirer_status_codestringResponse identifier code from the Issuing Bank.
acquirer_status_messagestringMessage regarding the Issuing Bank's response code.
Response example
{
  "status": "authorized",
  "nsu": "98765432",
  "authorization_code": "112233",
  "date_created": "2025-01-01T00:00:00.000Z",
  "date_updated": "2025-01-01T00:00:00.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",
  "card_id": "card_123456789",
  "acquirer_status_code": "0000",
  "acquirer_status_message": "The bank has authorized this amount on the card."
}

Error Object​

AttributeTypeDescription
api_referencestringURL for the documentation.
errorsarrayArray with all errors found when processing the request.
errors[][type]stringType of error that occurred.
errors[][message]stringDetailed message of the error that occurred.
Error Response example
{
  "api_reference": "https://docs.api.marlim.co/transactions/create/card",
  "errors": [
    {
      "type": "amount",
      "message": "The parameter [ amount ] is missing."
    }
  ]
}

Webhook URL​

Just like the transaction creation endpoint, you can pass a webhook_url to receive notifications on each status change.

StatusMeaning
authorizedTransaction authorized by the issuing bank. The amount was reserved on the card but not yet captured.
paidTransaction successfully captured after calling the POST v3/transactions/:transaction_id/capture endpoint.
canceledAuthorization canceled before capture. The reserved amount was released on the card.
refusedTransaction refused by the issuing bank.
failedTransaction with failure in the authorization process at the Acquirer.

Pre-Authorization Flow​

The complete pre-authorization flow works in 3 steps:

Request
curl -X POST "https://api.marlim.co/v3/transactions/authorize" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
  "amount": 1000,
  "installments": "1",
  "item_id": "ABC123456789",
  "soft_descriptor": "Marlim Store",
  "card_id": "card_jedi123master4amidala5son",
  "customer": {
    "name": "Luke Skywalker",
    "email": "luke@jedimaster.sw",
    "document_number": "00099988877",
    "phone": {
      "country_code": "+55",
      "area_code": "11",
      "number": "999887766"
    },
    "address": {
      "country": "BR",
      "state": "SP",
      "city": "São Paulo",
      "neighborhood": "República",
      "street": "Rua Aurora",
      "number": "123",
      "complement": "Apto 42",
      "zipcode": "01209001"
    }
  },
  "webhook_url": "https://webhook.site/123-456-789"
}'
Response200
{
  "status": "authorized",
  "nsu": "98765432",
  "authorization_code": "112233",
  "date_created": "2026-06-09T12:37:17.135Z",
  "date_updated": "2026-06-09T12:37:17.135Z",
  "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",
  "card_id": "card_123456789",
  "acquirer_status_code": "0000",
  "acquirer_status_message": "The bank has authorized this amount on the card."
}
Attention

It is necessary to save the transaction_id returned by this endpoint in your application. Only with this ID will it be possible to capture or cancel the authorization later.