API

A Marlim fornece criar um Link de Pagamento, tanto via API quanto Dashboard.
Descrevemos nessa sessão como implementar via API.

Importante

Todos os links criados pela Marlim, 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.

POSTv1/link_payment

Request Body Params

Atributo	Tipo	Descrição
net_value	int32	Valor a ser cobrado do cliente sem as taxas de adquirência. 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 17 caracteres, sendo alfanuméricos e espaços.
split	array	*Parâmetro opcional* para o array de objetos com os dados do Split de Pagamento.
split[][seller_id]	string	*Parâmetro opcional* para passar o ID do parceiro que fará parte do Split de Pagamento.
split[][amount]	int32	Valor em centavos que o parceiro deverá receber do pagamento. Deve ser passado em centavos.
webhook_url	string	*Parâmetro opcional* para passar o endpoint do seu sistema que receberá informações a cada atualização do link.
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_number]	string	Número do telefone do cliente.
customer[address][country]	string	Nacionalidade do cliente, 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

Split de Pagamento

A Marlim oferece a opção de Split de Pagamento para que a isaac possa criar um Link com múltiplos recebedores, basta passar um array de objetos com seller_id e amount no parâmetro split no corpo da requisição.

Se for utilizada a opção de Split de Pagamento, será necessário adicionar o recebedor padrão da isaac no parâmetro split.

Caso não seja passado o parâmetro split, o valor cobrado será destinado inteiramente ao recebedor padrão da isaac.

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.
split	array	Array de objetos com os dados do Split de Pagamento
split[][seller_id]	string	ID do parceiro que fará parte do Split de Pagamento.
split[][amount]	int32	Valor em centavos que o parceiro deverá receber do pagamento.

Dica

A URL de Pagamento pode ser customizado para uma URL da própria isaac, 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.

Status

Link

Quando o seu cliente ainda não iniciou nenhum processo ou quando ele tentar executar o pagamento de um link, o status do Link pode sofrer algumas alterações. 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.
`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. Abaixo um exemplo de como é enviado o webhook para o seu sistema:

Request

curl -X POST "https://isaac.com.br/pedido/123456789/callback" \
-H "Content-Type: application/json" \ 
-H "User-Agent: Marlim/1.0.0" \ 
-H "Marlim-Api-Signature: Star98765Wars43210ANewHope1977" \
-d '{
  "status": "paid",
  "item_id": "#ABCDEFG",
  "net_value": 100000,
  "customer_name": "Luke Skywalker",
  "customer_document_number": "00099988877",
  "payment_hash": "hYZdCLp123vy",
  "payment_info": {
    "current_status": "paid",
    "current_status_code": "0000",
    "transaction_id": "ABCeWbEfTwHtmkX3q123",
    "authorization_code": "019146989",
    "nsu": "123456789",
    "date_updated": "2025-01-01T10:00:00.000Z",
    "aproved_amount": 110000,
    "paid_amount": 110000,
    "installments": "1",
    "card_brand": "visa",
    "card_holder_name": "Luke Skywalker",
    "card_first_digits": "555544",
    "card_last_digits": "2222"
  }
}'

Retentativas

Caso o seu sistema deixe de receber um webhook por alguma instabilidade ou até mesmo por estar fora do ar, serão executados dos servidores da Marlim novas tentativas para completar a request até que os nossos servidores recebeba um STATUS 200 do seu sistema. Partindo do primeiro webhook, os próximos são enviados com o seguinte padrão de intervalo de tempo:

Tempo	Tentativas
1 Minuto	3 Tentativas
5 Minutos	3 Tentativas
60 Minutos	25 Tentativas

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ê utlizar 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.isaac.marlim.co/v1/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://isaac.com.br/pedido/123456789/callback",
  "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-03-30T20:20:05.655Z"
}

Request

curl -X POST "https://api.isaac.marlim.co/v1/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://isaac.com.br/pedido/123456789/callback",
  "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-03-30T20:20:05.655Z",
  "split": [
    {
      "seller_id": "se_k4m6Rw5rlQszEY7fiuRe",
      "amount": 30000
    },
    {
      "seller_id": "se_9876543210abcdefghij",
      "amount": 70000
    }
  ]
}

Request

curl -X POST "https://api.isaac.marlim.co/v1/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://isaac.com.br/pedido/123456789/callback",
  "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​

Status​

Link​

Pagamento​

Webhooks​

Retentativas​

Exemplos​

Request Body Params

Response Object

Status

Link

Pagamento

Webhooks

Retentativas

Exemplos