Pular para o conteúdo principal

Criar Link de Pagamento

Disponível apenas em Sandbox

Este endpoint está disponível somente no ambiente Sandbox. Não há suporte para Pix Agendado em produção no momento.

O Pix Agendado não está disponível para todas as contas e depende de habilitação prévia pela Marlim. Para verificar a elegibilidade da sua conta, entre em contato com o nosso time comercial.

Use esta rota para criar o link onde o cliente revisa e aprova os pagamentos agendados. A resposta traz a payment_url para onde o cliente deve ser enviado.

POSTv3/scheduled_pix/links
Atenção

Faça esta chamada sempre a partir do seu servidor.

Request Body Params​

AtributoTipoDescrição
item_idstringParâmetro opcional. ID do link na sua plataforma.
descriptionstringParâmetro opcional. Texto exibido ao cliente na tela de aprovação e no extrato.
amountint32Valor de cada pagamento do agendamento. Deve ser passado em centavos. O mesmo valor vale para todas as datas.
scheduleobjectObjeto Agendamento, com o tipo e as datas dos pagamentos.
schedule[type]stringTipo do agendamento.

Valores aceitos: single (pagamento único em data futura), daily, weekly, monthly e custom (datas personalizadas).
schedule[date]dateData do pagamento no formato YYYY-MM-DD. Obrigatório quando schedule[type] é single. Até 365 dias à frente.
schedule[start_date]dateData do primeiro pagamento no formato YYYY-MM-DD. Obrigatório quando schedule[type] é daily, weekly ou monthly.
schedule[quantity]int32Quantidade de pagamentos. Obrigatório quando schedule[type] é daily, weekly ou monthly. De 2 a 60 no diário e no semanal, e de 2 a 24 no mensal.
schedule[day_of_week]stringDia da semana dos pagamentos. Obrigatório quando schedule[type] é weekly.

Valores aceitos: monday, tuesday, wednesday, thursday, friday, saturday e sunday.
schedule[day_of_month]int32Dia do mês dos pagamentos, de 1 a 31. Obrigatório quando schedule[type] é monthly.
schedule[dates]arrayLista de datas no formato YYYY-MM-DD, de 2 a 60 datas sem repetição. Obrigatório quando schedule[type] é custom.
schedule[additional_information]stringParâmetro opcional. Texto exibido ao cliente explicando o agendamento personalizado. Usado somente quando schedule[type] é custom.
methodstringForma de recebimento.

Valores aceitos: default_account (conta de recebimento cadastrada na sua conta Marlim), bank_account (conta informada em creditor_account) e pix_key (chave informada em pix_key).
creditor_accountobjectObjeto Conta recebedora. Obrigatório quando method é bank_account.
creditor_account[document_number]stringCNPJ ou CPF do titular da conta recebedora, somente números.
creditor_account[ispb]stringISPB da instituição recebedora (8 dígitos).
creditor_account[agency]stringNúmero da agência, sem dígito.
creditor_account[account_number]stringNúmero da conta, com o dígito verificador.
creditor_account[type]stringTipo da conta.

Valores aceitos: checking (conta corrente), savings (poupança) e payment (conta de pagamento).
pix_keystringChave Pix do recebedor. Obrigatório quando method é pix_key.
expires_atdateTimeParâmetro opcional. Data de expiração do link no formato ISODateTime. Após esse momento o cliente não consegue mais aprovar. Deve ser anterior à data do primeiro pagamento.
customerobjectObjeto Pagador, titular da conta que será debitada.
customer[name]stringParâmetro opcional. Nome do pagador.
customer[document_number]stringCPF ou CNPJ do pagador, somente números.
customer[ip_address]stringParâmetro opcional do endereço IP público do cliente ao acessar a sua página de checkout no formato IPv4 ou IPv6. Recomendado, pois é usado na análise de risco.
business_entityobjectParâmetro opcional. Use quando o pagador for pessoa jurídica.
business_entity[document_number]stringCNPJ da empresa pagadora, somente números.
participant_idstringParâmetro opcional. Banco do pagador, se já conhecido. Pula a etapa de escolha do banco na jornada.
debtor_accountobjectParâmetro opcional. Objeto Conta do pagador, se já conhecida.
debtor_account[ispb]stringISPB do banco do pagador (8 dígitos).
debtor_account[agency]stringNúmero da agência, sem dígito.
debtor_account[account_number]stringNúmero da conta, com o dígito verificador.
redirect_urlstringParâmetro opcional. URL para onde o cliente volta após concluir a aprovação. Recomendado quando a jornada começa no seu site ou app. Se omitido, a jornada termina na tela de conclusão da Marlim.
redirect_on_error_urlstringParâmetro opcional. URL para onde o cliente volta em caso de erro na jornada. Se omitido, é usada a redirect_url.
webhook_urlstringParâmetro opcional para passar o endpoint do seu sistema que receberá as mudanças de status do link e dos pagamentos. Veja Webhooks.
webhook_auth_tokenstringParâ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.
metadataobjectParâmetro opcional. Objeto livre para guardar dados da sua aplicação. É devolvido nas consultas.
Importante

Todas as datas do agendamento devem ser a partir do dia seguinte à criação do link e no máximo 2 anos à frente. Todos os valores do Pix Agendado são em centavos.

Response Object​

PropriedadeTipoDescrição
link_idstringID Marlim do link de pagamento. Guarde este ID: é com ele que você consulta e cancela o link e lista os pagamentos.
item_idstringID do link na sua plataforma.
current_statusstringStatus atual do link. No momento da criação, sempre created. Veja Status do Link.
payment_urlstringURL para onde o cliente deve ser enviado para aprovar os pagamentos.
date_createddateTimeData de criação do link no formato ISODateTime.
expires_atdateTimeData de expiração do link no formato ISODateTime.

Error Object​

AtributoTipoDescrição
api_referencestringURL para a documentação. Retornado nos erros de parâmetro.
errorsarrayArray com todos os erros encontrados ao processar a requisição.
errors[][type]stringTipo de erro ocorrido.
errors[][message]stringMensagem detalhada do erro ocorrido.

Redirecione o cliente para a payment_url pelo servidor ou exiba um botão na sua página. Botões com âncora <a> costumam converter melhor do que redirecionamentos automáticos.

// Pelo servidor
redirect(link.payment_url)

// Pela interface
<a href={link.payment_url}>Pagar com Pix Agendado</a>

A partir daqui, acompanhe o resultado pelos webhooks ou pela consulta do link.

Recusa do Cliente​

A criação do link é síncrona e sempre responde com current_status igual a created. Os erros que acontecem durante a aprovação, como o cliente recusar o agendamento no banco, não são retornados nesta chamada: eles chegam depois pelo webhook scheduled_pix_link_status_changed, com o current_status igual a error e o código da recusa em error.code.

CódigoSignificado
rejected_by_customerO cliente recusou o agendamento no banco.
authorization_time_expiredO cliente não aprovou dentro do prazo.
journey_time_expiredO cliente não finalizou a jornada a tempo.

Para esses códigos, pergunte ao cliente se ele quer tentar de novo e crie um novo link. A lista completa está em Rejeições da Aprovação.

🕹  Criar um link e receber a recusa do cliente com rejected_by_customer.
Request
curl -X POST "https://sandbox.api.marlim.co/v3/scheduled_pix/links" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
"item_id": "RESERVA_ENDOR_0042",
"description": "Reserva Endor Lodge",
"amount": 60000,
"schedule": {
"type": "custom",
"dates": [
"2026-12-01",
"2027-01-15",
"2027-02-20"
]
},
"method": "default_account",
"customer": {
"name": "Leia Organa",
"document_number": "00011122233"
},
"redirect_url": "https://suaaplicacao.com.br/obrigado",
"webhook_url": "https://suaaplicacao.com.br/webhook"
}'
Response200
{
"link_id": "vBn2Qw8ErT5yUi1OpL6k",
"item_id": "RESERVA_ENDOR_0042",
"current_status": "created",
"payment_url": "https://checkout.marlim.co/scheduled-pix/vBn2Qw8ErT5yUi1OpL6k",
"date_created": "2026-11-16T15:30:00.000Z",
"expires_at": "2026-11-17T15:30:00.000Z"
}

Recusa do Banco​

Depois de aprovado, cada pagamento é liquidado na sua data e ainda pode ser recusado pelo banco do cliente ou pelo SPI. Nesse caso, o webhook scheduled_pix_payment_status_changed chega com o current_status igual a rejected e o código da recusa em error.code. Os demais pagamentos do agendamento continuam valendo. Os códigos mais comuns estão abaixo.

CódigoSignificado
insufficient_balanceConta do cliente sem saldo suficiente, mesmo após a nova tentativa do banco no dia.
amount_above_limitValor acima do limite de Pix definido pelo cliente no banco.
refused_by_bankRecusado pelo banco do cliente. O motivo vem em error.detail.
account_holder_mismatchA conta não pertence mais ao CPF ou CNPJ do pagador.

A lista completa e a ação recomendada para cada código estão em Rejeições de Pagamento.

🕹  Criar um link e receber a recusa de um pagamento com insufficient_balance.
Request
curl -X POST "https://sandbox.api.marlim.co/v3/scheduled_pix/links" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
"item_id": "CURSO_PILOTAGEM_00321",
"description": "Curso de Pilotagem 3x",
"amount": 25000,
"schedule": {
"type": "monthly",
"start_date": "2026-12-10",
"quantity": 3,
"day_of_month": 10
},
"method": "default_account",
"customer": {
"name": "Luke Skywalker",
"document_number": "00099988877"
},
"redirect_url": "https://suaaplicacao.com.br/obrigado",
"webhook_url": "https://suaaplicacao.com.br/webhook",
"metadata": {
"turma": "2027A"
}
}'
Response200
{
"link_id": "sKd4Wp7RtY2nQm9XbC3v",
"item_id": "CURSO_PILOTAGEM_00321",
"current_status": "created",
"payment_url": "https://checkout.marlim.co/scheduled-pix/sKd4Wp7RtY2nQm9XbC3v",
"date_created": "2026-11-16T14:19:18.051Z",
"expires_at": "2026-12-05T23:59:59.000Z"
}

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.

Sucesso​

Request
curl -X POST "https://sandbox.api.marlim.co/v3/scheduled_pix/links" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
"item_id": "CURSO_PILOTAGEM_00321",
"description": "Curso de Pilotagem 3x",
"amount": 25000,
"schedule": {
"type": "monthly",
"start_date": "2026-12-10",
"quantity": 3,
"day_of_month": 10
},
"method": "default_account",
"expires_at": "2026-12-05T23:59:59.000Z",
"customer": {
"name": "Luke Skywalker",
"document_number": "00099988877",
"ip_address": "200.150.10.20"
},
"redirect_url": "https://suaaplicacao.com.br/obrigado",
"webhook_url": "https://suaaplicacao.com.br/webhook",
"webhook_auth_token": "1234567890",
"metadata": {
"turma": "2027A"
}
}'
Response200
{
"link_id": "sKd4Wp7RtY2nQm9XbC3v",
"item_id": "CURSO_PILOTAGEM_00321",
"current_status": "created",
"payment_url": "https://checkout.marlim.co/scheduled-pix/sKd4Wp7RtY2nQm9XbC3v",
"date_created": "2026-11-16T14:19:18.051Z",
"expires_at": "2026-12-05T23:59:59.000Z"
}

Erros​

Request
curl -X POST "https://sandbox.api.marlim.co/v3/scheduled_pix/links" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
"amount": 25000,
"schedule": {
"type": "yearly",
"start_date": "2026-12-10",
"quantity": 3
},
"method": "default_account",
"redirect_url": "https://suaaplicacao.com.br/obrigado"
}'
Response400
{
"api_reference": "https://docs.api.marlim.co/scheduled-pix/links/create",
"errors": [
{
"type": "schedule",
"message": "The parameter [ schedule.type ] must be one of: single, daily, weekly, monthly, custom."
},
{
"type": "customer",
"message": "The parameter [ customer.document_number ] is missing."
}
]
}