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://api.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.

Parâmetro	Onde	Obrigatório	Descrição
`externalId`	query	não	O id do pedido no seu sistema.
`status`	query	não
`createdAfter`	query	não
`createdBefore`	query	não
`startingAfter`	query	não	`id` da última cobrança da página anterior.
`limit`	query	não

Respostas

Código	Significa
200	Uma página de cobranças
400	Parâmetro inválido
401	Chave ausente, inválida ou revogada
429	Limite atingido

`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.

Parâmetro	Onde	Obrigatório	Descrição
`Idempotency-Key`	header	não	Retry seguro de rede. Se a resposta se perder, repita a requisição com a mesma chave: você recebe a cobrança original em vez de uma segunda.

Corpo

Campo	Tipo	Obrigatório	Descrição
`amountInCents`	`integer`	sim	Valor bruto em centavos. Mínimo 1000 (R$ 10,00), máximo 500000 (R$ 5.000,00).
`payerTaxNumber`	`string`	sim	CPF ou CNPJ de quem vai pagar. Com ou sem pontuação. Obrigatório: é o provedor de Pix que exige, para identificar o pagador.
`payerName`	`string`	não	Nome de quem vai pagar. Não é conferido — depois do pagamento devolvemos o nome que o banco informou.
`externalId`	`string`	não	O id do pedido no seu sistema. Opcional, mas é o que torna a criação idempotente: o mesmo valor nunca vira duas cobranças.
`description`	`string`	não	Some na resposta e nos eventos. Não vai para o extrato do pagador.
`metadata`	`object`	não	Pares livres, devolvidos em toda resposta e em todo evento.

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

Respostas

Código	Significa
200	Cobrança já existia com este externalId e o mesmo corpo
201	Cobrança criada
400	Corpo inválido (`invalid_request`)
401	Chave ausente, inválida ou revogada
402	O provedor de Pix recusou (`provider_error`)
403	Conta não liberada para cobrar (`merchant_not_activated`, `charge_blocked`, `missing_merchant_id`)
409	`external_id_conflict` (mesmo externalId, corpo diferente), `idempotency_key_conflict` ou `charge_processing` (a original ainda está sendo criada — repita em 1s)
429	Limite por chave atingido (`rate_limited`)

`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.

Parâmetro	Onde	Obrigatório	Descrição
`id`	path	sim	O `id` que devolvemos na criação.

Respostas

Código	Significa
200	A cobrança
401	Chave ausente, inválida ou revogada
404	Não existe nesta conta e neste ambiente (`charge_not_found`)
429	Limite atingido

`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.

Parâmetro	Onde	Obrigatório	Descrição
`id`	path	sim

Respostas

Código	Significa
200	Cobrança cancelada
401	Chave ausente, inválida ou revogada
404	Não encontrada
409	Já paga, expirada ou cancelada (`charge_not_cancelable`)
429	Limite atingido

`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

Código	Significa
200	A conta
401	Chave ausente, inválida ou revogada

`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

Código	Significa
202	Evento enfileirado
401	Chave ausente, inválida ou revogada
404	Nenhuma URL de webhook configurada para este ambiente

`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.

Parâmetro	Onde	Obrigatório	Descrição
`id`	path	sim

Corpo

Campo	Tipo	Obrigatório	Descrição
`status`	`paid_pending_settlement` \| `settled` \| `expired` \| `refunded`	sim

{
  "status": "paid_pending_settlement"
}

Respostas

Código	Significa
200	A cobrança no novo estado
401	Chave ausente, inválida ou revogada
403	Chamada com chave de produção (`not_available_in_live`)
404	Não encontrada
409	A cobrança não pode ir para esse estado (`invalid_transition`)

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.

Parâmetro	Onde	Obrigatório	Descrição
`X-P2D-Event-Id`	header	sim	Id do evento. É por ele que você deduplica.
`X-P2D-Event-Type`	header	sim
`X-P2D-Timestamp`	header	sim	Epoch em segundos. Recuse o que estiver a mais de 300s do seu relógio.
`X-P2D-Signature`	header	sim	`v1=` + HMAC-SHA256 de `<timestamp>.<corpo bruto>` com o segredo do webhook, em hex.

Corpo

Campo	Tipo	Obrigatório	Descrição
`id`	`string`	sim	Imutável. Deduplique por ele.
`type`	`charge.awaiting_payment` \| `charge.paid_pending_settlement` \| `charge.settled` \| `charge.expired` \| `charge.canceled` \| `charge.failed` \| `charge.refunded` \| `charge.test`	sim
`createdAt`	`string`	sim
`environment`	`live` \| `test`	sim
`data`	`object`	sim

Respostas

Código	Significa
200	Recebido. Qualquer 2xx serve.

Objetos

CriarCobranca

Campo	Tipo	Obrigatório	Descrição
`amountInCents`	`integer`	sim	Valor bruto em centavos. Mínimo 1000 (R$ 10,00), máximo 500000 (R$ 5.000,00).
`payerTaxNumber`	`string`	sim	CPF ou CNPJ de quem vai pagar. Com ou sem pontuação. Obrigatório: é o provedor de Pix que exige, para identificar o pagador.
`payerName`	`string`	não	Nome de quem vai pagar. Não é conferido — depois do pagamento devolvemos o nome que o banco informou.
`externalId`	`string`	não	O id do pedido no seu sistema. Opcional, mas é o que torna a criação idempotente: o mesmo valor nunca vira duas cobranças.
`description`	`string`	não	Some na resposta e nos eventos. Não vai para o extrato do pagador.
`metadata`	`object`	não	Pares livres, devolvidos em toda resposta e em todo evento.

Cobranca

Campo	Tipo	Obrigatório	Descrição
`id`	`string`	sim	Nosso id. 24 caracteres hexadecimais.
`externalId`	`string`	não
`status`	`created` \| `awaiting_payment` \| `paid_pending_settlement` \| `settled` \| `expired` \| `canceled` \| `failed` \| `refunded`	sim	Veja a tabela de status.
`environment`	`live` \| `test`	sim
`amount`	Valores	sim	A taxa é uma parcela fixa por depósito mais um percentual do seu plano.
`pix`	Pix	sim
`settlement`	Liquidacao	sim	O caminho do dinheiro depois do pagamento.
`payer`	`object`	sim
`description`	`string`	não
`metadata`	`object`	não
`createdAt`	`string`	sim
`updatedAt`	`string`	sim

Valores

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

Campo	Tipo	Obrigatório	Descrição
`grossInCents`	`integer`	sim	O que o seu cliente paga no Pix.
`feeBps`	`integer`	sim	Percentual do plano em pontos-base. 199 = 1,99%.
`feeFixedInCents`	`integer`	sim	Parcela fixa por depósito.
`feeInCents`	`integer`	sim	Fixa + percentual.
`netInCents`	`integer`	sim	O que chega em DePix na sua carteira.

Pix

Campo	Tipo	Obrigatório	Descrição
`qrCode`	`string`	não	Copia-e-cola. É isto que vira QR Code na sua tela.
`qrCodeImageUrl`	`string`	não	Imagem pronta do QR. Pode não vir — gere o QR do `qrCode` se preferir.
`expiresAt`	`string`	não	Passou disso, a cobrança vira `expired`.

Liquidacao

O caminho do dinheiro depois do pagamento.

Campo	Tipo	Obrigatório	Descrição
`delayHours`	`integer`	não	Retenção antifraude entre o Pix pago e o DePix liquidado.
`estimatedAt`	`string`	não	Quando o DePix deve sair. Só existe depois do pagamento — é a data que você mostra ao seu cliente.
`paidAt`	`string`	não
`settledAt`	`string`	não
`blockchainTxId`	`string`	não	Comprovante on-chain na Liquid. Só depois de `settled`.

ListaDeCobrancas

Campo	Tipo	Obrigatório	Descrição
`data`	Cobranca[]	sim
`hasMore`	`boolean`	sim	Se `true`, peça a próxima página com `startingAfter` no `id` do último item.

Conta

Campo	Tipo	Obrigatório	Descrição
`merchantId`	`string`	sim	Seu identificador no provedor de Pix.
`email`	`string`	sim
`environment`	`live` \| `test`	sim	O ambiente da chave que você usou.
`plan`	`object`	sim
`feeFixedInCents`	`integer`	sim	Parcela fixa por depósito.
`limits`	`object`	sim
`settlementDelayHours`	`integer`	sim	Retenção antifraude aplicada às cobranças.
`webhook`	`object`	não

Evento

Campo	Tipo	Obrigatório	Descrição
`id`	`string`	sim	Imutável. Deduplique por ele.
`type`	`charge.awaiting_payment` \| `charge.paid_pending_settlement` \| `charge.settled` \| `charge.expired` \| `charge.canceled` \| `charge.failed` \| `charge.refunded` \| `charge.test`	sim
`createdAt`	`string`	sim
`environment`	`live` \| `test`	sim
`data`	`object`	sim

Erro

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

Campo	Tipo	Obrigatório	Descrição
`error`	`object`	sim