API Pix2DePix para comerciantes

Gere cobranças Pix na sua plataforma e receba DePix — a stablecoin de real na Liquid Network — direto na sua carteira.

seu cliente  ──Pix──►  Pix2DePix  ──DePix──►  sua carteira Liquid

Comece por aqui


Quickstart	Da chave à primeira cobrança paga, em menos de 10 minutos.
Referência	Todos os endpoints, campos e respostas.
Status da cobrança	O que cada estado significa e o que fazer nele.
Webhooks	Avisos no seu servidor, com validação de assinatura.
Erros	Todos os códigos e o que repetir.
Boas práticas	O que separa uma integração que aguenta produção.
Exemplos	cURL, Node, Python e PHP, executáveis.

O que você precisa saber antes de tudo

1. Existe um atraso entre o Pix ser pago e o DePix chegar. Toda cobrança passa por uma retenção antifraude de 24h. Nesse intervalo ela fica em paid_pending_settlement: o dinheiro saiu do banco do seu cliente, mas ainda não chegou na sua carteira.

Libere produto em settled, não em paid_pending_settlement. Se o seu negócio não tolera essa espera, fale com a gente antes de integrar.

2. Valores são sempre inteiros, em centavos. R$ 250,00 é 25000. Não existe ponto flutuante em lugar nenhum desta API — é assim que centavo não some.

3. Você precisa do CPF ou CNPJ de quem vai pagar. É exigência do provedor de Pix para identificar o pagador, e não há caminho alternativo.

Ambientes

São duas chaves diferentes, e a chave é o que escolhe o ambiente — não há URL separada nem cabeçalho extra.

	Chave	O que acontece
Produção	`p2d_live_…`	Cobrança de verdade, QR pagável, dinheiro real.
Sandbox	`p2d_test_…`	Nenhum Pix é criado. Você move a cobrança com `POST /v1/test/charges/{id}/advance` e exercita o ciclo inteiro, webhooks inclusive.

Uma chave p2d_test_ colada em produção por engano falha como credencial inválida — ela não cobra nada.

Autenticação

Authorization: Bearer p2d_live_a1b2c3d4e5f6a7b8c9d0e1f2_SEU-SEGREDO

Gere o par no painel, em API. O segredo aparece uma única vez: guarde no servidor, num cofre de variáveis de ambiente. Se perder, revogue e gere outro — não temos como reexibi-lo.

Chave de API é segredo de servidor. Nunca no navegador, nunca num app mobile, nunca num repositório.
Você pode ter várias chaves ativas ao mesmo tempo e revogar uma sem tocar nas outras. É assim que se troca de chave sem parar a loja: crie a nova, publique, confirme que rodou, revogue a velha.
O painel mostra a data do último uso de cada chave — é como você descobre qual pode ser revogada em paz.
Revogar para a chave na hora e a deixa na lista, marcada. Depois de revogada ela pode ser removida de vez, e aí some — as cobranças que ela criou continuam lá, mas deixam de apontar para qual chave foi.

Limite de requisições

120 por minuto, por chave. Ao passar disso a resposta é 429 com o cabeçalho Retry-After dizendo quantos segundos esperar. Toda resposta traz também:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 118
X-RateLimit-Reset: 1787975820

Precisa de mais? Fale com a gente antes de aumentar o volume.

Taxas

A taxa é a do seu plano assinado — a mesma da tela de cobrança do painel — e vem aberta em toda resposta:

"amount": {
  "grossInCents": 25000,
  "feeBps": 199,
  "feeFixedInCents": 99,
  "feeInCents": 597,
  "netInCents": 24403
}

feeBps é o percentual do plano em pontos-base (199 = 1,99%) e feeFixedInCents é a parcela fixa por depósito. Consulte GET /v1/account para ver a taxa vigente — não guarde percentual no seu código, porque ele muda quando você troca de plano.