Criar Link de Pagamento
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.
Faça esta chamada sempre a partir do seu servidor.
Request Body Params
| Atributo | Tipo | Descrição |
|---|---|---|
| item_id | string | Parâmetro opcional. ID do link na sua plataforma. |
| description | string | Parâmetro opcional. Texto exibido ao cliente na tela de aprovação e no extrato. |
| amount | int32 | Valor de cada pagamento do agendamento. Deve ser passado em centavos. O mesmo valor vale para todas as datas. |
| schedule | object | Objeto Agendamento, com o tipo e as datas dos pagamentos. |
| schedule[type] | string | Tipo do agendamento. Valores aceitos: single (pagamento único em data futura), daily, weekly, monthly e custom (datas personalizadas). |
| schedule[date] | date | Data do pagamento no formato YYYY-MM-DD. Obrigatório quando schedule[type] é single. Até 365 dias à frente. |
| schedule[start_date] | date | Data do primeiro pagamento no formato YYYY-MM-DD. Obrigatório quando schedule[type] é daily, weekly ou monthly. |
| schedule[quantity] | int32 | Quantidade 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] | string | Dia da semana dos pagamentos. Obrigatório quando schedule[type] é weekly.Valores aceitos: monday, tuesday, wednesday, thursday, friday, saturday e sunday. |
| schedule[day_of_month] | int32 | Dia do mês dos pagamentos, de 1 a 31. Obrigatório quando schedule[type] é monthly. |
| schedule[dates] | array | Lista de datas no formato YYYY-MM-DD, de 2 a 60 datas sem repetição. Obrigatório quando schedule[type] é custom. |
| schedule[additional_information] | string | Parâmetro opcional. Texto exibido ao cliente explicando o agendamento personalizado. Usado somente quando schedule[type] é custom. |
| method | string | Forma 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_account | object | Objeto Conta recebedora. Obrigatório quando method é bank_account. |
| creditor_account[document_number] | string | CNPJ ou CPF do titular da conta recebedora, somente números. |
| creditor_account[ispb] | string | ISPB da instituição recebedora (8 dígitos). |
| creditor_account[agency] | string | Número da agência, sem dígito. |
| creditor_account[account_number] | string | Número da conta, com o dígito verificador. |
| creditor_account[type] | string | Tipo da conta. Valores aceitos: checking (conta corrente), savings (poupança) e payment (conta de pagamento). |
| pix_key | string | Chave Pix do recebedor. Obrigatório quando method é pix_key. |
| expires_at | dateTime | Parâ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. |
| customer | object | Objeto Pagador, titular da conta que será debitada. |
| customer[name] | string | Parâmetro opcional. Nome do pagador. |
| customer[document_number] | string | CPF ou CNPJ do pagador, somente números. |
| customer[ip_address] | string | Parâ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_entity | object | Parâmetro opcional. Use quando o pagador for pessoa jurídica. |
| business_entity[document_number] | string | CNPJ da empresa pagadora, somente números. |
| participant_id | string | Parâmetro opcional. Banco do pagador, se já conhecido. Pula a etapa de escolha do banco na jornada. |
| debtor_account | object | Parâmetro opcional. Objeto Conta do pagador, se já conhecida. |
| debtor_account[ispb] | string | ISPB do banco do pagador (8 dígitos). |
| debtor_account[agency] | string | Número da agência, sem dígito. |
| debtor_account[account_number] | string | Número da conta, com o dígito verificador. |
| redirect_url | string | Parâ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_url | string | Parâmetro opcional. URL para onde o cliente volta em caso de erro na jornada. Se omitido, é usada a redirect_url. |
| webhook_url | string | Parâ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_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. |
| metadata | object | Parâmetro opcional. Objeto livre para guardar dados da sua aplicação. É devolvido nas consultas. |
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
| Propriedade | Tipo | Descrição |
|---|---|---|
| link_id | string | ID Marlim do link de pagamento. Guarde este ID: é com ele que você consulta e cancela o link e lista os pagamentos. |
| item_id | string | ID do link na sua plataforma. |
| current_status | string | Status atual do link. No momento da criação, sempre created. Veja Status do Link. |
| payment_url | string | URL para onde o cliente deve ser enviado para aprovar os pagamentos. |
| date_created | dateTime | Data de criação do link no formato ISODateTime. |
| expires_at | dateTime | Data de expiração do link no formato ISODateTime. |
Error Object
| Atributo | Tipo | Descrição |
|---|---|---|
| api_reference | string | URL para a documentação. Retornado nos erros de parâmetro. |
| 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. |
Enviando o cliente para o link
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ódigo | Significado |
|---|---|
rejected_by_customer | O cliente recusou o agendamento no banco. |
authorization_time_expired | O cliente não aprovou dentro do prazo. |
journey_time_expired | O 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.
- 1º Criar Link
- 2º Receber o Webhook
- 3º Consultar o Link
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"
}'
{
"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"
}
curl -X POST "https://suaaplicacao.com.br/webhook" \
-H "Content-Type: application/json" \
-H "User-Agent: Marlim/1.0.0" \
-H "Marlim-Api-Signature: Star98765Wars43210ANewHope1977" \
-H "Authorization: Bearer 1234567890" \
-d '{
"event": "scheduled_pix_link_status_changed",
"link_id": "vBn2Qw8ErT5yUi1OpL6k",
"item_id": "RESERVA_ENDOR_0042",
"current_status": "error",
"payment_url": "https://checkout.marlim.co/scheduled-pix/vBn2Qw8ErT5yUi1OpL6k",
"error": {
"code": "rejected_by_customer",
"title": "Rejected by customer",
"detail": "The customer rejected the payment at the bank."
},
"metadata": {},
"date_created": "2026-11-16T15:30:00.000Z",
"date_updated": "2026-11-16T15:34:51.000Z",
"expires_at": "2026-11-17T15:30:00.000Z"
}'
curl -X GET "https://sandbox.api.marlim.co/v3/scheduled_pix/links/vBn2Qw8ErT5yUi1OpL6k" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{}'
{
"link_id": "vBn2Qw8ErT5yUi1OpL6k",
"item_id": "RESERVA_ENDOR_0042",
"current_status": "error",
"payment_url": "https://checkout.marlim.co/scheduled-pix/vBn2Qw8ErT5yUi1OpL6k",
"error": {
"code": "rejected_by_customer",
"title": "Rejected by customer",
"detail": "The customer rejected the payment at the bank."
},
"metadata": {},
"date_created": "2026-11-16T15:30:00.000Z",
"date_updated": "2026-11-16T15:34:51.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ódigo | Significado |
|---|---|
insufficient_balance | Conta do cliente sem saldo suficiente, mesmo após a nova tentativa do banco no dia. |
amount_above_limit | Valor acima do limite de Pix definido pelo cliente no banco. |
refused_by_bank | Recusado pelo banco do cliente. O motivo vem em error.detail. |
account_holder_mismatch | A 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.
- 1º Criar Link
- 2º Receber o Webhook
- 3º Listar os Pagamentos
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"
}
}'
{
"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"
}
curl -X POST "https://suaaplicacao.com.br/webhook" \
-H "Content-Type: application/json" \
-H "User-Agent: Marlim/1.0.0" \
-H "Marlim-Api-Signature: Star98765Wars43210ANewHope1977" \
-H "Authorization: Bearer 1234567890" \
-d '{
"event": "scheduled_pix_payment_status_changed",
"payment_id": "pAy2Kj9HgF5dSa1QwE7u",
"link_id": "sKd4Wp7RtY2nQm9XbC3v",
"item_id": "CURSO_PILOTAGEM_00321",
"current_status": "rejected",
"date": "2027-01-10",
"amount": 25000,
"description": "Curso de Pilotagem 3x",
"customer": {
"name": "Luke Skywalker",
"document_number": "00099988877"
},
"participant": {
"participant_id": "c8f0bf49-4744-4933-8960-7add6e590841",
"name": "Banco da Aliança"
},
"end_to_end_id": null,
"error": {
"code": "insufficient_balance",
"title": "Insufficient balance",
"detail": "The customer's account does not have enough balance."
},
"metadata": {
"turma": "2027A"
},
"date_created": "2026-11-16T14:23:02.410Z",
"date_updated": "2027-01-10T18:00:12.000Z"
}'
curl -X GET "https://sandbox.api.marlim.co/v3/scheduled_pix/links/sKd4Wp7RtY2nQm9XbC3v/payments" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{}'
{
"link_id": "sKd4Wp7RtY2nQm9XbC3v",
"payments": [
{
"payment_id": "pAy1Mn6BvC3xZq8WeR4t",
"link_id": "sKd4Wp7RtY2nQm9XbC3v",
"item_id": "CURSO_PILOTAGEM_00321",
"current_status": "paid",
"date": "2026-12-10",
"amount": 25000,
"description": "Curso de Pilotagem 3x",
"customer": {
"name": "Luke Skywalker",
"document_number": "00099988877"
},
"participant": {
"participant_id": "c8f0bf49-4744-4933-8960-7add6e590841",
"name": "Banco da Aliança"
},
"end_to_end_id": "E12345678202612100612abcdef12345",
"error": null,
"metadata": {
"turma": "2027A"
},
"date_created": "2026-11-16T14:23:02.410Z",
"date_updated": "2026-12-10T06:12:44.000Z"
},
{
"payment_id": "pAy2Kj9HgF5dSa1QwE7u",
"link_id": "sKd4Wp7RtY2nQm9XbC3v",
"item_id": "CURSO_PILOTAGEM_00321",
"current_status": "rejected",
"date": "2027-01-10",
"amount": 25000,
"description": "Curso de Pilotagem 3x",
"customer": {
"name": "Luke Skywalker",
"document_number": "00099988877"
},
"participant": {
"participant_id": "c8f0bf49-4744-4933-8960-7add6e590841",
"name": "Banco da Aliança"
},
"end_to_end_id": null,
"error": {
"code": "insufficient_balance",
"title": "Insufficient balance",
"detail": "The customer's account does not have enough balance."
},
"metadata": {
"turma": "2027A"
},
"date_created": "2026-11-16T14:23:02.410Z",
"date_updated": "2027-01-10T18:00:12.000Z"
},
{
"payment_id": "pAy3Pl4OkI7uJy2HtG9r",
"link_id": "sKd4Wp7RtY2nQm9XbC3v",
"item_id": "CURSO_PILOTAGEM_00321",
"current_status": "scheduled",
"date": "2027-02-10",
"amount": 25000,
"description": "Curso de Pilotagem 3x",
"customer": {
"name": "Luke Skywalker",
"document_number": "00099988877"
},
"participant": {
"participant_id": "c8f0bf49-4744-4933-8960-7add6e590841",
"name": "Banco da Aliança"
},
"end_to_end_id": null,
"error": null,
"metadata": {
"turma": "2027A"
},
"date_created": "2026-11-16T14:23:02.410Z",
"date_updated": "2026-11-16T14:23:02.410Z"
}
]
}
Exemplos
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
- Mensal
- Datas personalizadas
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"
}
}'
{
"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"
}
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"
],
"additional_information": "Entrada, segunda parcela e quitação antes da hospedagem"
},
"method": "bank_account",
"creditor_account": {
"document_number": "11222333000181",
"ispb": "12345678",
"agency": "0001",
"account_number": "111882220",
"type": "checking"
},
"customer": {
"name": "Leia Organa",
"document_number": "00011122233"
},
"redirect_url": "https://suaaplicacao.com.br/obrigado",
"webhook_url": "https://suaaplicacao.com.br/webhook"
}'
{
"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"
}
Erros
- Parâmetros inválidos
- Quantidade acima do limite
- Conta recebedora ausente
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"
}'
{
"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."
}
]
}
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": "monthly",
"start_date": "2026-12-10",
"quantity": 36,
"day_of_month": 10
},
"method": "default_account",
"customer": {
"document_number": "00099988877"
}
}'
{
"api_reference": "https://docs.api.marlim.co/scheduled-pix/links/create",
"errors": [
{
"type": "schedule",
"message": "The parameter [ schedule.quantity ] must be between 2 and 24 for monthly schedules."
}
]
}
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": "single",
"date": "2026-12-20"
},
"method": "bank_account",
"customer": {
"document_number": "00099988877"
}
}'
{
"api_reference": "https://docs.api.marlim.co/scheduled-pix/links/create",
"errors": [
{
"type": "creditor_account",
"message": "The parameter [ creditor_account ] is required when [ method ] is bank_account."
}
]
}