Guia de integração
Consultas
Use os endpoints de consulta para recuperar o estado atual de um depósito ou saque a partir de qualquer identificador único que você tenha em mãos. São essenciais para:
- Reconciliação pós-falha de webhook — quando a entrega do webhook falha no seu servidor, você busca o estado atual aqui.
- Relatórios e auditoria — pegar snapshot de uma transação específica.
- Suporte ao cliente final — verificar status de um pagamento sem precisar acessar o portal.
Endpoints
GET https://api.zypfy.com/api/transactions/deposit
GET https://api.zypfy.com/api/transactions/withdrawConsultar depósito
GET /api/transactions/deposit?{parametro}={valor}Headers: Authorization: Bearer SEU_TOKEN.
Parâmetros (forneça exatamente um)
| Query param | Exemplo | Notas |
|---|---|---|
end_to_end | E00416968202406171524... | EndToEnd ID do PIX (gerado pelo BACEN na liquidação). Disponível em depósitos COMPLETED. |
transaction_id | a1b2c3d4-e5f6-7890-abcd-ef1234567890 | ID da Zypfy. Você recebe no response do POST e no webhook. |
external_id | order-2026-0001 | ID gerado pelo seu sistema na criação. |
txid | TXID123ABC | TXID EMV do QR Code. |
idempotency_key | — | Ignorado em depósitos (usado apenas em saques). |
Exemplo de chamada
curl -H "Authorization: Bearer SEU_TOKEN" \
"https://api.zypfy.com/api/transactions/deposit?external_id=order-2026-0001"Resposta 200 OK
{
"filters": {
"end_to_end": null,
"transaction_id": null,
"external_id": "order-2026-0001",
"txid": null,
"idempotency_key": null
},
"deposit": {
"type": "deposit",
"id": 101,
"transaction_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"end_to_end_id": "E0041696820240617152400000000001",
"external_id": "order-2026-0001",
"txid": "TXID123ABC",
"amount": 100.00,
"fee": 2.50,
"total": null,
"status": "COMPLETED",
"payer_name": "João Silva",
"payer_cpf": "12345678901",
"payer_ispb": "12345678",
"created_at": "2026-04-18T12:00:00.000Z"
}
}Se nenhum registro bater com os filtros, deposit vem como null.
Consultar saque
GET /api/transactions/withdraw?{parametro}={valor}Parâmetros (forneça exatamente um)
| Query param | Exemplo | Notas |
|---|---|---|
end_to_end | E0041696820240617152400000000002 | EndToEnd ID do PIX do saque. Disponível em saques COMPLETED. |
transaction_id | b2c3d4e5-f6a7-8901-bcde-f23456789012 | ID da Zypfy. |
external_id | saque-0001 | ID gerado pelo seu sistema. |
idempotency_key | saque-0001 | Chave de idempotência persistida (geralmente igual ao external_id). |
Exemplo de chamada
curl -H "Authorization: Bearer SEU_TOKEN" \
"https://api.zypfy.com/api/transactions/withdraw?external_id=saque-0001"Resposta 200 OK
{
"filters": {
"end_to_end": null,
"transaction_id": null,
"external_id": "saque-0001",
"txid": null,
"idempotency_key": null
},
"withdraw": {
"type": "withdraw",
"id": 202,
"transaction_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
"end_to_end_id": "E0041696820240617152400000000002",
"external_id": "saque-0001",
"amount": 50.00,
"fee": 2.50,
"total": 52.50,
"status": "COMPLETED",
"receiver_name": "João Silva",
"receiver_cpf": "12345678901",
"receiver_ispb": "87654321",
"created_at": "2026-04-18T12:05:00.000Z"
}
}Quando usar cada parâmetro
| Cenário | Melhor parâmetro |
|---|---|
| Logo após criar a transação | external_id (você já tem em mãos) |
| Depois de receber o webhook | transaction_id (vem no webhook) |
| Transação já liquidada (depois do PIX cair) | end_to_end ou end_to_end_id (vem no webhook e em auditorias bancárias) |
| Conferir TXID em QR Code PIX estático | txid (depósitos apenas) |
| Fluxos de retry/idempotência internos | idempotency_key (saques apenas) |
Reconciliação pós-falha de webhook
Webhooks podem falhar. Redes caem, seu servidor pode estar em deploy, firewall pode bloquear, etc. A Zypfy não retenta webhooks indefinidamente — ela tenta uma vez com timeout de 8s, e se falhar, o status fica registrado apenas no lado da Zypfy.
A solução robusta é cross-check periódico:
- A cada execução (cron ou scheduler), para cada transação que seu sistema considera
PENDINGhá mais de X minutos… - Chame
GET /api/transactions/deposit?external_id=…ouGET /api/transactions/withdraw?external_id=…. - Se a Zypfy reportar status diferente (
COMPLETED/FAILED), atualize seu banco local e dispare o resto do seu fluxo.
Exemplo: reconciliação em Node.js
async function reconcilePendingWithdrawals() {
const token = await getToken();
const pendings = await db.query(
`SELECT external_id FROM saques WHERE status='PENDING' AND created_at < NOW() - INTERVAL '10 minutes'`
);
for (const { external_id } of pendings) {
const { data } = await axios.get(
`https://api.zypfy.com/api/transactions/withdraw`,
{
headers: { Authorization: `Bearer ${token}` },
params: { external_id },
}
);
if (data.withdraw && data.withdraw.status !== 'PENDING') {
await db.query(
`UPDATE saques SET status=$1, updated_at=NOW() WHERE external_id=$2`,
[data.withdraw.status, external_id]
);
// dispara lógica pós-confirmação
}
}
}
// Rode a cada 5 minutos
setInterval(reconcilePendingWithdrawals, 5 * 60 * 1000);Códigos de erro
| HTTP | Resposta | Causa |
|---|---|---|
| 400 | Provide at least one unique parameter: ... | Você não passou nenhum query param. |
| 401 | Unauthorized. | Token ausente. |
| 403 | — | Token inválido ou expirado. |
Boas práticas
- Sempre mantenha o
external_idcomo ponte entre seu sistema e a Zypfy. É o parâmetro mais estável para consulta. - Configure reconciliação automática — não trate o webhook como única fonte da verdade.
- Nunca considere uma transação "não existente" sem primeiro checar aqui por
external_id— um HTTP 404 na camada HTTP do seu webhook não significa que a Zypfy não tem registro.