Documentação da API Pix

1. Fluxo recomendado (QR na sua página)

• A API devolve o Pix copia-e-cola (BR Code/EMV) em qr_copy_paste. Gere a imagem do QR no front (ex.: lib qrcode). Não precisa redirecionar para pay_url.
• A chave dpk_ nunca vai para o navegador. A API não libera CORS para outros domínios: tudo passa pelo seu backend.
• Libere o pedido só com status: "paid" (webhook com assinatura válida ou GET autenticado). Nunca só porque o QR apareceu.

2. Autenticação

Cada loja recebe uma chave de API e um segredo de webhook:

Uma chave amarra uma loja. Peça a chave no Telegram com /chaveapi: o link chega por e-mail e abre a chave uma vez só. Uma chave nova substitui a antiga na hora. O segredo do webhook vem junto com a primeira chave.

3. Criar cobrança

POST https://api.pay.p2p.app.br/v1/charges

Authorization: Bearer dpk_…
Content-Type: application/json
Idempotency-Key: <opcional, 1–200 caracteres sem espaço>

Body

Aliases camelCase que funcionam, e só estes: amountInCents, endUserTaxNumber, endUserFullName, tenantId, storeId. notifyUrl, returnUrl e linkTtlSecs são ignorados — mandar notifyUrl no lugar de notify_url não cadastra webhook. Campos de carteira/taxa (splitFee etc.) são proibidos e retornam 400. metadata livre: ainda não disponível (ignorado).

Exemplo: body do POST

{
  "amount_in_cents": 19700,
  "end_user_tax_number": "12345678909",
  "end_user_full_name": "Maria Silva",
  "euid": "pagador-42",
  "notify_url": "https://www.sua-loja.com/api/webhooks/depix",
  "reference": "pedido-123",
  "description": "Camiseta",
  "link_ttl_secs": 1200,
  "return_url": "https://www.sua-loja.com/pedido/123",
  "auto_redirect": false,
  "store_id": "10001",
  "tenant_id": "p2papp"
}

amount_in_cents também pode ir como "19700". Os campos opcionais podem ser omitidos. Não mande notifyUrl nem linkTtlSecs.

Resposta de sucesso (201) com QR

{
  "id": "chg_…",
  "status": "awaiting_payment",
  "tenant_id": "p2papp",
  "pay_url": "https://pay.p2p.app.br/pay/…",
  "qr_copy_paste": "00020126…6304ABCD",
  "amount_in_cents": 19700,
  "reference": "pedido-123",
  "description": "Camiseta",
  "expiration": "2026-10-06T14:38:39-03:00"
}

• Use qr_copy_paste para o QR e o botão “copiar”.
• expiration é o texto do emissor, sem conversão. Pode ser null, um instante em Z (2026-10-05T17:40:00Z) ou com fuso (2026-10-06T14:38:39-03:00). Quando vier null, o Pix vale link_ttl_secs, ou 1200 segundos se o cliente não mandou esse campo.
• reference e description só aparecem quando foram enviados. expiration sempre vem, mesmo null.
• issuance_error entra na cobrança (criar e GET) enquanto não há QR. Some quando o QR existe. Pode ser rate_limited, unavailable, identification_required, verifying, in_progress, failed, ou o mesmo código de um 422 que recusou o depósito.
• pay_url é a página hosted. Não monte essa URL na mão.
• qr_image_url (imagem pronta): ainda não disponível.

Resposta 201 creating_deposit (sem QR)

Acima de R$ 10,00 sem CPF/CNPJ e sem euid. Não há qr_copy_paste nem issuance_error.

{
  "id": "chg_…",
  "status": "creating_deposit",
  "tenant_id": "p2papp",
  "pay_url": "https://pay.p2p.app.br/pay/…",
  "amount_in_cents": 19700,
  "reference": "pedido-123",
  "description": "Camiseta",
  "expiration": null
}

Exemplo: corpo de erro

Limite de emissão. retry_after é segundos. O header Retry-After repete esse número quando ele existe.

{
  "error": "deposit_quota",
  "message": "deposit quota reached; retry later",
  "retry_after": 37,
  "charge": {
    "id": "chg_…",
    "status": "creating_deposit",
    "tenant_id": "p2papp",
    "pay_url": "https://pay.p2p.app.br/pay/…",
    "amount_in_cents": 19700,
    "reference": "pedido-123",
    "description": "Camiseta",
    "expiration": null,
    "issuance_error": "rate_limited"
  }
}

Validação é só error e message, sem charge: {"error":"invalid_amount","message":"amount_in_cents must be an integer between 1 and 10000000"}. GET sem a cobrança: {"error":"not_found"}.

Erros

O header Retry-After não vem sempre. Em deposit_quota e em rate_limited ele vem. Em eulen_rate_limited e em 503 temporarily_unavailable ele só vem quando o emissor mandou um. Em rate_limit_unavailable não vem.

Quando a cobrança chegou a ser gravada, 409/422/429/503 de emissão trazem charge (com id). idempotency_in_progress, rate_limited, payload_too_large e a validação 400 não trazem.

Idempotency-Key: repetir a mesma chave devolve a mesma resposta da primeira vez (mesmo status e corpo, inclusive um 429), sem prazo e sem comparar o body. Use uma chave por tentativa. O status atual sempre se lê no GET.

Exemplo: Next.js (App Router)

// app/api/pix/charge/route.ts
export const runtime = "nodejs";
const BASE = "https://api.pay.p2p.app.br";

export async function POST(req: Request) {
  const { orderId } = await req.json();
  const order = await loadOrder(orderId); // valor, nome, CPF — no servidor
  if (!order || order.status === "paid") {
    return Response.json({ error: "invalid_order" }, { status: 400 });
  }

  const res = await fetch(`${BASE}/v1/charges`, {
    method: "POST",
    cache: "no-store",
    headers: {
      Authorization: `Bearer ${process.env.DEPIX_API_KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": `${order.id}-pix-${order.pixAttempt}`,
    },
    body: JSON.stringify({
      amount_in_cents: order.amountInCents,
      end_user_full_name: order.buyerName,
      end_user_tax_number: order.buyerTaxNumber,
      reference: order.id,
      description: String(order.productName || "").slice(0, 200),
      notify_url: "https://www.sua-loja.com/api/webhooks/depix",
    }),
  });
  const data = await res.json().catch(() => ({}));
  if (data?.id) await saveChargeOnOrder(order.id, data.id, data.status);

  if (res.status === 201 && data.qr_copy_paste) {
    return Response.json({
      status: "awaiting_payment",
      qr: data.qr_copy_paste,
      expiration: data.expiration,
    });
  }
  if (res.status === 201 && data.status === "creating_deposit") {
    return Response.json({ status: "error", error: "tax_number_required" }, { status: 422 });
  }
  if (res.status === 409) return Response.json({ status: "verifying" }, { status: 202 });
  if (res.status === 429 || res.status === 503) {
    return Response.json({
      status: "retry",
      retryAfter: Number(res.headers.get("Retry-After") ?? 30),
    }, { status: 503 });
  }
  return Response.json({ status: "error", error: data.error ?? "unknown" }, { status: 502 });
}

Desenhar o QR no front

import QRCode from "qrcode"; // npm i qrcode

const dataUrl = await QRCode.toDataURL(qr, {
  margin: 1,
  width: 280,
  errorCorrectionLevel: "M",
});
// <img src={dataUrl} alt="QR Code Pix" />
// botão copiar: navigator.clipboard.writeText(qr)

4. Consultar status e a loja

GET https://api.pay.p2p.app.br/v1/charges/{id} — mesmo auth. Mesmo formato da criação, com pay_url quando o link ainda pode ser aberto. qr_copy_paste só vem enquanto awaiting_payment. issuance_error só vem enquanto não há QR. Depois do pagamento podem vir também payer_name_masked, payer_tax_masked, pix_message, late, dispute, bank_review, review_reason. Cobrança inexistente ou de outra loja: 404 {"error":"not_found"}.

Exemplo: GET depois do pagamento

{
  "id": "chg_…",
  "status": "paid",
  "tenant_id": "p2papp",
  "pay_url": "https://pay.p2p.app.br/pay/…",
  "amount_in_cents": 19700,
  "reference": "pedido-123",
  "description": "Camiseta",
  "expiration": "2026-10-06T14:38:39-03:00",
  "payer_name_masked": "Maria S.",
  "payer_tax_masked": "***.***.***-09",
  "pix_message": "pedido 42"
}

late, dispute (open ou refunded), bank_review e review_reason só entram quando existem. Não há qr_copy_paste depois de awaiting_payment.

GET /v1/charges lista as 50 mais recentes da loja. Paginação e busca por reference: ainda não disponíveis. Cada item é a cobrança mais created_at, sem pay_url e sem os campos do pagador. qr_copy_paste só no item awaiting_payment.

Exemplo: lista

{
  "charges": [
    {
      "id": "chg_…",
      "status": "paid",
      "tenant_id": "p2papp",
      "amount_in_cents": 19700,
      "reference": "pedido-123",
      "description": "Camiseta",
      "expiration": "2026-10-06T14:38:39-03:00",
      "created_at": "2026-10-06T17:18:39.000Z"
    }
  ]
}

GET /v1/store

GET https://api.pay.p2p.app.br/v1/store — chave da loja (dpk_). Devolve a loja da chave, sem segredo. Chave que não é de loja: 403 store_key_required. Loja inativa: 403 store_not_active.

{
  "store_id": "10001",
  "tenant_id": "p2papp",
  "status": "active",
  "destination_address": "lq1qq…",
  "merchant_euid": "EU01STORE",
  "split": {
    "address": "lq1qq…",
    "fee": "2.50%"
  }
}

store_id é o id da loja na chave. split é null quando o endereço ou a taxa do parceiro não está disponível.

5. Estados

• held também é o status de under_review, pending_pix2fa e delayed. Esses três não mandam webhook. charge.held só sai em under_bank_review (aí o GET pode trazer bank_review: true).
• canceled também não manda webhook. Confirme pelo GET.
• paid não volta atrás, mas refunded pode chegar depois (MED/estorno Pix).
• Pagamento tardio: uma cobrança expired/failed/canceled pode virar paid com late: true.
• Não espere o expired para trocar a tela: quando o seu timer zerar, ofereça novo Pix e continue aceitando um paid eventual da anterior.

6. Valores, prazos e limites

• Por cobrança: R$ 0,01 a R$ 100.000,00. Acima de R$ 10,00, CPF/CNPJ é obrigatório para gerar o QR, salvo com euid.
• Validade do Pix: padrão 20 min (1200 s) quando o cliente não manda link_ttl_secs. O campo, se vier, é inteiro de 20 min a 24 h.
• Emissão de Pix, por minuto: 2 por cobrança, 4 por loja, 4 por IP do servidor, 6 por rede (IPv4 /24 ou IPv6 /64), 8 nas chamadas com chave de API e 12 no total. Em picos espere 429 deposit_quota. Avise a DePix antes de lançamentos grandes.
• Consulta de limites diários do emissor: ainda não disponível.
• Taxa: definida no contrato comercial. O POST da cobrança não aceita taxa. GET /v1/store devolve a taxa vigente em split.fee.
• Estorno/cancelamento pela API: ainda não disponíveis. refunded aparece quando o banco do pagador estorna (MED).

7. Webhook (confirmação)

POST no seu notify_url, body JSON igual ao GET (sem pay_url), mais bank_tx_id e blockchain_tx_id quando existirem.

Exemplo: webhook charge.paid

{
  "id": "chg_…",
  "status": "paid",
  "tenant_id": "p2papp",
  "amount_in_cents": 19700,
  "reference": "pedido-123",
  "description": "Camiseta",
  "expiration": "2026-10-06T14:38:39-03:00",
  "bank_tx_id": "E123456789",
  "blockchain_tx_id": "abc123txid",
  "payer_name_masked": "Maria S.",
  "payer_tax_masked": "***.***.***-09",
  "pix_message": "pedido 42"
}

bank_tx_id e blockchain_tx_id só entram quando o emissor os mandou. O mesmo vale para os campos do pagador, late, dispute, bank_review e review_reason. Campo ausente não vem como null — a exceção é expiration.

Content-Type: application/json
X-DePix-Event: charge.paid
X-DePix-Signature: sha256=<hex>
webhook-id: msg_…
webhook-timestamp: 1759689600
webhook-signature: v1,<base64>

O tipo do evento vem só no header X-DePix-Event (não está no body).

Eventos

Não existe charge.canceled. canceled não manda webhook.

Assinatura (como o gateway calcula hoje)

• X-DePix-Signature = "sha256=" + hex(HMAC_SHA256(chave = "whsec_…" como texto, mensagem = body cru))
• webhook-signature = "v1," + base64(HMAC_SHA256(chave = "whsec_…" como texto, mensagem = webhook-id + "." + webhook-timestamp + "." + body cru))
• O webhook-timestamp (unix, segundos) é renovado a cada tentativa. O webhook-id é o mesmo nas retentativas.
• Não use as libs standardwebhooks/svix: elas decodificam o secret em base64; aqui o secret é texto.
• O gateway não impõe janela de tempo. Recomendamos rejeitar timestamp com mais de 5 min de diferença.

Vetor de teste:

secret            = whsec_test_vector
webhook-id        = msg_test
webhook-timestamp = 1700000000
body              = {"id":"chg_test","status":"paid"}
X-DePix-Signature = sha256=128e4cf4b6f6928089d4c2c2b2e9c7abd25b48a728c4ade4ae0f24aa6659b00f
webhook-signature = v1,MWwyPUIfY/+8WVxw36RnDrqTv8IJuGvC8D8DjN14gNs=

Entregas

• Sucesso = resposta 2xx. Redirect (3xx), 4xx, 5xx e timeout contam como falha.
• Cadastre o host final (sem redirect www/apex, sem barra final que redirecione).
• No máximo 5 tentativas num intervalo curto (~7–8 min). Depois a entrega é abandonada. Reenvio manual: ainda não disponível.
• Trate duplicatas. Mantenha um job de reconciliação via GET para pedidos aguardando Pix.

Exemplo: verificar no Node / Next.js

// app/api/webhooks/depix/route.ts
import crypto from "node:crypto";
export const runtime = "nodejs";
export const dynamic = "force-dynamic";

const TOLERANCE_SEC = 300;

function safeEqual(a: string, b: string) {
  const x = Buffer.from(a, "utf8");
  const y = Buffer.from(b, "utf8");
  return x.length === y.length && crypto.timingSafeEqual(x, y);
}

function verify(rawBody: string, h: Headers, secret: string): boolean {
  const legacy = h.get("x-depix-signature") ?? "";
  const id = h.get("webhook-id") ?? "";
  const ts = h.get("webhook-timestamp") ?? "";
  const sig = h.get("webhook-signature") ?? "";

  const expectedLegacy =
    "sha256=" +
    crypto.createHmac("sha256", secret).update(rawBody, "utf8").digest("hex");
  if (!safeEqual(legacy, expectedLegacy)) return false;

  const t = Number(ts);
  if (!id || !Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > TOLERANCE_SEC) {
    return false;
  }
  const expectedStd =
    "v1," +
    crypto
      .createHmac("sha256", secret)
      .update(`${id}.${ts}.${rawBody}`, "utf8")
      .digest("base64");
  return safeEqual(sig, expectedStd);
}

export async function POST(req: Request) {
  const raw = await req.text(); // body CRU — não use req.json() antes
  const secrets = [
    process.env.DEPIX_WEBHOOK_SECRET,
    process.env.DEPIX_WEBHOOK_SECRET_PREVIOUS,
  ].filter(Boolean) as string[];
  if (!secrets.some((s) => verify(raw, req.headers, s))) {
    return new Response("invalid signature", { status: 401 });
  }

  const event = req.headers.get("x-depix-event") ?? "";
  const body = JSON.parse(raw) as {
    id: string;
    status: string;
    amount_in_cents: number;
    reference?: string;
  };

  // Idempotência: UNIQUE (charge_id, event). Se já existe, 200.
  const firstTime = await recordWebhookOnce(body.id, event, req.headers.get("webhook-id"));
  if (!firstTime) return new Response("ok", { status: 200 });

  if (event === "charge.paid") {
    // Reconsulte GET /v1/charges/:id e confira valor/pedido antes de liberar
    await markOrderPaid(body.id);
  } else if (event === "charge.refunded") {
    await markOrderRefunded(body.id);
  }
  return new Response("ok", { status: 200 });
}

Responda rápido (< 10 s). E-mail e outros efeitos vão para fila/job.

8. Página hosted (alternativa)

O campo pay_url aponta para https://pay.p2p.app.br/pay/{token}. O comprador vê o QR (ou o formulário de CPF quando a cobrança foi criada sem identificação acima de R$ 10). Use quando preferir redirect em vez de embutir o QR.

• O token é opaco e não é o id da cobrança. Não monte a URL.
• return_url no create habilita o link “Voltar à loja” após paid.
• Confirmação do pagamento continua sendo o webhook / GET — a página hosted não substitui isso.

9. Ainda não disponível

Não implemente contando com:

• Sandbox / chaves de teste (toda cobrança é Pix real)
• Imagem pronta do QR (qr_image_url)
• Estorno ou cancelamento de cobrança pela API
• Reenvio manual de webhook / painel de entregas para o lojista
• Informar CPF pela API depois de criar a cobrança; regerar Pix na mesma cobrança
• Campo metadata livre; busca por reference; paginação da lista
• Cartão e boleto (DePix Pay é só Pix)
• Chamada direta do navegador (CORS) / SDK / iframe / embed