Webhooks de Pix Automático

Disponível apenas em Sandbox

O Pix Automático está disponível somente no ambiente Sandbox. Não há suporte em produção no momento.

Todo o processo do Pix Automático é 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, a autorização gerada por ele ou qualquer cobrança dessa autorização 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

Evento	Quando é enviado
`automatic_pix_link_status_changed`	Mudança de status do link: `processing`, `completed`, `canceled`, `expired` e `error`.
`automatic_pix_authorization_status_changed`	Mudança de status da autorização: aprovada, rejeitada, revogada, consumida, cancelada ou expirada.
`automatic_pix_charge_status_changed`	Qualquer mudança de status de uma cobrança, incluindo as retentativas.

O corpo do webhook traz o campo event e os mesmos campos da consulta do objeto que mudou: link, autorização ou cobrança.

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, authorization_id ou charge_id) junto com o current_status.

Exemplos

Cobrança
Autorização
Link

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": "automatic_pix_charge_status_changed",
  "charge_id": "cHg4Tn8PqW1zLm6XbY2d",
  "authorization_id": "aUt7Hq2LmZ9xVb3KcR8s",
  "link_id": "pXq3Lk9TzR2mWb7NcA1e",
  "item_id": "MENSALIDADE_2026_12",
  "current_status": "paid",
  "date": "2026-12-05",
  "amount": 65000,
  "description": "Mensalidade dezembro",
  "customer": {
    "document_number": "00099988877"
  },
  "end_to_end_id": "E12345678202612050612abcdef12345",
  "has_retry": false,
  "original_charge_id": null,
  "error": null,
  "metadata": {},
  "date_created": "2026-11-25T17:33:06.364Z",
  "date_updated": "2026-12-05T06:12:44.000Z"
}'

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": "automatic_pix_authorization_status_changed",
  "authorization_id": "aUt7Hq2LmZ9xVb3KcR8s",
  "link_id": "pXq3Lk9TzR2mWb7NcA1e",
  "item_id": "MATRICULA_2026_00123",
  "current_status": "authorized",
  "contract_id": "CTR_2026_00123",
  "interval": "monthly",
  "reference_start_date": "2026-12-01",
  "fixed_amount": null,
  "min_variable_amount": 50000,
  "max_variable_amount": 80000,
  "is_retry_accepted": true,
  "start_date_time": "2026-11-12T14:22:38.000Z",
  "expiration_date_time": null,
  "customer": {
    "name": "Luke Skywalker",
    "document_number": "00099988877"
  },
  "contract_debtor": {
    "name": "Luke Skywalker",
    "document_number": "00099988877"
  },
  "creditors": [
    {
      "name": "Academia Jedi Ltda",
      "document_number": "11222333000181"
    }
  ],
  "participant": {
    "participant_id": "c8f0bf49-4744-4933-8960-7add6e590841",
    "name": "Banco da Aliança"
  },
  "rejection": null,
  "revocation": null,
  "metadata": {
    "plano": "anual"
  },
  "date_authorized": "2026-11-12T14:22:38.000Z",
  "date_created": "2026-11-12T14:20:05.000Z",
  "date_updated": "2026-11-12T14:22:40.112Z"
}'

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": "automatic_pix_link_status_changed",
  "link_id": "pXq3Lk9TzR2mWb7NcA1e",
  "item_id": "MATRICULA_2026_00123",
  "current_status": "completed",
  "authorization_url": "https://checkout.marlim.co/automatic-pix/pXq3Lk9TzR2mWb7NcA1e",
  "authorization_id": "aUt7Hq2LmZ9xVb3KcR8s",
  "error": null,
  "metadata": {
    "plano": "anual"
  },
  "date_created": "2026-11-12T14:19:18.051Z",
  "date_updated": "2026-11-12T14:22:40.112Z",
  "expires_at": "2026-11-20T23:59:59.000Z"
}'

Eventos​

Exemplos​

Eventos

Exemplos