Documentação PayCad

Início rápido

Três passos, nada além disso.

1. 1

   Pegue sua chave de API

   Crie sua conta, abra Integração e gere a chave. Use sk_test_ para testar e sk_live_ quando for cobrar de verdade.

2. 2

   Envie a requisição

   Um POST para /api/public/v1/pix devolve o copia e cola do PIX e uma URL de checkout pronta.

3. 3

   Receba o webhook

   Quando o cliente pagar, enviamos pix.paid para a sua URL. Responda HTTP 200 e libere o pedido.

Autenticação

Toda requisição usa a sua chave secreta no cabeçalho Authorization no formato Bearer. O ambiente é definido pela própria chave: nada de parâmetro extra.

Authorization: Bearer sk_test_...   # ambiente de testes (sandbox)
Authorization: Bearer sk_live_...   # ambiente de produção (dinheiro real)

Nunca exponha a chave secreta no front-end. Chame a API a partir do seu servidor.

Criar cobrança PIX

POST /api/public/v1/pix — só o essencial: amount (obrigatório) e os dados do pagador payer_name, payer_email, payer_cpf (opcionais, apenas CPF — nunca pedimos CNPJ), além de description. A tarifa fixa de R$ 0,80 já vem descontada em amount_net.

curl -X POST https://api.paycad.app/api/public/v1/pix \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 149.90,
    "description": "Plano Pro",
    "payer_name": "Cliente Exemplo",
    "payer_email": "cliente@email.com",
    "payer_cpf": "123.456.789-09"
  }'

Resposta 201

{
  "id": "8f1c2e70-9f2a-4c3b-8f6e-2a9c1d4e5b70",
  "environment": "sandbox",
  "status": "pending",
  "amount_gross": 149.9,
  "platform_fee": 0.8,
  "amount_net": 149.1,
  "pix_copy_paste": "00020126...5304...6304ABCD",
  "checkout_url": "https://api.paycad.app/checkout/8f1c2e70-..."
}

Webhooks

Cadastre a URL do webhook em Integração. Assim que o PIX for confirmado, enviamos este payload:

POST https://seusite.com/webhooks/paycad
Content-Type: application/json
x-paycad-event: pix.paid
x-paycad-environment: production

{
  "event": "pix.paid",
  "environment": "production",
  "transaction_id": "8f1c2e70-9f2a-4c3b-8f6e-2a9c1d4e5b70",
  "amount": 149.9,
  "net_amount": 149.1,
  "payer_name": "Cliente Exemplo",
  "status": "paid"
}

Como responder

Retorne HTTP 200 assim que receber. Qualquer outro status é tratado como falha de entrega.

app.post("/webhooks/paycad", express.json(), (req, res) => {
  const { event, transaction_id, net_amount } = req.body;

  if (event === "pix.paid") {
    liberarPedido(transaction_id, net_amount);
  }

  // Sempre responda 200 para confirmar o recebimento
  res.sendStatus(200);
});