Pular para o conteúdo principal

Webhooks de Pix por Biometria

Disponível apenas em Sandbox

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

O Pix por Biometria 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 por Biometria é 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 o pagamento gerado por ele 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
biometric_pix_link_status_changedMudança de status do link: processing, payment_pending, completed, canceled, expired e error.
biometric_pix_payment_status_changedQualquer mudança de status do pagamento.

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": "biometric_pix_payment_status_changed",
"payment_id": "pMt9Ws4EdC7rFv2TgB6y",
"link_id": "bIo6Lm3NqZ8tRw1YcV5k",
"item_id": "PEDIDO_1138",
"current_status": "paid",
"amount": 8990,
"description": "Pedido 1138 Cantina Mos Eisley",
"method": "default_account",
"customer": {
"name": "Han Solo",
"document_number": "00077766655"
},
"participant": {
"participant_id": "c8f0bf49-4744-4933-8960-7add6e590841",
"name": "Banco da Aliança"
},
"end_to_end_id": "E12345678202611161420abcdef67890",
"error": null,
"metadata": {
"canal": "app"
},
"date_created": "2026-11-16T14:19:52.000Z",
"date_updated": "2026-11-16T14:20:31.207Z"
}'