Skip to main content

Create Payment Link

This route should be used to create a Payment Link.

Important

All our links have a default validity of 24 hours. After this period, the link is automatically expired. This value can be changed according to your needs, just contact our Development team.

POSTv3/link_payment

Request Body Params​

Attention

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

AttributeTypeDescription
net_valueint32Net value to be received from the transaction. Must be passed in cents.
item_idstringPayment ID in your platform.
soft_descriptorstringDescription that will appear on your customer's invoice if a transaction occurs. Maximum of 13 characters, alphanumeric and spaces.
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.
webhook_urlstringOptional parameter to pass your system's endpoint 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.
simulate_statusstringOptional parameter that can be passed in test environment to simulate the Antifraud flow. Accepted values: paid, review and rejected.
simulate_validatorarrayOptional parameter that can be passed in test environment to simulate additional Validator checks. Accepted values: validation_charge, otp_email, otp_phone and facial. For facial biometrics, the supported combinations are ["facial"], ["otp_phone", "facial"] and ["validation_charge", "otp_phone", "facial"].
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.
acquirer_feebuyer | sellerOptional parameter. Defines who is responsible for paying the acquirer fees. When set to seller, the seller fully absorbs the transaction costs and no fee is passed on to the end customer. When set to buyer, the fees are passed on to the end customer. Defaults to buyer.
Request Body Example
{
  "net_value": 1000,
  "item_id": "#ABCDEFG",
  "soft_descriptor": "Star Wars",
  "customer": {
    "name": "Luke Skywalker",
    "email": "luke@jedimaster.sw",
    "document_number": "00099988877",
    "phone": {
      "country_code": "+55",
      "area_code": "11",
      "number": "999887766"
    }
  },
  "webhook_url": "https://yourapplication.com/order/123456789/webhook",
  "webhook_auth_token": "1234567890"
}

Cart Data​

AttributeTypeDescription
cart_itemsarrayOptional parameter list of cart items. When provided, must contain at least 1 item.
cart_items[][unit_price]int32Item unit price in cents. E.g.: $100.00 → 10000
cart_items[][quantity]int32Item quantity. Integer > 0
cart_items[][product_sku]stringProduct SKU (identifier in your system).
cart_items[][product_name]stringProduct name.
Request Body Example with cart data (cart_items)
{
  "net_value": 12500,
  "item_id": "LINK_ABC123456789",
  "soft_descriptor": "Marlim Store",
  "customer": {
    "name": "Luke Skywalker",
    "email": "luke@jedimaster.sw",
    "document_number": "00099988877",
    "phone": {
      "country_code": "55",
      "area_code": "11",
      "number": "999887766"
    }
  },
  "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-letter) format will be accepted. E.g.: BR, US, UY
Maximum characters: 2
ship_to[address][state]stringShipping destination state, in state code format. E.g.: 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.
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]stringShipping recipient full name.
ship_to[customer][phone]objectShipping recipient phone.
ship_to[customer][phone][country_code]stringShipping recipient country code. Digits only.
Size: 1-4.
ship_to[customer][phone][area_code]stringShipping recipient area code. 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)
{
  "net_value": 1000,
  "item_id": "LINK_ABC123456789",
  "soft_descriptor": "Marlim Store",
  "customer": {
    "name": "Luke Skywalker",
    "email": "luke@jedimaster.sw",
    "document_number": "00099988877",
    "phone": {
      "country_code": "55",
      "area_code": "11",
      "number": "999887766"
    }
  },
  "ship_to": {
    "address": {
      "country": "BR",
      "state": "SP",
      "city": "São Paulo",
      "neighborhood": "República",
      "street": "Rua Aurora",
      "number": "123",
      "complement": "Apt 42",
      "zipcode": "01209001"
    },
    "customer": {
      "name": "Luke Skywalker",
      "phone": {
        "country_code": "55",
        "area_code": "11",
        "number": "999887766"
      }
    }
  }
}

Travel Data​

AttributeTypeDescription
travel_informationobjectOptional parameter travel information.
travel_information[actual_final_destination]stringFinal destination airport in IATA code (3 letters). E.g.: JFK
travel_information[complete_route]stringComplete concatenated route. E.g.: "JFK-LHR:GRU-JFK:LHR-CDG", "JFK-LHR:GRU-JFK" or "GRU-JFK"
travel_information[departure]objectTravel departure date and time.
travel_information[departure][date]stringDate in YYYY-MM-DD format. E.g.: 2025-09-15
travel_information[departure][time]stringTime in HH:mm or HH:mm:ss (24h) format. E.g.: 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]stringPassenger full name.
travel_information[legs]arrayTravel legs/flights.
travel_information[legs][][origination]stringOrigin airport (IATA 3 letters). E.g.: JFK
travel_information[legs][][destination]stringDestination airport (IATA 3 letters). E.g.: CDG
travel_information[legs][][departure]objectLeg departure date and time.
travel_information[legs][][departure][date]stringDate in YYYY-MM-DD format. E.g.: 2025-09-15
travel_information[legs][][departure][time]stringTime in HH:mm or HH:mm:ss format. E.g.: 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]int32Item unit price in cents. E.g.: $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]stringPassenger full name.
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 (two-letter) format. E.g.: BR
travel_information[line_items][][passenger][phone]objectPassenger phone.
travel_information[line_items][][passenger][phone][country_code]stringCountry code. Digits only.
Size: 1-4.
travel_information[line_items][][passenger][phone][area_code]stringArea code. Digits only.
Size: 2-3.
travel_information[line_items][][passenger][phone][number]stringPhone number. Digits only.
Size: 8-9.
Request Body Example with travel data (travel_information)
{
  "net_value": 1000,
  "item_id": "LINK_ABC123456789",
  "soft_descriptor": "Marlim Store",
  "customer": {
    "name": "Luke Skywalker",
    "email": "luke@jedimaster.sw",
    "document_number": "62239006005",
    "phone": {
      "country_code": "55",
      "area_code": "11",
      "number": "999887766"
    }
  },
  "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 user's 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, 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, 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 referring to the sub_seller's app name, which can also be the app URL.
metadata[sub_seller_date_created]dateTimeOptional parameter for the sub_seller's 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
{
  "net_value": 1000,
  "item_id": "LINK_ABC123456789",
  "soft_descriptor": "Marlim Store",
  "customer": {
    "name": "Luke Skywalker",
    "email": "luke@jedimaster.sw",
    "document_number": "00099988877",
    "phone": {
      "country_code": "55",
      "area_code": "11",
      "number": "999887766"
    }
  },
  "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": "Sporting Goods",
    "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
payment_hashstringPayment Link ID.
payment_urlstringURL that should be redirected to the customer to make the payment.
item_idstringPayment ID in your platform.
net_valueint32Amount in cents to be charged from the customer without acquirer fees.
current_statusstringCurrent status of the Payment Link.
date_createddateTimeLink creation date in ISODateTime format.
expires_atdateTimeLink expiration date in ISODateTime format.
Response Example
{
  "payment_hash": "hYZdCLp123vy",
  "payment_url": "https://checkout.marlim.co/hYZdCLp123vy",
  "item_id": "#ABCDEFG",
  "net_value": 1000,
  "current_status": "waiting_payment",
  "date_created": "2025-01-01T10:00:00.000Z",
  "expires_at": "2025-01-02T10:00:00.000Z",
}
Tip

The Payment URL can be customized to a URL from your own application, just contact our Development team to configure the redirect DNS.

This way you won't need to create a new Front-End for the project, since we already have a ready-to-use product.

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.
Example of a Response with Error
{
  "api_reference": "https://docs.api.marlim.co/checkouts/link/create",
  "errors": [
    {
      "type": "customer",
      "message": "The parameter [ customer.email ] is missing."
    }
  ]
}

Status​

When your customer interacts with a link, it may undergo some status changes. Below is a table with the possible values returned in the current_status field:

StatusMeaning
waiting_paymentLink created successfully, waiting for payment.
reviewCustomer started the payment process, but Antifraud is analyzing.
paidLink paid successfully.
expiredThe link may have expired after 24h or the payment may have been refunded.

Payment​

When your customer attempts to pay the link, a transaction is generated in our systems. Like the link, a transaction can undergo some status changes. Below is a table with the possible values returned in the payment_info.current_status field:

StatusMeaning
paidTransaction paid and captured successfully.
reviewTransaction is under manual review by our specialists.
The amount was authorized and reserved on the card, but has not yet been captured.
refusedTransaction refused by the issuing bank.
rejectedTransaction not authorized by Marlim Antifraud.
failedTransaction with failure in the capture process at the Acquirer.
refundedTransaction refunded.
chargebackTransaction suffered chargeback.
Attention

Do not confuse the Payment Link status with the Transaction status.
When your customer makes a payment attempt, two different contexts will be returned via webhook:

  • current_status
    • represents the current Payment Link status.

  • payment_info.current_status
    • represents the last payment attempt (Transaction) status.

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.
1018Invalid installment.

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.

Attention

The parameters simulate_status, simulate_validator and simulate_refused_code are 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 of simulations using the parameter simulate_refused_code and its variables:
Request
curl -X POST "https://api.marlim.co/v3/link_payment" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
  "simulate_refused_code": "1000",
  "net_value": 1000,
  "item_id": "#ABCDEFG",
  "soft_descriptor": "Star Wars",
  "customer": {
    "name": "Luke Skywalker",
    "email": "luke@jedimaster.sw",
    "document_number": "00099988877",
    "phone": {
      "country_code": "+55",
      "area_code": "11",
      "number": "999887766"
    }
  },
  "webhook_url": "https://suaaplicacao.com.br/pedido/123456789/webhook",
  "webhook_auth_token": "1234567890"
}'
Response200
{
  "payment_hash": "hYZdCLp123vy",
  "payment_url": "https://checkout.marlim.co/hYZdCLp123vy",
  "item_id": "#ABCDEFG",
  "net_value": 1000,
  "current_status": "waiting_payment",
  "date_created": "2025-01-01T10:00:00.000Z",
  "expires_at": "2025-01-02T10:00:00.000Z"
}

Webhooks​

The entire status change process for a Payment Link is asynchronous. Therefore, it's important that you pass a webhook_url during the link creation process so your application receives all 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 an example of how the webhook is sent to your system:

Request
curl -X POST "https://yourapplication.com/order/123456789/webhook" \
-H "Content-Type: application/json" \ 
-H "User-Agent: Marlim/1.0.0" \ 
-H "Marlim-Api-Signature: Star98765Wars43210ANewHope1977" \ 
-H "Authorization: Bearer eyJhbGciOiJIU...px3kOoyAfNUwrI" \
-d '{
  "status": "paid",
  "item_id": "#ABCDEFG",
  "net_value": 1000,
  "customer_name": "Luke Skywalker",
  "customer_document_number": "00099988877",
  "payment_hash": "hYZdCLp123vy",
  "payment_info": {
    "current_status": "paid",
    "nsu": "123456789",
    "authorization_code": "019146989",
    "date_created": "2026-08-07T15:40:06.531Z",
    "date_updated": "2026-08-07T15:40:06.531Z",
    "amount": 1100,
    "authorized_amount": 1100,
    "paid_amount": 1100,
    "refunded_amount": 0,
    "installments": "1",
    "transaction_id": "ABCeWbEfTwHtmkX3q123",
    "card_brand": "mastercard",
    "card_holder_name": "Luke Skywalker",
    "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."
  }
}'

Note

You must validate the webhook origin, that is, if it was actually sent by Marlim 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_

Examples​

ATTENTION

The values used in the examples below are for illustration only and should not be used to make requests to Marlim APIs. In development and testing environments, use data closer to a real transaction (card and customer data). If you use fictitious values, the Antifraud may not work as expected.

Request
curl -X POST "https://api.marlim.co/v3/link_payment" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
  "net_value": 100000,
  "item_id": "#123456789",
  "soft_descriptor": "Star Wars",
  "webhook_url": "https://yourapplication.com/order/123456789/webhook",
  "customer": {
    "name": "Luke Skywalker",
    "email": "luke@jedimaster.sw",
    "document_number": "00099988877",
    "phone": {
      "country_code": "55",
      "area_code": "11",
      "number": "999887766"
    }
  }
}'
Response200
{
  "payment_hash": "gt58hyu123",
  "payment_url": "https://checkout.marlim.co/gt58hyu123",
  "item_id": "#123456789",
  "net_value": 100000,
  "current_status": "waiting_payment",
  "date_created": "2026-08-07T15:40:06.532Z",
  "expires_at": "2026-08-08T15:40:06.532Z"
}