Criar Link de Pagamento

Essa rota deve ser usada para criar um Link de Pagamento.

Importante

Todos os nossos links possuem uma validade de 24 horas por padrão. Após esse período, o link é automaticamente expirado. Esse valor pode ser alterado de acordo com as suas necessidades, basta falar com o nosso time de Desenvolvimento.

POSTv3/link_payment

Request Body Params

Atenção

Todos os campos do tipo string devem ser informados com caracteres alfanuméricos sem acentuação ou caracteres especiais.

Atributo	Tipo	Descrição
net_value	int32	Valor líquido a ser recebido pela transação. Deve ser passado em centavos.
item_id	string	ID do pagamento na sua plataforma.
soft_descriptor	string	Descrição que aparecerá na fatura do seu cliente, caso haja uma transação. Máximo de 13 caracteres, sendo alfanuméricos e espaços.
customer	object	Objeto Cliente.
customer[name]	string	Nome do cliente.
customer[email]	string	E-mail do cliente.
customer[document_number]	string	Número do documento do cliente.
customer[phone]	object	Objeto número do telefone do cliente.
customer[phone][country_code]	string	Código do país do telefone do cliente (DDI), Ex: +55.
customer[phone][area_code]	string	Código do estado do telefone do cliente (DDD).
customer[phone][number]	string	Número do telefone do cliente.
webhook_url	string	*Parâmetro opcional* para passar o endpoint do seu sistema que receberá informações a cada atualização da transação.
webhook_auth_token	string	Parâmetro opcional para autenticar as notificações enviadas para o `webhook_url`. Caso o parâmetro não seja informado, as notificações serão enviadas sem autenticação.

Exemplo de Request Body
{
  "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"
}

Dados de Carrinho

Atributo	Tipo	Descrição
cart_itens	array	Parâmetro opcional lista de itens do carrinho. Quando informado, deve conter ao menos 1 item.
cart_itens[][unit_price]	int32	Preço unitário do item em centavos. Ex.: R$ 100,00 → `10000`
cart_itens[][quantity]	int32	Quantidade do item. Inteiro > 0
cart_itens[][product_sku]	string	SKU do produto (identificador no seu sistema).
cart_itens[][product_name]	string	Nome do produto.

Exemplo de Request Body com dados de carrinho(cart_itens)
{
  "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_itens": [
    {
      "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"
    }
  ]
}

Dados de Entrega

Atributo	Tipo	Descrição
ship_to	object	Parâmetro opcional informações de entrega (destinatário).
ship_to[address]	object	Objeto endereço de entrega.
ship_to[address][country]	string	País do destino de entrega, no formato sigla do país. Só serão aceitos o formato ISO 3166-1 alfa-2 (duas-letras) Ex: `BR`, `US`, `UY` Máximo em caracteres: 2
ship_to[address][state]	string	UF do destino de entrega, no formato sigla do estado. Ex: `SP`, `RJ`, `MG` Máximo em caracteres: 2
ship_to[address][city]	string	Cidade do destino de entrega. Máximo: 50 caracteres.
ship_to[address][neighborhood]	string	Bairro do destino de entrega. Máximo: 45 caracteres.
ship_to[address][street]	string	Rua/Logradouro do destino de entrega. Máximo: 54 caracteres.
ship_to[address][number]	string	Número do endereço do destino de entrega. Máximo: 5 caracteres.
ship_to[address][complement]	string	Opcional complemento. Máximo: 30 caracteres.
ship_to[address][zipcode]	string	CEP do destino de entrega. Aceita hífen e é normalizado para dígitos. Para `BR`, deve conter 8–9 dígitos.
ship_to[customer]	object	Objeto destinatário da entrega.
ship_to[customer][name]	string	Nome completo do destinatário da entrega.
ship_to[customer][phone]	object	Telefone do destinatário da entrega.
ship_to[customer][phone][country_code]	string	DDI do destinatário da entrega. Somente dígitos. Tamanho: 1–4.
ship_to[customer][phone][area_code]	string	DDD do destinatário da entrega. Somente dígitos. Tamanho: 2–3.
ship_to[customer][phone][number]	string	Número do telefone do destinatário da entrega. Somente dígitos. Tamanho: 8–9.

Exemplo de Request Body com dados de entrega (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": "Apto 42",
      "zipcode": "01209001"
    },
    "customer": {
      "name": "Luke Skywalker",
      "phone": {
        "country_code": "55",
        "area_code": "11",
        "number": "999887766"
      }
    }
  }
}

Dados de Viagem

Atributo	Tipo	Descrição
travel_information	object	Parâmetro opcional informações de viagem.
travel_information[actual_final_destination]	string	Aeroporto de destino final em código IATA (3 letras). Ex.: `JFK`
travel_information[complete_route]	string	Rota completa concatenada. Ex.: `"JFK-LHR:GRU-JFK:LHR-CDG"`, `"JFK-LHR:GRU-JFK"` ou `"GRU-JFK"`
travel_information[departure]	object	Data e hora de partida da viagem.
travel_information[departure][date]	string	Data no formato YYYY-MM-DD. Ex.: `2025-09-15`
travel_information[departure][time]	string	Hora no formato HH:mmou HH:mm:ss (24h). Ex.: `22:30`
travel_information[journey_type]	string	Tipo da jornada. Valores aceitos: `oneway`, `roundtrip`, `OneWay`, `RoundTrip`, `ONEWAY`, `ROUNDTRIP`, `Oneway`, `Roundtrip`
travel_information[number_of_passengers]	integer	Quantidade total de passageiros.
travel_information[passengers]	array	Lista de passageiros.
travel_information[passengers][][name]	string	Nome completo do passageiro.
travel_information[legs]	array	Trechos/voos da viagem.
travel_information[legs][][origination]	string	Aeroporto de origem (IATA 3 letras). Ex.: `JFK`
travel_information[legs][][destination]	string	Aeroporto de destino (IATA 3 letras). Ex.: `CDG`
travel_information[legs][][departure]	object	Data e hora de partida do trecho.
travel_information[legs][][departure][date]	string	Data no formato YYYY-MM-DD. Ex.: `2025-09-15`
travel_information[legs][][departure][time]	string	Hora no formato HH:mm ou HH:mm:ss. Ex.: `22:30:15`
travel_information[legs][][carrier_code]	string	Código da companhia aérea (IATA 2 caracteres, p.ex. `AA`, `LA`, `G3`)
travel_information[line_itens]	array	Itens da viagem (bilhetes/produtos).
travel_information[line_itens][][unit_price]	int32	Preço unitário do item em centavos. Ex.: R$ 100,00 → `10000`
travel_information[line_itens][][quantity]	int32	Quantidade do item. Inteiro > 0
travel_information[line_itens][][product_sku]	string	SKU do produto.
travel_information[line_itens][][product_name]	string	Nome ou descrição do produto.
travel_information[line_itens][][passenger]	object	Dados do passageiro vinculado ao item.
travel_information[line_itens][][passenger][type]	string	Tipo de passageiro. Valores aceitos: `ADT`, `CNN`, `INF`, `YTH`, `STU`, `SCR`, `MIL`
travel_information[line_itens][][passenger][status]	string	Status interno do passageiro/reserva (ex.: `standard`, `gold`, `platinum`, conforme seu domínio).
travel_information[line_itens][][passenger][name]	string	Nome completo do passageiro.
travel_information[line_itens][][passenger][email]	string	Email do passageiro.
travel_information[line_itens][][passenger][document_number]	string	Documento (CPF/Passaporte). Somente dígitos quando aplicável.
travel_information[line_itens][][passenger][country]	string	País no formato ISO 3166-1 alfa-2 (duas letras). Ex.: `BR`
travel_information[line_itens][][passenger][phone]	object	Telefone do passageiro.
travel_information[line_itens][][passenger][phone][country_code]	string	DDI. Somente dígitos. Tamanho: 1–4.
travel_information[line_itens][][passenger][phone][area_code]	string	DDD. Somente dígitos. Tamanho: 2–3.
travel_information[line_itens][][passenger][phone][number]	string	Número do telefone. Somente dígitos. Tamanho: 8–9.

Exemplo de Request Body com dados de viagem (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_itens": [
      {
        "unit_price": 1500,
        "quantity": 1,
        "product_sku": "TICKET-GRU-JFK-001",
        "product_name": "Passagem Aérea - 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": "Passagem Aérea - 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

Atributo	Tipo	Descrição
metadata	object	Parâmetro opcional para informações adicionais.
metadata[customer_registration_date]	dateTime	Parâmetro opcional da data de abertura do cadastro do usuário na sua plataforma no formato ISODateTime.
metadata[customer_first_transaction_date]	dateTime	Parâmetro opcional da data da primeira operação concretizada (paga) na sua plataforma, independente de ter sido processada pela Marlim ou não, no formato ISODateTime.
metadata[customer_last_transaction_date]	dateTime	Parâmetro opcional da data da última operação concretizada (paga) na sua plataforma, independente de ter sido processada pela Marlim ou não, no formato ISODateTime.
metadata[customer_paid_proposals]	int32	Parâmetro opcional da quantidade de propostas concretizadas (pagas) pelo cliente na sua plataforma, independente de ter sido processada pela Marlim ou não.
metadata[sub_seller_social_name]	string	Parâmetro opcional do nome fantasia do sub_seller.
metadata[sub_seller_document]	string	Parâmetro opcional do Tax-ID do sub_seller.
metadata[sub_seller_cnae]	string	Parâmetro opcional do CNAE do sub_seller.
metadata[sub_seller_segment]	string	Parâmetro opcional do segmento de negócio do sub_seller.
metadata[sub_seller_app_name]	string	Parâmetro opcional referente ao nome do app do sub_seller, podendo também ser informada a URL do app.
metadata[sub_seller_date_created]	dateTime	Parâmetro opcional da data de criação do sub_seller no seller no formato ISODateTime.
metadata[sub_seller_country_operation]	string	Parâmetro opcional do país de operação do sub_seller.
metadata[sub_seller_state_operation]	string	Parâmetro opcional da UF fiscal de operação do sub_seller somente quando o país de operação for Brasil.

Exemplo de Request Body com 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": "Artigos Esportivos",
    "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

Propriedade	Tipo	Descrição
payment_hash	string	ID do Link de Pagamento.
payment_url	string	URL que deve ser redirecionada ao cliente para efetuar o pagamento.
item_id	string	ID do pagamento na sua plataforma.
net_value	int32	Valor em centavos a ser cobrado do cliente sem as taxas de adquirência.
current_status	string	Status atual em que se encontra o Link de Pagamento.
date_created	dateTime	Data de criação do link no formato ISODateTime.
expires_at	dateTime	Data de expiração do link no formato ISODateTime.

Exemplo de Response
{
  "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",
}

Dica

A URL de Pagamento pode ser customizado para uma URL da sua própria aplicação, basta falar com o nosso time de Desolvimento para configurarmos o DNS de redirecionamento.

Assim não será necessário criar um novo Front-End para o projeto, uma vez que já temos um produto pronto para ser usado.

Error Object

Atributo	Tipo	Descrição
api_reference	string	Url para a documentação.
errors	array	Array com todos os erros encontrados ao processar a requisição.
errors[][type]	string	Tipo de erro ocorrido.
errors[][message]	string	Mensagem detalhada do erro ocorrido.

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

Status

Link

Quando o seu cliente interage com um link, ele pode sofrer algumas alterações de status. Abaixo, uma tabela com os valores possíveis que são retornados no campo current_status:

Status	Significado
`waiting_payment`	Link criado com sucesso, aguardando o pagamento.
`manual_review`	Cliente iniciou o processo de pagamento, porém o Antifraude está analisando.
`paid`	Link pago com sucesso.
`expired`	O link pode ter vencido após 24h ou o pagamento pode ter sofrido um estorno.

Pagamento

Quando o seu cliente tenta executar o pagamento do link, é gerado em nossos sistemas uma transação. Assim como o link, um transação pode sofrer algumas alterações de status. Abaixo, uma tabela com os valores possíveis que são retornados no campo payment_info.current_status:

Status	Significado
`paid`	Transação paga e capturada com sucesso.
`review`	Transação está em processo de revisão manual pelos nossos especialistas. O valor foi autorizado e reservado no cartão, mas ainda não foi capturado.
`refused`	Transação recusada pelo banco emissor.
`rejected`	Transação não autorizada pelo Antifraude Marlim.
`failed`	Transação com falha no processo de captura na Adquirente.
`refunded`	Transação estornada.
`chargeback`	Transação sofreu chargeback.

Atenção

Não confundir o status do Link de Pagamento com o status da Transação.
Quando o seu cliente fizer uma tentativa de pagamento, será retornado via webhook dois contextos diferentes:

current_status
- representa o status atual do Link de Pagamento.
payment_info.current_status
- representa o status da última tentativa de pagamento (Transação).

Webhooks

Todo o processo de mudança de status de um Link de Pagamento é assíncrono. Por isso, é importante que você passe um webhook_url durante o processo de criação do link para que sua aplicação receba todas as mudanças.

Se for passado algum valor no parâmetro webhook_auth_token a Marlim vai enviar o token para a sua aplicação usando o padrão Authorization: Bearer no Header da requisição:

Authorization: Bearer {webhook_auth_token}

Abaixo um exemplo de como é enviado o webhook para o seu sistema:

Request

curl -X POST "https://suaaplicacao.com.br/pedido/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": "2025-11-04T18:29:37.462Z",
    "date_updated": "2025-11-04T18:29:37.462Z",
    "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."
  }
}'

Nota

Você deve validar a origem do webhook, isto é, se ele foi realmente enviado pelos servidores da Marlim.
Para isso, enviamos no HEADER do POST dois valores:

• User-Agent: sempre com o valor Marlim/1.0.0
• Marlim-Api-Signature: o final da sua api_key removendo os valores mak_test_ e mak_live_

Exemplos

ATENÇÃO

Os valores utilizados nos exemplos abaixo são apenas para ilustração e não devem ser usados para fazer requests nas APIs da Marlim. Em ambiente de desenvolvimento e testes, utilize dados mais próximos de uma transação real (dados de cartão e cliente). Se você utilizar valores fictícios o Antifraude pode não funcionar de forma esperada.

Link Criado
Link com Split de Pagamento
Faltando Dados

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://suaaplicacao.com.br/pedido/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": "2025-11-04T18:29:37.462Z",
  "expires_at": "2025-11-05T18:29:37.462Z"
}

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://suaaplicacao.com.br/pedido/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": "2025-11-04T18:29:37.462Z",
  "expires_at": "2025-11-05T18:29:37.462Z",
  "split": [
    {
      "seller_id": "se_k4m6Rw5rlQszEY7fiuRe",
      "amount": 30000
    },
    {
      "seller_id": "se_9876543210abcdefghij",
      "amount": 70000
    }
  ]
}

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://suaaplicacao.com.br/pedido/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."
  }
}

Request Body Params​

Dados de Carrinho​

Dados de Entrega​

Dados de Viagem​

Metadata​

Response Object​

Error Object​

Status​

Link​

Pagamento​

Webhooks​

Exemplos​

Request Body Params

Dados de Carrinho

Dados de Entrega

Dados de Viagem

Metadata

Response Object

Error Object

Status

Link

Pagamento

Webhooks

Exemplos