Webhook: depósito (enviado pela Zypfy ao seu servidor)
https://seusite.com/webhooks/zypfysua URL de callback (clientCallbackUrl ou a configurada no painel)Este endpoint é hospedado pelo seu servidor, não pela Zypfy.
A Zypfy faz POST para a URL configurada em clientCallbackUrl (do
request de criação do depósito) ou para a URL global configurada no
portal quando o status do depósito muda.
Headers que você vai receber
Content-Type: application/jsonAuthorization: Bearer <CLIENT_CALLBACK_TOKEN>(token fixo para identificar que o callback vem da Zypfy — configurado internamente).X-Webhook-Signature: HMAC-SHA256 (hex) de${X-Webhook-Timestamp}.${corpo_bruto}, assinado com a sua Webhook Signature.X-Webhook-Timestamp: unix time (segundos) do momento da assinatura.
Validando a assinatura
Recompute HMAC_SHA256(secret, "${timestamp}.${corpo_bruto}") sobre o
corpo bruto recebido e compare com X-Webhook-Signature em tempo
constante. Rejeite timestamps com mais de 5 minutos de diferença. A
Webhook Signature fica em Configurações > Credenciais. Veja o guia
Verificando a assinatura dos webhooks para exemplos em Node e PHP.
Fluxo de entrega
- A Zypfy tenta entregar o webhook quando o status do depósito muda
para
COMPLETEDouFAILED. - O timeout da requisição é 8 segundos.
- Se seu servidor responder
2xx, a entrega é marcada como sucedida. - Não há retry automático agressivo. Se o webhook falhar, você
precisa reconciliar chamando
GET /api/transactions/depositcomexternal_idouend_to_end.
Corpo da requisição
typestringvalores:Depositexemplo:Depositexternal_idstring | nullexemplo:order-2026-0001transaction_idstringexemplo:a1b2c3d4-e5f6-7890-abcd-ef1234567890txidstring | nullexemplo:TXID123ABCend_to_endstring | nullexemplo:E0041696820240617152400000000001payer_namestring | nullexemplo:João Silvapayer_cpfstring | nullexemplo:12345678901payer_ispbstring | nullexemplo:12345678statusstringvalores:PENDINGPROCESSINGCOMPLETEDFAILEDcurrencystringMoeda da cobrança.
MXNem depósitos México (SPEI).valores:BRLMXNexemplo:BRLamountnumber (float)Valor que efetivamente entrou e virou saldo (bruto, antes da taxa). No PIX é sempre igual ao valor cobrado. No SPEI (MXN) o pagador digita o valor livremente, então num pagamento parcial este campo vem menor que
amount_expected— use ele, e não o valor do pedido, para decidir a entrega.exemplo:100amount_expectednumber (float)Valor original da cobrança. Somente em depósitos MXN (SPEI). Igual a
amountquando o pagamento foi integral.exemplo:100amount_paidnumber (float)Total que o pagador transferiu, incluindo eventual excedente. Somente em depósitos MXN (SPEI). Quando ele paga a mais,
amount_paid>amount, porque o crédito é limitado ao valor cobrado.exemplo:100partialbooleantruequando a cobrança liquidou com pagamento parcial — o pagador mandou menos queamount_expected. Somente em depósitos MXN (SPEI). Se o pagador completar o valor depois, chega um novo webhook com o acumulado epartial: false.exemplo:falsefeenumber (float)Taxa cobrada sobre o valor que entrou (
amount).exemplo:2.5updated_atstring (date-time)exemplo:2026-04-18T12:05:00.000Zerror_codestring | nullPresente apenas em
FAILED.error_messagestring | nullPresente apenas em
FAILED.