Referência da API

Gerada de openapi.json — versão 1.0.0.

Gere cobranças Pix na sua plataforma e receba DePix.

O ponto que muda a sua integração: existe um atraso antifraude entre o Pix ser pago e o DePix ser liquidado. Uma cobrança paga fica em paid_pending_settlement antes de chegar a settled. Libere produto em settled, não em paid_pending_settlement.

Todos os valores são inteiros, em centavos de real.

Base: https://apiv2.pix2depix.com

Autenticação

Authorization: Bearer p2d_live_... em produção, p2d_test_... em sandbox. Gere no painel, em API. O segredo aparece uma única vez.

Endpoints

GET /v1/charges

Lista cobranças

Ordenadas da mais recente para a mais antiga. A paginação é por cursor: passe em startingAfter o id da última cobrança da página anterior.

Respostas

POST /v1/charges

Cria uma cobrança

Devolve o QR Code e o copia-e-cola.

201 quando a cobrança nasce agora. 200 quando o mesmo externalId (ou a mesma Idempotency-Key) já tinha criado esta cobrança com o mesmo corpo — repetir a criação não duplica nada nem vira erro.

Corpo

{
  "amountInCents": 25000,
  "payerTaxNumber": "529.982.247-25",
  "payerName": "Maria Silva",
  "externalId": "pedido-8891",
  "description": "Pedido #8891",
  "metadata": {
    "loja": "sp-01"
  }
}

Respostas

POST /v1/split-charges

Cria uma cobrança com split

Igual a POST /v1/charges, mas o DePix líquido é dividido entre as suas carteiras depois da retenção.

• Taxa: a do seu plano + 1 ponto percentual, cobrada na mesma linha da conversão. A parcela fixa por depósito continua igual.
• Divisão: uma única transação Liquid com uma saída por destino, proporcional aos percentuais, sobre amount.netInCents. A taxa de rede é nossa.
• Quando: logo depois de charge.settled (o DePix chegou à carteira de split). O fim chega em charge.split.completed, com o txId; falha, em charge.split.failed.
• A configuração é imutável. Consulta, listagem e cancelamento são as rotas de sempre (/v1/charges).

201/200 e idempotência funcionam como em POST /v1/charges — o split entra na comparação do corpo.

Guia passo a passo, com taxa, eventos e sandbox: Split de pagamento.

Corpo

{
  "amountInCents": 25000,
  "payerTaxNumber": "529.982.247-25",
  "payerName": "Maria Silva",
  "externalId": "pedido-8891",
  "description": "Pedido #8891",
  "metadata": {
    "loja": "sp-01"
  },
  "split": {
    "destinations": [
      {
        "address": "lq1qqf8er278e6nyvuwtgf39e6ewvdcnjupn9a86rzpx655y5lhkt0walu3djf9cklkxd3ryld97hu8h3xepw7sh2rlu7q45dcew5",
        "percent": 60
      },
      {
        "address": "ex1qw508d6qejxtdg4y5r3zarvary0c5xw7kxw5fx4",
        "percent": 40
      }
    ]
  }
}

Respostas

GET /v1/charges/{id}

Consulta uma cobrança

Confirme por aqui antes de liberar produto. O webhook é o aviso rápido; esta rota é a verdade.

Respostas

POST /v1/charges/{id}/cancel

Cancela uma cobrança não paga

Só antes do pagamento.

⚠️ O QR Code continua tecnicamente pagável depois do cancelamento: nosso provedor de Pix não tem como invalidá-lo. Se o Pix cair mesmo assim, o pagamento vence e a cobrança volta a andar — você recebe charge.paid_pending_settlement como em qualquer outra. Tire o QR da frente do seu cliente ao cancelar.

Respostas

GET /v1/account

Dados do comerciante, plano e taxa vigente

A taxa vem do seu plano assinado. Se você trocar de plano, ela muda aqui e nas cobranças novas — não guarde percentual no seu código.

Respostas

POST /v1/webhooks/test

Dispara um evento de teste

Manda um charge.test para a URL configurada no painel, assinado igual a um evento de verdade. Serve para validar o seu código de conferência de assinatura.

Respostas

POST /v1/test/charges/{id}/advance

Empurra uma cobrança de teste para o estado pedido

Existe só com chave p2d_test_. É como você exercita a espera da liquidação e os webhooks sem um Pix de verdade. As transições respeitam a mesma máquina de estados da produção: voltar atrás é 409 invalid_transition.

Corpo

{
  "status": "paid_pending_settlement"
}

Respostas

GET /v1/withdrawals

Lista saques

Ordenados do mais recente para o mais antigo. A paginação é por cursor: passe em startingAfter o id do último saque da página anterior.

Respostas

POST /v1/withdrawals

Cria um saque

O caminho inverso da cobrança: você manda DePix e recebe Pix na chave informada.

• Valor: informe amountInCents (o Pix que quer receber, taxa por fora) ou depixAmountInCents (o DePix que vai enviar, taxa por dentro) — nunca os dois.
• Taxa: R$ 3,00 fixos abaixo de R$ 100,00 de Pix; percentual daí para cima. A resposta traz os três números abertos em amount.
• Sua taxa (opcional): merchantFeeBps cobra de quem saca uma taxa sua, que vai em DePix para o seu endereço padrão na mesma transação do repasse. Ex.: 1.000 DePix com 3% nossos e merchantFeeBps: 100 → R$ 960,00 no Pix. Para mostrar o valor antes, use GET /v1/withdrawals/quote.
• Depois de criar: envie exatamente deposit.amountInCents de DePix para deposit.address, na Liquid. O endereço é só deste saque — não o reaproveite.
• Quando o Pix sai: assim que o depósito confirma na rede, o saque vai para processing e o Pix é pago em seguida (withdrawal.paid, com o endToEndId).

Não há rota de cancelamento: um saque sem depósito não custa nada e morre parado.

Guia passo a passo, com taxa, eventos e sandbox: Saque.

Corpo

{
  "amountInCents": 100000,
  "pixKeyType": "aleatoria",
  "pixKey": "6a4f5c1e-8b2d-4a7f-9c3e-1d2b3a4c5d6e",
  "payeeTaxNumber": "529.982.247-25",
  "externalId": "saque-77"
}

Respostas

GET /v1/withdrawals/quote

Cota um saque

Os valores que o saque teria, sem criar nada. É o número para mostrar a quem saca antes de confirmar: a conta é a mesma da criação, então o saque criado com os mesmos parâmetros sai com os mesmos valores.

Informe exatamente um de amountInCents (Pix que quer receber) ou depixAmountInCents (DePix que vai enviar). merchantFeeBps é a sua taxa, como na criação; aqui não exige endereço padrão.

Respostas

GET /v1/withdrawals/{id}

Consulta um saque

O estado de agora. Enquanto o DePix não chega, o saque fica em awaiting_deposit.

Respostas

POST /v1/test/withdrawals/{id}/advance

Empurra um saque de teste para o estado pedido

Existe só com chave p2d_test_. No sandbox ninguém envia DePix: é esta rota que faz o depósito chegar e o Pix cair, para você exercitar withdrawal.processing e withdrawal.paid. Voltar atrás é 409 invalid_transition.

Corpo

{
  "status": "processing"
}

Respostas

Webhook

POST <sua URL>

Evento de cobrança

Enviamos para a URL que você configurou no painel a cada mudança de estado.

A entrega é at-least-once: o mesmo evento pode chegar mais de uma vez. Deduplique pelo campo id.

Responda 2xx rápido. Qualquer outra coisa — inclusive 3xx — conta como falha e entra na fila de retentativa, que insiste por até 24h com espera crescente.

Corpo

Respostas

Objetos

CriarCobranca

Cobranca

Valores

A taxa é uma parcela fixa por depósito mais um percentual do seu plano.

Pix

Liquidacao

O caminho do dinheiro depois do pagamento.

ListaDeCobrancas

Conta

Evento

Erro

O formato é o mesmo em todos os endpoints e em todos os códigos HTTP.

DestinoSplit

CriarCobrancaComSplit

Split

Só em cobranças criadas por POST /v1/split-charges.

CriarSaque

Informe exatamente um dos dois valores: amountInCents (lado do Pix) ou depixAmountInCents (lado do DePix).

ValoresDoSaque

DepositoDoSaque

PixDoSaque

Saque

ListaDeSaques

CotacaoDeSaque

Os valores que o saque teria, sem criar nada.