Skip to main content

Create Card Transaction

To make a charge you must use this route and create your transaction.

It is possible to use a card_hash, card_id or all card data directly (card_holder_name, card_number, card_expiration_date and card_cvv). The first option is the most recommended for security reasons.

Every time a transaction is successfully completed in our systems, a card_id will be returned that can be used in future purchases. So using card_hash for the first purchase and a card_id for future purchases, you further increase the security of your customer's data without needing to expose sensitive card data.

Marlim is a PCI Compliant company, meaning we are audited to follow all market security rules aimed at protecting your customers' card data. If your system is not enabled to create card_hash, you can transact securely with open card data, since our systems encrypt all data and only our Acquirer (who processes the payment with the Issuing Bank) has access to the real card data. In the following link, we describe the step-by-step process of how to create a card_hash.

POSTv3/transactions

Request Body Params​

Attention

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

AttributeTypeDescription
amountint32Final amount to be charged from the end consumer. Must be passed in cents.
installmentsstringNumber of installments for the transaction, with minimum: 1 and maximum: 12.
item_idstringTransaction ID in your platform.
card_holder_namestringCardholder name.
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 manually encrypted card 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). Ex: +55.
customer[phone][area_code]stringCustomer phone state code (DDD).
customer[phone][number]stringCustomer phone number.
customer[address]objectCustomer Address object.
customer[address][country]stringCustomer nationality, in country code format. Only ISO 3166-1 alpha-2 (two-letters) format will be accepted. Ex: BR, US, UY...
Maximum characters: 2
customer[address][state]stringCustomer's current address state, in state code format. Ex: SP, RJ, MG...
Maximum characters: 2
customer[address][city]stringCustomer address city.
Maximum characters: 50
customer[address][neighborhood]stringCustomer address neighborhood.
Maximum characters: 45
customer[address][street]stringCustomer address street.
Maximum characters: 54
customer[address][number]stringCustomer's current address number.
Maximum characters: 5
customer[address][complement]stringOptional parameter for customer's current address complement.
Maximum characters: 14
customer[address][zipcode]stringCustomer ZIP code.
Maximum characters: 9
soft_descriptorstringDescription that will appear on your customer's invoice. Maximum of 13 characters, alphanumeric and spaces.
sub_seller_idstringOptional parameter to identify a sub_seller previously registered at Marlim, responsible for the transaction.
splitarrayOptional parameter for array of objects with Split Payment data.
split[][sub_seller_id]stringOptional parameter to pass the partner ID that will be part of the Split Payment.
split[][amount]int32Amount in cents that 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. If the parameter is not provided, notifications will be sent without authentication.
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_idstringOptional parameter of the URL ID that makes up the session_id created in the integration with Marlim's Antifraud.
external_sub_seller_document_numberstringOptional parameter to inform the CNPJ of your sales partner.
external_sub_seller_idstringOptional parameter to inform the ID in your platform of your sales partner.
threeds_authentication_idstringOptional parameter that defines the 3DS authentication ID returned by the SDK. It is required when 3DS authentication is performed.
chargeback_ownerstringOptional parameter that defines who will be responsible for the transaction chargeback. Accepted values: acquirer or seller
Default: acquirer
simulate_statusstringOptional parameter that can be passed in test environment to simulate the Antifraud flow. Accepted values: paid, failed, review and rejected.
simulate_refused_codestringOptional parameter that can be passed in test environment to simulate the negative returns flow from the issuing bank.

Accepted values: 1000, 1011, 1016 and 5000.
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 mandatory and you don't want it to be computed, simply remove it from the request.

Cart Items​

AttributeTypeDescription
cart_itemsarrayOptional parameter list of cart items. When provided, must contain at least 1 item.
cart_items[][unit_price]int32Unit price of the item in cents. Ex.: $100.00 → 10000
cart_items[][quantity]int32Quantity of the item. Integer > 0
cart_items[][product_sku]stringProduct SKU (identifier in your system).
cart_items[][product_name]stringProduct name.
Request Body Example with cart items (cart_items)
{
  "amount": 12500,
  "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"
    }
  },
  "cart_items": [
    {
      "unit_price": 5000,
      "quantity": 2,
      "product_sku": "SKU-001",
      "product_name": "Lightsaber"
    },
    {
      "unit_price": 2500,
      "quantity": 1,
      "product_sku": "SKU-002",
      "product_name": "Jedi Robe"
    }
  ]
}

Shipping Data​

AttributeTypeDescription
ship_toobjectOptional parameter shipping information (recipient).
ship_to[address]objectShipping address object.
ship_to[address][country]stringShipping destination country, in country code format. Only ISO 3166-1 alpha-2 (two-letters) format accepted. Ex: BR, US, UY
Maximum characters: 2
ship_to[address][state]stringShipping destination state, in state code format. Ex: SP, RJ, MG
Maximum characters: 2
ship_to[address][city]stringShipping destination city.
Maximum: 50 characters.
ship_to[address][neighborhood]stringShipping destination neighborhood.
Maximum: 45 characters.
ship_to[address][street]stringShipping destination street/address.
Maximum: 54 characters.
ship_to[address][number]stringShipping destination address number.
Maximum: 5 characters.
ship_to[address][complement]stringOptional complement.
Maximum: 30 characters.
ship_to[address][zipcode]stringShipping destination ZIP code. Accepts hyphen and is normalized to digits. For BR, must contain 8–9 digits.
ship_to[customer]objectShipping recipient object.
ship_to[customer][name]stringFull name of the shipping recipient.
ship_to[customer][phone]objectShipping recipient phone.
ship_to[customer][phone][country_code]stringShipping recipient DDI. Digits only.
Size: 1–4.
ship_to[customer][phone][area_code]stringShipping recipient DDD. Digits only.
Size: 2–3.
ship_to[customer][phone][number]stringShipping recipient phone number. Digits only.
Size: 8–9.
Request Body Example with shipping data (ship_to)
{
  "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"
    }
  },
  "ship_to": {
    "address": {
      "country": "BR",
      "state": "SP",
      "city": "São Paulo",
      "neighborhood": "República",
      "street": "Rua Aurora",
      "number": "123",
      "complement": "Apto 42",
      "zipcode": "01209001"
    },
    "customer": {
      "name": "Luke Skywalker",
      "phone": {
        "country_code": "55",
        "area_code": "11",
        "number": "999887766"
      }
    }
  }
}

Travel Information​

AttributeTypeDescription
travel_informationobjectOptional parameter travel information.
travel_information[actual_final_destination]stringFinal destination airport in IATA code (3 letters). Ex.: JFK
travel_information[complete_route]stringComplete concatenated route. Ex.: "JFK-LHR:GRU-JFK:LHR-CDG", "JFK-LHR:GRU-JFK" or "GRU-JFK"
travel_information[departure]objectTrip departure date and time.
travel_information[departure][date]stringDate in YYYY-MM-DD format. Ex.: 2025-09-15
travel_information[departure][time]stringTime in HH:mm or HH:mm:ss (24h) format. Ex.: 22:30
travel_information[journey_type]stringJourney type. Accepted values: oneway, roundtrip, OneWay, RoundTrip, ONEWAY, ROUNDTRIP, Oneway, Roundtrip
travel_information[number_of_passengers]integerTotal number of passengers.
travel_information[passengers]arrayList of passengers.
travel_information[passengers][][name]stringFull name of the passenger.
travel_information[legs]arrayTrip legs/flights.
travel_information[legs][][origination]stringOrigin airport (IATA 3 letters). Ex.: JFK
travel_information[legs][][destination]stringDestination airport (IATA 3 letters). Ex.: CDG
travel_information[legs][][departure]objectLeg departure date and time.
travel_information[legs][][departure][date]stringDate in YYYY-MM-DD format. Ex.: 2025-09-15
travel_information[legs][][departure][time]stringTime in HH:mm or HH:mm:ss format. Ex.: 22:30:15
travel_information[legs][][carrier_code]stringAirline code (IATA 2 characters, e.g. AA, LA, G3)
travel_information[line_items]arrayTravel items (tickets/products).
travel_information[line_items][][unit_price]int32Unit price of the item in cents. Ex.: $100.00 → 10000
travel_information[line_items][][quantity]int32Item quantity. Integer > 0
travel_information[line_items][][product_sku]stringProduct SKU.
travel_information[line_items][][product_name]stringProduct name or description.
travel_information[line_items][][passenger]objectPassenger data linked to the item.
travel_information[line_items][][passenger][type]stringPassenger type. Accepted values: ADT, CNN, INF, YTH, STU, SCR, MIL
travel_information[line_items][][passenger][status]stringInternal passenger/booking status (e.g.: standard, gold, platinum, according to your domain).
travel_information[line_items][][passenger][name]stringFull name of the passenger.
travel_information[line_items][][passenger][email]stringPassenger email.
travel_information[line_items][][passenger][document_number]stringDocument (CPF/Passport). Digits only when applicable.
travel_information[line_items][][passenger][country]stringCountry in ISO 3166-1 alpha-2 format (two letters). Ex.: BR
travel_information[line_items][][passenger][phone]objectPassenger phone.
travel_information[line_items][][passenger][phone][country_code]stringDDI. Digits only.
Size: 1–4.
travel_information[line_items][][passenger][phone][area_code]stringDDD. Digits only.
Size: 2–3.
travel_information[line_items][][passenger][phone][number]stringPhone number. Digits only.
Size: 8–9.
Request Body Example with travel information (travel_information)
{
  "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": "62239006005",
    "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"
    }
  },
  "travel_information": {
    "actual_final_destination": "CDG",
    "complete_route": "JFK-LHR:GRU-JFK:LHR-CDG",
    "departure": {
      "date": "2025-09-15",
      "time": "22:30"
    },
    "journey_type": "roundtrip",
    "number_of_passengers": 2,
    "passengers": [
      { "name": "JOHN DOE" },
      { "name": "JANE DOE" }
    ],
    "legs": [
      {
        "origination": "GRU",
        "destination": "JFK",
        "departure": { "date": "2025-09-15", "time": "22:30" },
        "carrier_code": "AA"
      },
      {
        "origination": "JFK",
        "destination": "GRU",
        "departure": { "date": "2025-09-22", "time": "18:00" },
        "carrier_code": "AA"
      }
    ],
    "line_items": [
      {
        "unit_price": 1500,
        "quantity": 1,
        "product_sku": "TICKET-GRU-JFK-001",
        "product_name": "Flight Ticket - São Paulo → New York",
        "passenger": {
          "type": "ADT",
          "status": "platinum",
          "name": "JOHN DOE",
          "email": "john.doe@example.com",
          "document_number": "62374860035",
          "country": "BR",
          "phone": {
            "country_code": "55",
            "area_code": "11",
            "number": "999999999"
          }
        }
      },
      {
        "unit_price": 1500,
        "quantity": 1,
        "product_sku": "TICKET-GRU-JFK-002",
        "product_name": "Flight Ticket - New York → São Paulo",
        "passenger": {
          "type": "ADT",
          "status": "gold",
          "name": "JANE DOE",
          "email": "jane.doe@example.com",
          "document_number": "62374860035",
          "country": "BR",
          "phone": {
            "country_code": "55",
            "area_code": "11",
            "number": "988887777"
          }
        }
      }
    ]
  }
}

Metadata​

AttributeTypeDescription
metadataobjectOptional parameter for additional information.
metadata[customer_registration_date]dateTimeOptional parameter for the customer registration date on your platform in ISODateTime format.
metadata[customer_first_transaction_date]dateTimeOptional parameter for the date of the first completed (paid) transaction on your platform, regardless of whether it was processed by Marlim or not, in ISODateTime format.
metadata[customer_last_transaction_date]dateTimeOptional parameter for the date of the last completed (paid) transaction on your platform, regardless of whether it was processed by Marlim or not, in ISODateTime format.
metadata[customer_paid_proposals]int32Optional parameter for the number of completed (paid) proposals by the customer on your platform, regardless of whether it was processed by Marlim or not.
metadata[sub_seller_social_name]stringOptional parameter for the sub_seller's trade name.
metadata[sub_seller_document]stringOptional parameter for the sub_seller's Tax-ID.
metadata[sub_seller_cnae]stringOptional parameter for the sub_seller's CNAE.
metadata[sub_seller_segment]stringOptional parameter for the sub_seller's business segment.
metadata[sub_seller_app_name]stringOptional parameter for the sub_seller's app name, which can also be the app URL.
metadata[sub_seller_date_created]dateTimeOptional parameter for the sub_seller creation date in the seller in ISODateTime format.
metadata[sub_seller_country_operation]stringOptional parameter for the sub_seller's country of operation.
metadata[sub_seller_state_operation]stringOptional parameter for the sub_seller's fiscal state of operation only when the country of operation is Brazil.
Request Body Example with metadata
{
  "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"
    }
  },
  "metadata": {
    "customer_registration_date": "2023-01-15T14:32:00Z",
    "customer_first_transaction_date": "2023-02-10T12:00:00Z",
    "customer_last_transaction_date": "2025-08-20T09:45:30Z",
    "customer_paid_proposals": 12,
    "sub_seller_social_name": "Jedi Supplies LTDA",
    "sub_seller_document": "12345678000190",
    "sub_seller_cnae": "4751201",
    "sub_seller_segment": "Sports Articles",
    "sub_seller_app_name": "JediShop App",
    "sub_seller_date_created": "2022-11-01T10:00:00Z",
    "sub_seller_country_operation": "BR",
    "sub_seller_state_operation": "SP"
  }
}

Split Payment​

Marlim offers the Split Payment option so that your application can create a transaction with multiple recipients, just pass an array of objects with sub_seller_id and amount in the split parameter in the request body.

🕹  Request Body example with Split Payment
  {
    "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"
      }
    },
    "split": [
      {
        "sub_seller_id": "sub_k4m6Rw5rlQszEY7fiuRe",
        "amount": 900
      }
    ]
  }

Chargeback​

The parameter chargeback_owner defines the responsibility for chargebacks in transactions:

  • acquirer: Marlim assumes responsibility for chargebacks
  • seller: your Company assumes responsibility for chargebacks
Important

When chargeback_owner is seller, installments are calculated with specific fees for this modality, resulting in different final values from those calculated when responsibility is Marlim's.

If your company passes on acquirer fees to your end customer, use the Installments endpoint so that you are sure of the correct amount to be charged in the transaction.

🕹  Request Body example with your company responsible for Chargeback
  {
    "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"
      }
    },
    "chargeback_owner": "seller"
  }

Response Object​

PropertyTypeDescription
statusstringRepresents the current state of the transaction. Possible values: paid, review, rejected, refused and failed.
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.
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_idstringTransaction identifier number in Marlim.
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 | nullWhen a transaction is completed with status paid, we always return a card_id. If the transaction was created using a card_hash, we automatically create this id with the card data encrypted in Marlim's vault. This card_id can be used in future purchases.
acquirer_status_codestringResponse identifier code from the Issuing Bank. Possible values: 0000, 1000, 1011, 1016 and 5000.
acquirer_status_messagestringMessage regarding the Issuing Bank's response code.
splitarrayArray of objects with Split Payment data.
split[][sub_seller_id]stringPartner ID that is part of the Split Payment.
split[][amount]int32Amount in cents that the partner should receive from the payment.
Response Example
{
  "status": "paid",
  "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": 1000,
  "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 acquirer captured the amount on the card."
}

Error Object​

AttributeTypeDescription
api_referencestringURL to 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​

The entire process of changing a transaction's status is asynchronous. Therefore, it's important that you pass a webhook_url during the transaction creation process so that your application receives all status changes.

If any value is passed in the webhook_auth_token parameter, Marlim will send the token to your application using the Authorization: Bearer standard in the request Header:

Authorization: Bearer {webhook_auth_token}

Below is the table with possible status values received at the webhook_url.

StatusMeaning
paidTransaction paid and captured successfully.
reviewTransaction is under manual review process by our specialists.
The amount was authorized and reserved on the card, but not yet captured.
refusedTransaction refused by the issuing bank.
failedTransaction with failure in the capture process at the Acquirer.
refundedTransaction refunded.
chargebackTransaction suffered chargeback.
Example of WEBHOOK BODY from Marlim to your application
curl -X POST "https://yourapplication.com/orders/123456789/webhook" \
-H "Content-Type: application/json" \ 
-H "User-Agent: Marlim/1.0.0" \ 
-H "Marlim-Api-Signature: Star98765Wars43210ANewHope1977" \
-d '{
  "event": "transaction_status_changed",
  "transaction_id": "HcDscltTIVK3VMAAOj7J",
  "item_id": "ABC123456789",
  "payment_method": "credit_card",
  "current_status": "paid",
  "nsu": "98765432",
  "authorization_code": "112233",
  "date_created": "2026-01-15T17:36:12.609Z",
  "date_updated": "2026-01-15T17:36:12.609Z",
  "amount": 1000,
  "paid_amount": 1000,
  "installments": "1",
  "card_holder_name": "Luke Skywalker",
  "card_brand": "visa",
  "card_first_digits": "444455",
  "card_last_digits": "2222",
  "sub_seller_id": "sub_k4m6Rw5rlQszEY7fiuRe",
  "acquirer_status_code": "0000"
}'

Attention

You must validate the webhook origin, that is, if it was really sent by Marlim's servers.
For this, we send two values in the HEADER of the POST:

• User-Agent: always with the value Marlim/1.0.0
• Marlim-Api-Signature: the end of your api_key removing the values mak_test_ and mak_live_

Antifraud​

To make it easier during the development phase, you can simulate the status of a transaction together with our Antifraud to develop this flow in your application. You can simulate the status of a transaction using the parameter simulate_status passing the values: paid, review or rejected.

In Production environment, a transaction with status review will be manually reviewed by our specialists. After this analysis, the transaction may change to paid status (i.e., it was approved by a specialist) or refunded (i.e., it was rejected by the specialist).

In Sandbox environment, you will have access to an endpoint to "emulate" the future status of this review that happens in Production: https://api.marlim.co/v3/antifraud where you can pass the values accept or reject and the ID of a transaction, following the payload below:

{
  "transaction_id": "HcDscltTIVK3VMAAYC54",
  "status": "accept" // accept || reject
}
Attention

The parameter simulate_status and the endpoint v3/antifraud are only enabled for api_key from the Sandbox Environment. If used in Production Environment, a 403 (Forbidden) error will be returned.

Issuing Bank Refusal​

When a transaction is refused by the Issuing Bank, we return the status refused with the property acquirer_status_code containing the refusal code. Since each card brand as well as the issuing bank can have a different code, Marlim groups the context of this refusal according to the table below. In the future, new codes may be included, as this control is with the brands and banks.

The property acquirer_status_message is also returned with a specific message for each refusal code, as shown in the table below.

PrefixMeaning
1000Transaction not approved by the bank.

acquirer_status_message
Transaction not approved by your bank. Please contact your bank and try again.
1011Incorrect card data.

acquirer_status_message
Some of your card numbers are incorrect. Check the numbers and try again.
1016Card without balance.

acquirer_status_message
The bank informed us that the card balance is insufficient for that amount.
5000Generic banking error.

acquirer_status_message
Your bank declined this purchase but did not tell us why. Contact us to understand your case!

The issuing bank flow does not exist in Sandbox environment, so to make it easier during the development stage we have the parameter simulate_refused_code, which can be used to pass the refusal codes described above.

Attention

The parameter simulate_refused_code is only enabled for api_key from the Sandbox Environment. If you pass these parameters in Production Environment, a 403 (Forbidden) error will be returned.

Examples​

Request
curl -X POST "https://api.marlim.co/v3/transactions" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
  "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"
    }
  }
}'
Response200
{
  "status": "paid",
  "nsu": "032416400102",
  "date_created": "2026-01-15T17:36:12.609Z",
  "date_updated": "2026-01-15T18:36:12.609Z",
  "authorized_amount": 1000,
  "paid_amount": 1000,
  "refunded_amount": 0,
  "installments": "1",
  "transaction_id": "k4m6Rw5rlQszEY7fiuRe",
  "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 acquirer captured the amount on the card.",
  "card_id": "card_k4m6Rw5rlQszEY7fiuRe"
}