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.

Attribute	Type	Description
net_value	int32	Net value to be received from the transaction. Must be passed in cents.
item_id	string	Payment ID in your platform.
soft_descriptor	string	Description that will appear on your customer's invoice if a transaction occurs. Maximum of 13 characters, alphanumeric and spaces.
customer	object	Customer Object.
customer[name]	string	Customer name.
customer[email]	string	Customer email.
customer[document_number]	string	Customer document number.
customer[phone]	object	Customer phone number object.
customer[phone][country_code]	string	Customer phone country code (DDI), e.g.: +55.
customer[phone][area_code]	string	Customer phone area code (DDD).
customer[phone][number]	string	Customer phone number.
webhook_url	string	Optional parameter to pass your system's endpoint that will receive information with each transaction update.
webhook_auth_token	string	Optional parameter to authenticate notifications sent to webhook_url. If the parameter is not provided, notifications will be sent without authentication.

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

Attribute	Type	Description
cart_items	array	Optional parameter list of cart items. When provided, must contain at least 1 item.
cart_items[][unit_price]	int32	Item unit price in cents. E.g.: $100.00 → 10000
cart_items[][quantity]	int32	Item quantity. Integer > 0
cart_items[][product_sku]	string	Product SKU (identifier in your system).
cart_items[][product_name]	string	Product 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

Attribute	Type	Description
ship_to	object	Optional parameter shipping information (recipient).
ship_to[address]	object	Shipping address object.
ship_to[address][country]	string	Shipping 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]	string	Shipping destination state, in state code format. E.g.: SP, RJ, MG Maximum characters: 2
ship_to[address][city]	string	Shipping destination city. Maximum: 50 characters.
ship_to[address][neighborhood]	string	Shipping destination neighborhood. Maximum: 45 characters.
ship_to[address][street]	string	Shipping destination street. Maximum: 54 characters.
ship_to[address][number]	string	Shipping destination address number. Maximum: 5 characters.
ship_to[address][complement]	string	Optional complement. Maximum: 30 characters.
ship_to[address][zipcode]	string	Shipping destination ZIP code. Accepts hyphen and is normalized to digits. For BR, must contain 8-9 digits.
ship_to[customer]	object	Shipping recipient object.
ship_to[customer][name]	string	Shipping recipient full name.
ship_to[customer][phone]	object	Shipping recipient phone.
ship_to[customer][phone][country_code]	string	Shipping recipient country code. Digits only. Size: 1-4.
ship_to[customer][phone][area_code]	string	Shipping recipient area code. Digits only. Size: 2-3.
ship_to[customer][phone][number]	string	Shipping 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

Attribute	Type	Description
travel_information	object	Optional parameter travel information.
travel_information[actual_final_destination]	string	Final destination airport in IATA code (3 letters). E.g.: JFK
travel_information[complete_route]	string	Complete concatenated route. E.g.: "JFK-LHR:GRU-JFK:LHR-CDG", "JFK-LHR:GRU-JFK" or "GRU-JFK"
travel_information[departure]	object	Travel departure date and time.
travel_information[departure][date]	string	Date in YYYY-MM-DD format. E.g.: 2025-09-15
travel_information[departure][time]	string	Time in HH:mm or HH:mm:ss (24h) format. E.g.: 22:30
travel_information[journey_type]	string	Journey type. Accepted values: oneway, roundtrip, OneWay, RoundTrip, ONEWAY, ROUNDTRIP, Oneway, Roundtrip
travel_information[number_of_passengers]	integer	Total number of passengers.
travel_information[passengers]	array	List of passengers.
travel_information[passengers][][name]	string	Passenger full name.
travel_information[legs]	array	Travel legs/flights.
travel_information[legs][][origination]	string	Origin airport (IATA 3 letters). E.g.: JFK
travel_information[legs][][destination]	string	Destination airport (IATA 3 letters). E.g.: CDG
travel_information[legs][][departure]	object	Leg departure date and time.
travel_information[legs][][departure][date]	string	Date in YYYY-MM-DD format. E.g.: 2025-09-15
travel_information[legs][][departure][time]	string	Time in HH:mm or HH:mm:ss format. E.g.: 22:30:15
travel_information[legs][][carrier_code]	string	Airline code (IATA 2 characters, e.g. AA, LA, G3)
travel_information[line_items]	array	Travel items (tickets/products).
travel_information[line_items][][unit_price]	int32	Item unit price in cents. E.g.: $100.00 → 10000
travel_information[line_items][][quantity]	int32	Item quantity. Integer > 0
travel_information[line_items][][product_sku]	string	Product SKU.
travel_information[line_items][][product_name]	string	Product name or description.
travel_information[line_items][][passenger]	object	Passenger data linked to the item.
travel_information[line_items][][passenger][type]	string	Passenger type. Accepted values: ADT, CNN, INF, YTH, STU, SCR, MIL
travel_information[line_items][][passenger][status]	string	Internal passenger/booking status (e.g.: standard, gold, platinum, according to your domain).
travel_information[line_items][][passenger][name]	string	Passenger full name.
travel_information[line_items][][passenger][email]	string	Passenger email.
travel_information[line_items][][passenger][document_number]	string	Document (CPF/Passport). Digits only when applicable.
travel_information[line_items][][passenger][country]	string	Country in ISO 3166-1 alpha-2 (two-letter) format. E.g.: BR
travel_information[line_items][][passenger][phone]	object	Passenger phone.
travel_information[line_items][][passenger][phone][country_code]	string	Country code. Digits only. Size: 1-4.
travel_information[line_items][][passenger][phone][area_code]	string	Area code. Digits only. Size: 2-3.
travel_information[line_items][][passenger][phone][number]	string	Phone 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

Attribute	Type	Description
metadata	object	Optional parameter for additional information.
metadata[customer_registration_date]	dateTime	Optional parameter for the user's registration date on your platform in ISODateTime format.
metadata[customer_first_transaction_date]	dateTime	Optional 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]	dateTime	Optional 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]	int32	Optional parameter for the number of completed (paid) proposals by the customer on your platform, regardless of whether it was processed by Marlim.
metadata[sub_seller_social_name]	string	Optional parameter for the sub_seller's trade name.
metadata[sub_seller_document]	string	Optional parameter for the sub_seller's Tax-ID.
metadata[sub_seller_cnae]	string	Optional parameter for the sub_seller's CNAE.
metadata[sub_seller_segment]	string	Optional parameter for the sub_seller's business segment.
metadata[sub_seller_app_name]	string	Optional parameter referring to the sub_seller's app name, which can also be the app URL.
metadata[sub_seller_date_created]	dateTime	Optional parameter for the sub_seller's creation date in the seller in ISODateTime format.
metadata[sub_seller_country_operation]	string	Optional parameter for the sub_seller's country of operation.
metadata[sub_seller_state_operation]	string	Optional 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

Property	Type	Description
payment_hash	string	Payment Link ID.
payment_url	string	URL that should be redirected to the customer to make the payment.
item_id	string	Payment ID in your platform.
net_value	int32	Amount in cents to be charged from the customer without acquirer fees.
current_status	string	Current status of the Payment Link.
date_created	dateTime	Link creation date in ISODateTime format.
expires_at	dateTime	Link expiration date in ISODateTime format.

Response Example

{
  "payment_hash": "hYZdCLp123vy",
  "payment_url": "https://link.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

Attribute	Type	Description
api_reference	string	URL to the documentation.
errors	array	Array with all errors found when processing the request.
errors[][type]	string	Type of error that occurred.
errors[][message]	string	Detailed message of the error that occurred.

Example of a Response with Error

{
  "api_reference": "https://docs.api.marlim.co/link/create",
  "errors": [
    {
      "type": "customer",
      "message": "The parameter [ customer.email ] is missing."
    }
  ]
}

Status

Link

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:

Status	Meaning
waiting_payment	Link created successfully, waiting for payment.
manual_review	Customer started the payment process, but Antifraud is analyzing.
paid	Link paid successfully.
expired	The 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:

Status	Meaning
paid	Transaction paid and captured successfully.
review	Transaction is under manual review by our specialists. The amount was authorized and reserved on the card, but has not yet been captured.
refused	Transaction refused by the issuing bank.
rejected	Transaction not authorized by Marlim Antifraud.
failed	Transaction with failure in the capture process at the Acquirer.
refunded	Transaction refunded.
chargeback	Transaction 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.

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-01-15T17:36:12.411Z",
    "date_updated": "2026-01-15T17:36:12.411Z",
    "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.

Link Created

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",
  "customer[email]": "luke@jedimaster.sw",
  "customer[document_number]": "00099988877",
  "customer[phone_number]": "+18007770133",
  "customer[address][country]": "br"
}'

Response200

{
  "payment_hash": "gt58hyu123",
  "payment_url": "https://link.marlim.co/gt58hyu123",
  "item_id": "#123456789",
  "net_value": 100000,
  "current_status": "waiting_payment",
  "date_created": "2026-01-15T17:36:12.411Z",
  "expires_at": "2026-01-16T17:36:12.411Z"
}

Link with Split Payment

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",
  "split": [
    {
      "seller_id": "se_k4m6Rw5rlQszEY7fiuRe",
      "amount": 30000
    },
    {
      "seller_id": "se_9876543210abcdefghij",
      "amount": 70000
    }
  ],
  "webhook_url": "https://yourapplication.com/order/123456789/webhook",
  "customer[name]": "Luke Skywalker",
  "customer[email]": "luke@jedimaster.sw",
  "customer[document_number]": "00099988877",
  "customer[phone_number]": "+18007770133",
  "customer[address][country]": "br"
}'

Response200

{
  "payment_hash": "gt58hyu123",
  "payment_url": "https://link.marlim.co/gt58hyu123",
  "item_id": "#123456789",
  "net_value": 100000,
  "current_status": "waiting_payment",
  "date_created": "2026-01-15T17:36:12.411Z",
  "expires_at": "2026-01-16T17:36:12.411Z",
  "split": [
    {
      "seller_id": "se_k4m6Rw5rlQszEY7fiuRe",
      "amount": 30000
    },
    {
      "seller_id": "se_9876543210abcdefghij",
      "amount": 70000
    }
  ]
}

Missing Data

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",
  "customer[document_number]": "00099988877",
  "customer[phone_number]": "+18007770133",
  "customer[address][country]": "br"
}'

Response401

{
  "errors": {
    "type": "parameter",
    "message": "The parameter [ customer.email ] is missing."
  }
}