Referência da API

Catálogo completo de todos os endpoints públicos da Demo Pay v1. Todos os caminhos são relativos à URL base de produção — https://demo.zentry.cloud/v1. (Um host de sandbox dedicado ainda não está disponível.)

Autentique toda requisição com sua chave de API no cabeçalho apikey — apikey: <DEMO_API_KEY> (dm_test_*/dm_live_*). Todos os corpos são JSON. Todos os valores são inteiros na menor unidade da moeda.

A API é organizada em torno de alguns recursos:

• Cobranças (/v1/charges) — criar e consultar cobranças Pix: object: "charge", ids ch_…, cabeçalho Idempotency-Key, bloco pix. É por aqui que toda integração começa.
• Carteiras (/v1/wallets) — o saldo da sua conta.
• Operações de pagamento (/v1/payments) — reembolso, cancelamento, estatísticas e outras operações sobre uma cobrança, endereçadas pelo id cru (sem o prefixo ch_).
• Webhooks (/v1/webhooks) — registrar endpoints e inspecionar entregas.

#Cobranças

/v1/charges.

Contrato público das convenções da API §3. Toda resposta é montada por um serializador com allowlist — nenhum id interno, nome de PSP, custo ou payload cru de provedor pode aparecer aqui.

#Criar cobrança

POST /v1/charges — atalho Pix-first: POST /v1/pix/charges fixa payment_method: "pix" no corpo e devolve exatamente a mesma Charge.

Cabeçalhos

Corpo

Exemplo

curl -X POST https://demo.zentry.cloud/v1/pix/charges \
  -H "apikey: $DEMO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000,
    "currency": "BRL",
    "description": "Pedido #12345",
    "customer": { "name": "Maria Silva", "document": "12345678901" }
  }'

Resposta 201 Created

{
  "id": "ch_a1b2c3d4-0000-0000-0000-000000000009",
  "object": "charge",
  "amount": 1000,
  "currency": "BRL",
  "status": "pending",
  "payment_method": "pix",
  "customer": { "name": "Maria Silva", "document": "12345678901" },
  "pix": {
    "br_code": "000201BRCODEPIX",
    "qr_code_url": "https://qr.example/img.png",
    "expires_at": "2026-07-23T15:00:00.000Z"
  },
  "checkout_url": "https://checkout.demo.zentry.cloud/a1b2c3d4-0000-0000-0000-000000000009",
  "settlement": {},
  "metadata": { "order_id": "12345" },
  "created_at": "2026-07-23T14:30:00.000Z"
}

pix.txid (quando o provedor vinculou um) e settlement.end_to_end_id (só depois de paid e liquidado) são dado contextual do Pix — veja PIX. charge.id nunca é igual a charge.pix.txid.

checkout_url é o checkout hospedado da Demo Pay para a cobrança — redirecione o pagador para lá em vez de renderizar sua própria tela de Pix. Vem tanto na criação quanto no GET /v1/charges/{id}, e não dá para deduzir de charge.id (o caminho do checkout remove o prefixo ch_).

Vocabulário público de status: pending, processing, paid, failed, expired, cancelled, refunded, disputed.

#Consultar cobrança

GET /v1/charges/{id}

Aceita tanto o id com prefixo ch_… quanto o id interno cru. Escopado à conta do chamador — uma cobrança de outra conta responde 404.

Resposta 200 OK — mesma forma de Charge da criação.

#Listar cobranças

Status: o contrato de query abaixo (ListChargesDto + PaymentsService.listCharges) está implementado e testado unitariamente, mas a rota GET /v1/charges ainda não está ligada a um controlador HTTP — chamá-la hoje dá 404. Use a listagem GET /v1/payments até isso subir. Rastreado como follow-up do contrato /v1/charges.

GET /v1/charges?limit=25&starting_after=ch_01J…&status=paid

{
  "object": "list",
  "data": [],
  "has_more": false,
  "next_cursor": null
}

page/offset nunca são aceitos nesta listagem por cursor — apenas starting_after.

#Carteiras

/v1/wallets. Os saldos da sua conta. Somente leitura, com escopo na sua chave de API.

#Consultar saldo

GET /v1/wallets/balance

O parâmetro currency é opcional. Sem ele (forma recomendada), a resposta traz todas as moedas da conta em balances[], mais os campos da moeda primária (BRL por padrão) no topo:

curl "https://demo.zentry.cloud/v1/wallets/balance" \
  -H "apikey: $DEMO_API_KEY"

Resposta 200 OK

{
  "available": 880,
  "pending": 0,
  "total": 880,
  "retained": 0,
  "currency": "BRL",
  "next_release_at": null,
  "next_release_amount": null,
  "balances": [
    { "currency": "BRL", "available": 880, "pending": 0, "total": 880 }
  ],
  "primary": { "currency": "BRL", "available": 880, "pending": 0, "total": 880 }
}

Os campos no topo (available/pending/total/currency) são a moeda primária — mantidos por compatibilidade. Para contas multi-moeda, itere sobre balances[].

#Uma moeda só (formato legado)

GET /v1/wallets/balance?currency=BRL

Passe currency para receber o formato achatado de uma única moeda:

curl "https://demo.zentry.cloud/v1/wallets/balance?currency=BRL" \
  -H "apikey: $DEMO_API_KEY"

{
  "available": 880,
  "pending": 0,
  "currency": "BRL",
  "next_release_at": null,
  "next_release_amount": null
}

Autenticação e erros. Sempre com o header apikey. Chave ausente ou inválida → 401 (nunca 404). Se você receber 404 nesta rota, o request não chegou na Demo Pay — quase sempre é caminho errado (/v1/wallets/balance, no plural, com o prefixo /v1) ou um proxy/gateway intermediário que não repassa /v1/wallets/*.

#Listar carteiras

GET /v1/wallets

Todas as carteiras da conta (operacional, por moeda), mesma autenticação.

curl https://demo.zentry.cloud/v1/wallets \
  -H "apikey: $DEMO_API_KEY"

Resposta 200 OK

[
  {
    "currency": "BRL",
    "walletType": "OPERATIONAL",
    "balance": 880,
    "pendingBalance": 0
  }
]

balance/pendingBalance vêm na menor unidade da moeda — os mesmos valores que GET /v1/wallets/balance expõe como available/pending.

#Operações de pagamento

/v1/payments. Estas rotas operam sobre a mesma cobrança que você criou via /v1/charges, endereçada pelo id cru (sem o prefixo ch_). Cobrem operações que a superfície /v1/charges ainda não expõe — reembolso, cancelamento, estatísticas, comprovantes — além de criar/consultar/listar no formato de fio de transação (ids tx_…, status WAITING_PAYMENT/PAID). Para criar uma cobrança, prefira Cobranças.

#Criar pagamento

POST /payments

Corpo

Resposta 201 Created

{
  "id": "a1b2c3d4-e5f6-4789-9abc-def012345678",
  "status": "WAITING_PAYMENT",
  "amount": 24900,
  "currency": "BRL",
  "paymentMethods": ["PIX"],
  "customerName": "Maria Silva",
  "customerDocument": "12345678909",
  "customerEmail": "maria@example.com",
  "metadata": { "orderId": "ORD-7821" },
  "createdAt": "2026-04-25T15:42:11.000Z"
}

Campos específicos de método (pixQrCode, cardRedirectUrl, etc.) são preenchidos pelo GET /payments/{id} depois que a Demo Pay finaliza a cobrança com o adquirente subjacente (normalmente <3s).

#Consultar pagamento

GET /payments/{id}

Resposta 200 OK

{
  "id": "a1b2c3d4-e5f6-4789-9abc-def012345678",
  "status": "PAID",
  "amount": 24900,
  "currency": "BRL",
  "paymentMethods": ["PIX"],
  "paidWith": "PIX",
  "pixQrCode": "data:image/png;base64,iVBOR...",
  "pixCopyPaste": "00020126580014br.gov.bcb.pix...",
  "pixExpiresAt": "2026-04-25T16:12:11.000Z",
  "cardRedirectUrl": null,
  "mbEntity": null,
  "mbReference": null,
  "mbExpiresAt": null,
  "boletoBarcode": null,
  "boletoLine": null,
  "boletoPdfUrl": null,
  "boletoExpiresAt": null,
  "cryptoAddress": null,
  "cryptoAmount": null,
  "cryptoNetwork": null,
  "cryptoCurrency": null,
  "providerFee": 75,
  "platformFee": 200,
  "netAmount": 24625,
  "metadata": { "orderId": "ORD-7821" },
  "createdAt": "2026-04-25T15:42:11.000Z",
  "paidAt": "2026-04-25T15:43:08.000Z"
}

Campos vêm null quando não se aplicam aos paymentMethods escolhidos.

#Listar pagamentos

GET /payments

Parâmetros de query

Resposta 200 OK

{
  "data": [ { "id": "tx_...", "...": "..." } ],
  "total": 142,
  "page": 1,
  "limit": 20
}

#Estatísticas

GET /payments/stats?days=7

Resposta 200 OK

{
  "totalTransactions": 142,
  "paidTransactions": 119,
  "todayTransactions": 8,
  "successRate": 84,
  "volumeByCurrency": [
    { "currency": "BRL", "volume": 1245000, "count": 95 },
    { "currency": "EUR", "volume": 89400,   "count": 24 }
  ],
  "todayVolumeByCurrency": { "BRL": 24900, "EUR": 8990 },
  "dailyVolume": [
    { "date": "2026-04-19", "currencies": { "BRL": 89000 } },
    { "date": "2026-04-20", "currencies": { "BRL": 124500, "EUR": 4500 } }
  ],
  "methodBreakdown": [
    { "method": "PIX",         "volume": 980000, "count": 78 },
    { "method": "CREDIT_CARD", "volume": 265000, "count": 34 },
    { "method": "MULTIBANCO",  "volume": 89400,  "count": 7 }
  ]
}

#Métricas

GET /payments/metrics?days=7&currency=BRL

Métricas de funil de conversão e volume da sua conta de lojista. days tem padrão 7; currency é opcional (filtra para uma única moeda). Escopado à sua apikey.

#Reembolsar pagamento

POST /payments/{id}/refund

Reembolsa uma transação liquidada (PAID ou APPROVED), total ou parcial. Ativo em produção. Para PIX isso mapeia para uma devolução BACEN (por endToEndId) ou um cashout PIX-out, conforme strategy.

Corpo

Resposta 201 Created

{
  "id": "b2c3d4e5-f6a7-4890-9abc-def012345678",
  "transactionId": "a1b2c3d4-e5f6-4789-9abc-def012345678",
  "amount": 24900,
  "currency": "BRL",
  "status": "PENDING",
  "reason": "customer_request",
  "createdAt": "2026-04-25T15:50:00.000Z"
}

O status do reembolso avança de forma assíncrona (PENDING → IN_PROGRESS → REFUNDED/FAILED) conforme o adquirente confirma — assine o webhook payment.refunded. A transação só vira REFUNDED quando o total reembolsado atinge o valor original; reembolsos parciais a deixam em PAID/APPROVED.

O suporte a reembolso depende do provedor: PIX (BrasilCash) e cartão (Stripe) estão ativos. Outros provedores devolvem um erro REFUND_NOT_SUPPORTED.

#Listar reembolsos

GET /payments/{id}/refunds

Devolve todos os reembolsos emitidos contra uma transação (mais recentes primeiro).

#Cancelar pagamento

POST /payments/{id}/cancel

Cancela uma cobrança em andamento — válido só enquanto WAITING_PAYMENT, PENDING ou PROCESSING. Cobranças liquidadas (PAID/APPROVED) devem ser reembolsadas, não canceladas. Devolve a transação atualizada e dispara payment.failed.

#Reenviar webhook

POST /payments/{id}/resend-webhook

Reemite o status atual da transação como uma entrega de webhook nova — útil quando seu endpoint estava fora do ar.

{ "resent": true, "status": "PAID" }

#Status no provedor

GET /payments/{id}/provider-status

Status ao vivo direto do adquirente (ignora nosso cache) — para depurar cobranças travadas.

{
  "localStatus": "WAITING_PAYMENT",
  "provider": "brasilcash",
  "providerTransactionId": "bc_...",
  "providerStatus": "PENDING",
  "rawResponse": { "...": "..." }
}

Devolve "error": "TRANSACTION_HAS_NO_PROVIDER_REFERENCE" quando a cobrança nunca chegou a um provedor.

#Comprovante

GET /payments/{id}/receipt

Comprovante do provedor (PDF) para uma transação liquidada, onde o adquirente expõe um (ex.: PIX da BrasilCash).

{ "contentType": "application/pdf", "base64": "JVBERi0xLjcK..." }

#Webhooks

#Registrar endpoint

POST /webhooks/endpoints

{
  "url": "https://merchant.example.com/hooks/demo",
  "events": ["charge.paid", "charge.failed", "charge.expired"]
}

Nomes de evento (relativos a cobrança): charge.created, charge.paid, charge.failed, charge.expired, payout.created, payout.paid, payout.failed. São entregues no envelope versionado evt_ e assinados X-Demo-Signature: t=<unix>,v1=<hex> — veja Webhooks. Assine estes.

O endpoint também aceita uma família de eventos mais antiga (payment.created, payment.completed, payment.failed, payment.expired, payment.refunded, withdrawal.* e os aliases payment.status_changed/withdrawal.status_changed), entregue com o envelope { event, data } e X-Demo-Signature: sha256=<hex>. Integrações novas não precisam dela — use os nomes charge.*/payout.* acima. A lista completa e atual é autoritativa em GET /webhooks/event-catalog.

Resposta 201 Created

{
  "id": "e5f6a7b8-c9d0-4123-9ef0-123456789012",
  "url": "https://merchant.example.com/hooks/demo",
  "events": ["charge.paid", "charge.failed", "charge.expired"],
  "secret": "b8f3a9c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1",
  "status": "ACTIVE"
}

O secret é mostrado uma única vez — guarde imediatamente.

#Listar endpoints

GET /webhooks/endpoints

{
  "data": [
    {
      "id": "wh_...",
      "url": "https://...",
      "events": ["payment.status_changed"],
      "status": "ACTIVE",
      "createdAt": "...",
      "updatedAt": "..."
    }
  ]
}

O secret nunca é devolvido por este endpoint.

#Rotacionar segredo

POST /webhooks/endpoints/{id}/rotate-secret

{ "id": "e5f6a7b8-c9d0-4123-9ef0-123456789012" }

Resposta 200 OK

{ "id": "e5f6a7b8-c9d0-4123-9ef0-123456789012", "secret": "<hex de 64 caracteres>" }

O novo segredo é mostrado uma única vez. A rotação é uma troca instantânea no servidor — não há janela de sobreposição. Todo webhook assinado depois desta chamada usa o novo segredo, então faça seu verificador aceitar ambos — o antigo e o novo — durante o seu deploy, e depois descarte o antigo (veja webhooks.md).

#Atualizar endpoint

PATCH /webhooks/endpoints/{id}

Atualiza URL, eventos assinados ou status (ACTIVE/INACTIVE). Envie só os campos a mudar.

{ "url": "https://merchant.example.com/hooks/v2", "status": "ACTIVE" }

Resposta 200 OK — { id, url, events, status }. O segredo nunca é devolvido.

#Remover endpoint

DELETE /webhooks/endpoints/{id}

Remove o endpoint permanentemente. Todas as entregas pendentes para ele são abandonadas.

Resposta 200 OK — { "deleted": true }.

#Catálogo de eventos

GET /webhooks/event-catalog

Devolve a lista completa e atual de nomes de evento públicos assináveis com descrições (legacy: true nas famílias descontinuadas). Sem autenticação. Trecho relevante para cobrança/saque:

[
  { "event": "charge.created", "description": "Cobrança criada (Pix/cartão gerado, aguardando pagamento)." },
  { "event": "charge.paid",    "description": "Cobrança paga e confirmada (Pix/cartão liquidado)." },
  { "event": "charge.failed",  "description": "Cobrança falhou ou foi cancelada." },
  { "event": "charge.expired", "description": "Cobrança expirou sem pagamento." },
  { "event": "payout.created", "description": "Saque solicitado." },
  { "event": "payout.paid",    "description": "Saque liquidado com sucesso." },
  { "event": "payout.failed",  "description": "Saque falhou ou foi rejeitado." },
  { "event": "payment.completed",    "description": "[legado] Cobrança paga — use charge.paid.", "legacy": true },
  { "event": "withdrawal.completed", "description": "[legado] Saque liquidado — use payout.paid.", "legacy": true }
]

#Listar entregas

GET /webhooks/deliveries

{
  "data": [
    {
      "id": "wd_...",
      "endpointId": "wh_...",
      "eventType": "payment.completed",
      "status": "DELIVERED",
      "attempts": 1,
      "maxAttempts": 15,
      "lastStatusCode": 200,
      "lastError": null,
      "nextRetryAt": null,
      "deliveredAt": "2026-04-25T15:43:09.000Z",
      "createdAt": "2026-04-25T15:43:08.000Z",
      "updatedAt": "2026-04-25T15:43:09.000Z",
      "payload": { "event": "payment.completed", "data": { "...": "..." } }
    }
  ],
  "total": 142,
  "limit": 25,
  "offset": 0
}

#Estatísticas de entrega

GET /webhooks/stats

{
  "total": 1402,
  "PENDING": 3,
  "PROCESSING": 1,
  "DELIVERED": 1380,
  "FAILED": 12,
  "CANCELLED": 6
}

#Enum de status

A tabela abaixo é o enum de status detalhado devolvido pelas rotas de transação /v1/payments (e eventType/payload.data.status nas entregas de webhook delas). POST/GET /v1/charges nunca emitem esses valores; eles emitem o vocabulário público menor (pending, processing, paid, failed, expired, cancelled, refunded, disputed — veja Primeiros passos §5), no qual o enum abaixo é mapeado.

payment.completed dispara para PAID e APPROVED; charge.paid dispara para a mesma transição subjacente. payment.failed dispara para REFUSED, CANCELLED, EXPIRED, CHARGEBACK, DISPUTE; charge.failed e charge.expired dividem essa família payment.* mais antiga por desfecho.

#Schema do payload de webhook

#Envelope canônico (charge.* / payout.*)

{
  "id": "evt_5f3a9b2c1d4e5f6a7b8c9d0e1f2a3b4c",
  "object": "event",
  "api_version": "2026-07-23",
  "type": "charge.paid",
  "created_at": "2026-07-23T14:31:00.000Z",
  "data": {
    "object": {
      "id": "ch_a1b2c3d4-0000-0000-0000-000000000009",
      "object": "charge",
      "amount": 24900,
      "currency": "BRL",
      "status": "paid",
      "payment_method": "pix",
      "settlement": { "end_to_end_id": "E-END-TO-END-99" }
    }
  }
}

#Envelope payment.* / withdrawal.*

{
  "event": "payment.completed",
  "data": {
    "transactionId": "tx_...",
    "amount": 24900,
    "status": "PAID",
    "previousStatus": "WAITING_PAYMENT",
    "paidWith": "PIX",
    "providerFee": 75,
    "platformFee": 200,
    "netAmount": 24625,
    "occurredAt": "2026-04-25T15:43:08.000Z"
  }
}

#Cabeçalhos de webhook

Veja webhooks.md para exemplos de verificação.

#Códigos de status HTTP

Veja Erros para o envelope canônico completo de erro (error.type/error.code/error.message, request_id, X-Request-Id).