Skip to main content

Create Crossborder Transaction

Attention

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

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/crossborder/transactions
Transaction routes for accounts with Cross Border

For accounts with Cross Border enabled, the standard transaction routes return 403. Use the Cross Border equivalents:

Pix, pre-authorization, capture and cancellation are not available. GET v3/card_hash_key stays enabled to create the card_hash.

Request Body Params​

Attention

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

AttributeTypeDescription
amountint32Transaction amount, always in cents, in the currency set by currency.

With currency = BRL (default), it is the final amount charged from the end consumer.
E.g.: R$ 1,000.00 → 100000

With currency = USD, it is the transaction amount in dollars. The consumer is charged in reais, at the exchange rate applied at the time of the transaction.
E.g.: US$ 184.02 → 18402
currencystringOptional parameter that sets the currency of amount. Accepted values: BRL and USD.
Default: BRL
installmentsstringNumber of installments for the transaction, with minimum: 1 and maximum: 12.
item_idstringTransaction ID in your platform.
card_holder_namestringCardholder name, letters and spaces only, no 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 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 CPF.
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]stringPartner 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. It is recommended to provide it: when the operation takes longer than the synchronous response window, this request returns 408 and the final outcome arrives here. See Synchronous response and webhook.
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.
Not accepted when currency is not BRL.
dfp_idstringURL 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, 1018 and 5000.
simulate_crossborder_liquidationbooleanOptional parameter, available only in the Sandbox Environment, that creates the transaction already settled so you can test the blocked refund flow. See Simulate Settlement.

Transaction currency​

The currency parameter sets which currency the amount is in, and that is what decides who absorbs the exchange costs.

currencyWhat you fixWhat is charged on the card
BRL (default)The amount in reais charged from the end consumer.The amount itself. Exchange costs are absorbed by the seller, who receives the converted amount already net of fees.
USDThe price announced in dollars.The conversion of that amount into reais, with no fees added on top. Exchange costs are absorbed by the seller, who receives less than the announced amount. The charged value is defined at the time of the transaction and returned in the amount field of the response.
Attention

With currency set to USD, the amount charged in reais is only known at the time of the transaction, since it depends on the exchange rate. Example: 8599 (US$ 85.99) charges around R$ 446.60 from the consumer, and the seller receives around US$ 82.37, already net of exchange costs.

Because of that, the parameters net_value, split and threeds_authentication_id are not accepted in this mode.

The converted amount must be at least 50 USD. In reais, this minimum varies with the exchange rate.

To estimate these values before transacting, use the Exchange Quote route.

Request Body Example in dollars
{
  "amount": 18402,
  "currency": "USD",
  "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": "Sao Paulo",
      "neighborhood": "Republica",
      "street": "Rua Aurora",
      "number": "123",
      "complement": "Apto 42",
      "zipcode": "01209001"
    }
  }
}
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 orders effectively completed by the customer via PIX from an account under their own ownership, regardless of whether they were processed by Marlim.
More information
  • Example 1: If the customer with CPF 123.456.789-00 made 5 PIX payments from an account owned by CPF 123.456.789-00, the parameter to be sent must be 5.
  • Example 2: If the customer with CPF 123.456.789-00 made 2 BOLETO payments, this parameter does not need to be sent (boleto is not a payment instrument for which we can guarantee ownership).
  • Example 3: If the customer with CPF 123.456.789-00 made 2 CREDIT CARD payments, this parameter does not need to be sent (credit card is not a payment instrument for which we can guarantee ownership).
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"
  }
}

Response Object​

PropertyTypeDescription
statusstringRepresents the current state of the transaction. Possible values: authorized, rejected, refused and failed.

Use POST v3/transactions/authorize to create a transaction with authorized status.
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, 1018 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.
exchangeobjectForeign exchange data of the remittance. Values are in currency units (not in cents).
exchange[indicative]booleanfalse when the rate is the one locked when the exchange was closed (the one applied). true when it is only a preview.
exchange[currency]stringCurrency of exchange[amount], received by the seller. E.g.: USD.
exchange[pay_currency]stringCurrency the paying customer is charged in. The other values in this object are in this currency. E.g.: BRL.
exchange[amount]numberAmount in the exchange[currency] currency.
exchange[price]numberTotal amount in the exchange[pay_currency] currency: amount_converted + spread_amount + operation_fees.
exchange[amount_converted]numberexchange[amount] converted at the spot_rate.
exchange[spot_rate]numberCommercial exchange rate applied.
exchange[vet]numberTotal Effective Rate (VET): the final rate of the operation, including spread and fees (price / amount).
exchange[spread_rate]numberSpread rate applied on the converted amount, as a fraction (e.g.: 0.009 = 0.9%).
exchange[spread_amount]numberSpread amount in the exchange[pay_currency] currency.
exchange[operation_fees]numberOperation fees (including taxes) in the exchange[pay_currency] currency.
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.",
  "exchange": {
    "indicative": false,
    "currency": "USD",
    "pay_currency": "BRL",
    "amount": 187.4,
    "price": 1000.03,
    "amount_converted": 957.88,
    "spot_rate": 5.1114,
    "vet": 5.3363,
    "spread_rate": 0.009,
    "spread_amount": 8.6209,
    "operation_fees": 33.5258
  }
}

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/crossborder/transactions",
  "errors": [
    {
      "type": "amount",
      "message": "The parameter [ amount ] is missing."
    }
  ]
}

If the Cross Border routes are not enabled for your account, the request returns 403:

Error Response Example when Cross Border is not enabled (403)
{
  "api_reference": "https://docs.api.marlim.co/crossborder/transactions",
  "errors": [
    {
      "type": "forbidden",
      "message": "Cross Border routes are not enabled for this account. Please contact the Marlim team to enable this feature."
    }
  ]
}

Synchronous response and webhook​

Unlike a regular transaction, a Cross Border transaction involves the international partner that performs the remittance. Marlim waits for the outcome and tries to respond synchronously, but that wait has a limit.

Two possible paths for the same transaction

1. Outcome within the window. The response is 200 with the final status (paid, refused or rejected), as in any transaction.

2. Outcome outside the window. The response is 408 with the transaction_id in the message:

{
  "errors": [
    {
      "type": "timeout",
      "message": "Transaction [ 3IF9NlZJnzwLKrgrmNRK ] is still processing. Use GET /v3/crossborder/transactions to check the final status."
    }
  ]
}
A 408 does NOT mean the transaction failed

The operation continues and completes normally. The 408 only means there was no time to respond synchronously. Never retry the request after a 408, since that would create a new transaction. Instead, get the outcome through one of two paths:

  • via webhook_url, which receives the outcome when it happens, the recommended path;
  • by querying Read Transactions with the transaction_id returned in the message.

That is why webhook_url is the mechanism that guarantees your platform always learns the outcome, even when the synchronous response is not possible.

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.
authorizedTransaction authorized by the issuing bank, but not yet captured. Available when using the POST v3/transactions/authorize endpoint.
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.
canceledAuthorized transaction canceled before capture. The reserved amount was released on the card. Available when using the POST v3/transactions/:transaction_id/cancel endpoint.
chargebackTransaction suffered chargeback.

The webhook also includes the exchange object, with the remittance's foreign exchange data (same fields as the Response Object).

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-10-30T18:58:53.410Z",
  "date_updated": "2026-10-30T18:58:53.410Z",
  "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",
  "exchange": {
    "indicative": false,
    "currency": "USD",
    "pay_currency": "BRL",
    "amount": 187.4,
    "price": 1000.03,
    "amount_converted": 957.88,
    "spot_rate": 5.1114,
    "vet": 5.3363,
    "spread_rate": 0.009,
    "spread_amount": 8.6209,
    "operation_fees": 33.5258
  }
}'

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. To do this, send a PATCH request to /v3/antifraud with the transaction ID and the new analysis status. The status field accepts accept or reject:

Request
curl -X PATCH "https://sandbox.api.marlim.co/v3/antifraud" \
  -H "Content-Type: application/json" \
  -H "api_key: api_key_value" \
  -d '{
    "transaction_id": "HcDscltTIVK3VMAAOj7J",
    "status": "accept"
  }'
Response 200
{
  "updated": true
}
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.
1018Allowed number of installments exceeded.

acquirer_status_message
The bank informed us that the number of installments is exceeded.
5000Generic banking refusal.

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.

🕹  Examples of simulations using the parameter simulate_refused_code and its variables:
Request
curl -X POST "https://api.marlim.co/v3/crossborder/transactions" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
  "simulate_refused_code": "1000",
  "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"
    }
  }
}'
Response200
{
  "status": "refused",
  "nsu": "98765434",
  "authorization_code": null,
  "date_created": "2026-10-30T18:58:53.410Z",
  "date_updated": "2026-10-30T18:58:53.410Z",
  "amount": 1000,
  "paid_amount": 0,
  "installments": "1",
  "transaction_id": null,
  "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_jedi123master4amidala5son",
  "acquirer_status_code": "1000",
  "acquirer_status_message": "Transaction not approved by your bank. Please contact your bank and try again.",
  "exchange": {
    "indicative": false,
    "currency": "USD",
    "pay_currency": "BRL",
    "amount": 187.4,
    "price": 1000.03,
    "amount_converted": 957.88,
    "spot_rate": 5.1114,
    "vet": 5.3363,
    "spread_rate": 0.009,
    "spread_amount": 8.6209,
    "operation_fees": 33.5258
  }
}
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.

Simulate Settlement​

Every Cross Border transaction is created not settled: crossborder_liquidation = false and crossborder_liquidation_date = null. While it is not settled, it can be refunded. Once settled, the refund is refused. The current state is returned by the Return Transactions route.

To test a settled transaction in the Sandbox Environment, send simulate_crossborder_liquidation: true on creation. The transaction is created with crossborder_liquidation = true and crossborder_liquidation_date set to the creation date and time. With false, or without the parameter, it is created not settled.

Request
curl -X POST "https://api.marlim.co/v3/crossborder/transactions" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
  "simulate_status": "paid",
  "simulate_crossborder_liquidation": true,
  "amount": 1000,
  "installments": "1",
  "item_id": "ABC123456789",
  "card_hash": "{{card_hash}}",
  "customer": {
    "+n": "..."
  }
}'
Response200
{
  "status": "paid",
  "transaction_id": "HcDscltTIVK3VMAAOj7J",
  "+n": "..."
}
Attention

The simulate_crossborder_liquidation parameter is only accepted in the Sandbox Environment. In the Production Environment, sending it (even as false) returns a 400 (Bad Request) error and the transaction is not created. In Sandbox, a non-boolean value also returns 400.

Examples​

Request
curl -X POST "https://api.marlim.co/v3/crossborder/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-10-30T18:58:53.410Z",
  "date_updated": "2026-10-30T19:58:53.410Z",
  "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",
  "exchange": {
    "indicative": false,
    "currency": "USD",
    "pay_currency": "BRL",
    "amount": 187.4,
    "price": 1000.03,
    "amount_converted": 957.88,
    "spot_rate": 5.1114,
    "vet": 5.3363,
    "spread_rate": 0.009,
    "spread_amount": 8.6209,
    "operation_fees": 33.5258
  }
}