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​

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).
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.
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.
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.

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, expired, failed, refunded and chargeback.
nsustringCode that identifies the transaction in the Acquirer.
date_createddateTimeTransaction creation date in ISODateTime format.
date_updateddateTimeTransaction status update date in ISODateTime format.
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.
transaction_idstringTransaction identifier number in Marlim.
item_idstringTransaction ID in your platform.
payment_methodstringPayment method used in the transaction. Possible values: credit_card.
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.
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.
card_idstringID of the saved card for future purchases.

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": "2025-07-29T11:38:57.815Z",
  "date_updated": "2025-07-29T12:38:57.815Z",
  "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"
}