Integração com a API

Guia para implementar recebimento de pagamentos Pix via API

Criar Pagamento

Cria um pagamento vinculado a um POS específico.

Endpoint

POST /merchants/pos/{posId}/payments

URL completa:

https://api.pix2depix.com/merchants/pos/{posId}/payments

Substitua {posId} pelo ID do seu ponto de venda.

Body da Requisição

{
  "value": 10,
  "cpfCnpj": "44648338022",
  "externalId": "123"
}

Campos

Campo	Tipo	Obrigatório	Descrição
value	number	Sim	Valor do pagamento em reais. Mínimo: R$ 10,00
cpfCnpj	string	Não	CPF ou CNPJ do pagador
externalId	string	Não	Identificador do pagamento no seu sistema

Valor mínimo

O valor mínimo permitido por pagamento é: R$ 10,00

Resposta de Sucesso (200 OK)

{
  "transactionId": "trx_123456",
  "response": {
    "id": "pay_abc123",
    "qrCopyPaste": "000201010212...",
    "qrImageUrl": "https://api.pix2depix.com/qrcodes/pay_abc123.png"
  },
  "async": false
}

Campos da Resposta

Campo	Tipo	Descrição
transactionId	string	Identificador interno da transação
response.id	string	ID do pagamento gerado
response.qrCopyPaste	string	Código Pix copia e cola
response.qrImageUrl	string	URL da imagem do QR Code
async	boolean	Indica se o processamento foi assíncrono

Campo async

Valor	Significado
false	Pagamento criado e QR Code disponível imediatamente
true	Pagamento está sendo processado de forma assíncrona

Se async = true, recomenda-se acompanhar via webhook.

Exemplo em cURL

curl -X POST https://api.pix2depix.com/merchants/pos/abc123/payments \
  -H "Content-Type: application/json" \
  -d '{
        "value": 10,
        "cpfCnpj": "44648338022",
        "externalId": "123"
      }'

Webhook (Confirmação de Pagamento)

Após a confirmação do pagamento, será enviado um webhook para a URL cadastrada no POS.

Exemplo de payload:

{
  "status": "under_review",
  "bankTxId": "fitbank_E182...",
  "valueInCents": 1000,
  "payerName": "Nome do pagador",
  "transactionId": "698...",
  "externalId": ""
}

Campos da Resposta

Campo	Tipo	Descrição
status	string	Status atual do pagamento (veja tabela abaixo)
bankTxId	string	ID da transação no banco
valueInCents	number	Valor do pagamento em centavos
payerName	string	Nome do pagador
transactionId	string	ID interno da transação
externalId	string	Identificador que você enviou na criação do pagamento

Status retornados

Status	Descrição
under_review	O pagamento foi recebido do usuário final, mas está sob revisão por nossa equipe. Se este status demorar muito, por favor nos avise.
depix_sent	Significa que recebemos o pagamento via PIX do usuário final, aprovamos e enviamos o DePix para o parceiro ou endereço especificado. Provavelmente esse é o status que mais te interessa e que você deve monitorar.
refunded	Significa que o valor foi reembolsado ao usuário que fez o depósito, provavelmente através de um mecanismo especial de estorno (MED).
cancelled	O pagamento foi cancelado pelo usuário final, por nosso parceiro ou por nossa equipe. Por favor, contate nossa equipe para mais detalhes sobre o ocorrido.

Códigos de Erro

Código	Descrição
400	Requisição inválida
401	Token inválido ou ausente
404	POS não encontrado
422	Valor abaixo do mínimo permitido
500	Erro interno

Limites

Limites de valor aplicados aos pagamentos por CPF/CNPJ

Regra	Valor
Valor mínimo permitido por pagamento	R$ 10,00
Limite por 24h por CPF/CNPJ	R$ 6.000
CPF/CNPJ sem histórico de compras: Máximo nas primeiras 24h	R$ 500

Boas Práticas

•Sempre utilize externalId para conciliação.
•Não considere pagamento como concluído apenas pela criação do QR.
•Utilize webhook para confirmação definitiva.