ZypfyDocs Acessar painel
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:

Endpoints

código
GET https://api.zypfy.com/api/transactions/deposit
GET https://api.zypfy.com/api/transactions/withdraw

Consultar depósito

código
GET /api/transactions/deposit?{parametro}={valor}

Headers: Authorization: Bearer SEU_TOKEN.

Parâmetros (forneça exatamente um)

Query paramExemploNotas
end_to_endE00416968202406171524...EndToEnd ID do PIX (gerado pelo BACEN na liquidação). Disponível em depósitos COMPLETED.
transaction_ida1b2c3d4-e5f6-7890-abcd-ef1234567890ID da Zypfy. Você recebe no response do POST e no webhook.
external_idorder-2026-0001ID gerado pelo seu sistema na criação.
txidTXID123ABCTXID EMV do QR Code.
idempotency_key—Ignorado em depósitos (usado apenas em saques).

Exemplo de chamada

bash
curl -H "Authorization: Bearer SEU_TOKEN" \
  "https://api.zypfy.com/api/transactions/deposit?external_id=order-2026-0001"

Resposta 200 OK

json
{
  "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

código
GET /api/transactions/withdraw?{parametro}={valor}

Parâmetros (forneça exatamente um)

Query paramExemploNotas
end_to_endE0041696820240617152400000000002EndToEnd ID do PIX do saque. Disponível em saques COMPLETED.
transaction_idb2c3d4e5-f6a7-8901-bcde-f23456789012ID da Zypfy.
external_idsaque-0001ID gerado pelo seu sistema.
idempotency_keysaque-0001Chave de idempotência persistida (geralmente igual ao external_id).

Exemplo de chamada

bash
curl -H "Authorization: Bearer SEU_TOKEN" \
  "https://api.zypfy.com/api/transactions/withdraw?external_id=saque-0001"

Resposta 200 OK

json
{
  "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árioMelhor parâmetro
Logo após criar a transaçãoexternal_id (você já tem em mãos)
Depois de receber o webhooktransaction_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áticotxid (depósitos apenas)
Fluxos de retry/idempotência internosidempotency_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:

  1. A cada execução (cron ou scheduler), para cada transação que seu sistema considera PENDING há mais de X minutos…
  2. Chame GET /api/transactions/deposit?external_id=… ou GET /api/transactions/withdraw?external_id=….
  3. 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

javascript
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

HTTPRespostaCausa
400Provide at least one unique parameter: ...Você não passou nenhum query param.
401Unauthorized.Token ausente.
403—Token inválido ou expirado.

Boas práticas