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

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

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-08-27T15:32:45.952Z",
    "date_updated": "2025-08-27T15:32:45.952Z",
    "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-08-27T15:32:45.952Z",
  "expires_at": "2025-08-28T15:32:45.952Z"
}

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-08-27T15:32:45.952Z",
  "expires_at": "2025-08-28T15:32:45.952Z",
  "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​

Response Object​

Error Object​

Status​

Link​

Pagamento​

Webhooks​

Exemplos​

Request Body Params

Response Object

Error Object

Status

Link

Pagamento

Webhooks

Exemplos