Pular para o conteúdo principal

Webhooks de Pix Agendado

Disponível apenas em Sandbox

O Pix Agendado está disponível somente no ambiente Sandbox. Não há suporte 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.

Todo o processo do Pix Agendado é assíncrono. Por isso, é importante que você passe um webhook_url na criação do link. A Marlim envia um POST para esse endereço sempre que o link ou qualquer pagamento do agendamento muda de status.

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}
Atenção

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_

Eventos​

EventoQuando é enviado
scheduled_pix_link_status_changedMudança de status do link: processing, payment_pending, completed, canceled, expired e error.
scheduled_pix_payment_status_changedQualquer mudança de status de um pagamento, incluindo o cancelamento feito pelo cliente no banco.

O corpo do webhook traz o campo event e os mesmos campos da consulta do objeto que mudou: link ou pagamento.

Dica

Responda com HTTP 200 o mais rápido possível e processe o evento de forma assíncrona. O mesmo evento pode chegar mais de uma vez: trate o evento de forma idempotente usando o ID do objeto (link_id ou payment_id) junto com o current_status.

Exemplos​

Exemplo do BODY de um WEBHOOK da Marlim para a sua aplicação
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": "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"
}'