Primeiros passos

Cinco minutos até a sua primeira Cobrança (charge).

#1. Pegue sua chave de API

Entre no painel Demo Pay → Configurações → Chaves de API → Criar chave, ou pela API/CLI como está em Chaves de API.

Você recebe uma chave assim:

dm_test_8f3a9b2c1d4e5f6a7b8c9d0e1f2a3b4c

Chaves dm_test_* batem na mesma infraestrutura de produção, com comportamento seguro para teste; chaves dm_live_* movem dinheiro de verdade. Trate as duas como senha: quem tem a chave cria cobrança na sua conta. Guarde só no servidor — nunca mande para navegador ou app mobile. O texto em claro aparece uma única vez, na emissão; se você perder, veja rotação em Chaves de API.

#2. Escolha o ambiente

Todos os exemplos deste guia usam a URL de produção.

#3. Faça a primeira chamada

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

Resposta de sucesso (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"
  },
  "settlement": {},
  "metadata": { "order_id": "12345" },
  "created_at": "2026-07-23T14:30:00.000Z"
}

O id (ch_…) é o identificador da cobrança — use-o para consultar status e conciliar webhooks. No Pix, o BR Code e o QR Code já vêm na resposta de criação: não é preciso consultar de novo para renderizar o checkout.

pix.txid e settlement.end_to_end_id são dado contextual do Pix pelo BACEN, não identificadores — veja Pix. settlement fica {} até a cobrança virar paid.

#4. Convenções

Estas regras valem para todos os endpoints da família /v1/charges.

#Autenticação

Toda requisição a endpoint de lojista leva sua chave de API no cabeçalho apikey:

apikey: dm_live_...

Chave ausente ou inválida devolve 401 Unauthorized.

#Valores são inteiros na menor unidade da moeda

Cobrança Pix liquida só em BRL hoje. Nunca mande decimal — 10.00 é recusado.

#Idempotência é obrigatória na escrita

Todo POST /v1/charges precisa do cabeçalho Idempotency-Key (8 a 128 caracteres, com escopo lojista + operação + chave — a mesma chave vinda de outro lojista nunca conflita).

Reenviar a mesma chave com o mesmo corpo devolve a resposta guardada, o que garante que uma retentativa de rede, um duplo toque no app ou o restart de um job em background nunca cobrem duas vezes. Reusar a chave com corpo diferente devolve 409 e error.code: "idempotency_key_reused" (veja Erros). O servidor guarda o registro por no mínimo 24 horas.

Recomendado: use o id interno do seu pedido (ex.: pedido-12345).

Não use valor aleatório. Um UUID novo a cada tentativa reintroduz exatamente o problema que a chave existe para resolver: se a requisição chegou mas a resposta se perdeu, repetir com chave nova cria uma segunda cobrança.

#Datas em ISO 8601 UTC

2026-07-23T14:30:00.000Z

#Identificadores

Id de cobrança sempre começa com ch_ seguido de uma string opaca em formato UUID — por exemplo ch_a1b2c3d4-e5f6-4789-9abc-def012345678. Trate como string opaca: não faça parse, não ordene lexicograficamente, não deduza ordem do valor. ch_… é sempre o id Demo Pay; o pix.txid e o settlement.end_to_end_id do BACEN são dado contextual do Pix e nunca substituem o id.

#Erros

Todo erro vem no envelope canônico:

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_amount",
    "message": "amount deve ser um inteiro positivo em centavos.",
    "param": "amount"
  },
  "request_id": "req_01J..."
}

Toda resposta — de sucesso ou de erro — também traz X-Request-Id. Veja Erros para o envelope completo e o mapa de status.

#Limites de taxa

200 req/s, 5000 req/min e 50000 req/hora por chave autenticada, por padrão. Precisa de mais? Escreva para suporte@demo.zentry.cloud.

#5. Ciclo de vida da cobrança

                  ┌──────────────────────┐
                  │       pending        │  ← criada, esperando o pagador
                  └──────────┬───────────┘
                             │
                ┌────────────┼────────────┐
                ▼            ▼            ▼
          ┌─────────┐  ┌──────────┐  ┌─────────┐
          │  paid   │  │ expired  │  │ failed  │
          └────┬────┘  └──────────┘  └─────────┘
               │
               ▼
          ┌──────────┐
          │ refunded │
          └──────────┘

Vocabulário público de status: pending, processing, paid, failed, expired, cancelled, refunded, disputed. São estados estáveis, nos quais você pode ramificar; os estados internos de onde eles vêm nunca aparecem numa resposta de /v1/charges.

Libere o pedido no paid. O resto é informativo — e para essa transição prefira webhooks a ficar consultando.

#6. Consulte seu saldo

Quando as cobranças começam a liquidar, o saldo disponível está a uma chamada de distância — mesma apikey, sem corpo. O parâmetro currency é opcional; sem ele você recebe todas as moedas da conta:

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

{
  "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 }
  ]
}

Os valores vêm em centavos (880 = R$ 8,80). available é o que você pode gastar ou sacar agora; pending é o que já liquidou mas ainda não foi liberado. Quando há liberação agendada, next_release_at / next_release_amount dizem quando e quanto. Cada moeda da conta aparece em balances[].

Só uma moeda? Adicione ?currency=BRL para o formato achatado. Precisa de todas as carteiras (por tipo)? GET /v1/wallets devolve a lista completa. Veja a Referência da API.

#Próximo

→ Monte o fluxo Pix