Quickstart

Da chave à primeira cobrança paga. Tudo no ambiente de teste, sem dinheiro.

1. Gere uma chave de teste — 1 minuto

No painel, em API, escolha a aba Teste, dê um nome à chave e clique em Gerar. Copie o segredo agora: ele não aparece de novo.

export P2D_KEY='p2d_test_a1b2c3d4e5f6a7b8c9d0e1f2_SEU-SEGREDO'
export P2D_URL='https://api.pix2depix.com'

2. Confirme que a chave funciona — 30 segundos

curl -s $P2D_URL/v1/account -H "authorization: Bearer $P2D_KEY"

{
  "merchantId": "EU010563156526920",
  "environment": "test",
  "plan": { "id": "free", "name": "Gratuito", "feeBps": 199 },
  "feeFixedInCents": 99,
  "limits": { "minChargeInCents": 1000, "maxChargeInCents": 500000 },
  "settlementDelayHours": 24
}

environment: "test" confirma que você está no sandbox. Se vier live, pare: a chave é de produção.

3. Crie uma cobrança — 1 minuto

curl -s $P2D_URL/v1/charges \
  -H "authorization: Bearer $P2D_KEY" \
  -H 'content-type: application/json' \
  -d '{
    "amountInCents": 25000,
    "payerTaxNumber": "529.982.247-25",
    "payerName": "Maria Silva",
    "externalId": "pedido-8891"
  }'

{
  "id": "6a92586d486e6a4f3d305214",
  "externalId": "pedido-8891",
  "status": "awaiting_payment",
  "environment": "test",
  "amount": { "grossInCents": 25000, "feeInCents": 597, "netInCents": 24403, "feeBps": 199, "feeFixedInCents": 99 },
  "pix": {
    "qrCode": "PIX2DEPIX-SANDBOX-SEM-VALOR-test_d5088fb3…",
    "expiresAt": "2026-08-29T04:16:29.478Z"
  },
  "settlement": { "delayHours": 24 },
  "payer": { "taxNumber": "•••.982.247-••", "name": "Maria Silva" }
}

Guarde o id — é por ele que você consulta.

export CHARGE_ID='6a92586d486e6a4f3d305214'

externalId é o número do pedido no seu sistema. Mandar ele torna a criação idempotente: se a resposta se perder e você repetir a requisição, recebe a mesma cobrança de volta em vez de criar uma segunda. Sempre mande.

No sandbox o qrCode é propositalmente um texto que não é um Pix. Se ele aparecer numa tela de produção, você vê na hora.

4. Simule o pagamento — 1 minuto

Em produção quem faz isso é o seu cliente, pagando o Pix. No sandbox, é você:

curl -s $P2D_URL/v1/test/charges/$CHARGE_ID/advance \
  -H "authorization: Bearer $P2D_KEY" \
  -H 'content-type: application/json' \
  -d '{"status":"paid_pending_settlement"}'

{
  "status": "paid_pending_settlement",
  "settlement": {
    "delayHours": 24,
    "paidAt": "2026-08-29T03:57:04.856Z",
    "estimatedAt": "2026-08-30T04:27:04.856Z"
  }
}

Este é o estado que muda a sua integração. O Pix foi pago; o DePix ainda não saiu. Em produção a cobrança fica aqui por cerca de 24h, e settlement.estimatedAt é a data que você mostra ao seu cliente.

Não libere o produto ainda.

5. Simule a liquidação — 30 segundos

curl -s $P2D_URL/v1/test/charges/$CHARGE_ID/advance \
  -H "authorization: Bearer $P2D_KEY" \
  -H 'content-type: application/json' \
  -d '{"status":"settled"}'

{
  "status": "settled",
  "settlement": {
    "paidAt": "2026-08-29T03:57:04.856Z",
    "settledAt": "2026-08-29T03:57:07.296Z",
    "blockchainTxId": "0000…"
  }
}

settled é o sinal verde: o DePix está na sua carteira. Agora libere o produto.

6. Configure o webhook — 3 minutos

Consultar a cobrança em laço funciona, mas o webhook avisa na hora.

No painel, em API → aba Teste → Webhook, aponte a URL do seu servidor e salve. O segredo de assinatura aparece uma vez — copie.

export P2D_WEBHOOK_SECRET='whsec_…'

Dispare um evento de teste:

curl -s -X POST $P2D_URL/v1/webhooks/test -H "authorization: Bearer $P2D_KEY"

{ "eventId": "6a9258a6486e6a4f3d30521e" }

Seu servidor deve receber um charge.test. Confira a assinatura antes de confiar no corpo — o guia de webhooks tem o código pronto em Node, Python e PHP.

7. Vá para produção

Troque a chave por uma p2d_live_, configure a URL de webhook na aba Produção (o segredo é outro) e pronto. Nada mais muda: mesma URL base, mesmos endpoints, mesmos campos.

Antes de ligar, passe pelas boas práticas — são cinco minutos que evitam os problemas que aparecem depois da primeira venda.

Exemplos completos