Como criar uma cobrança PIX pela API?

Antes de começar, a conta precisa ter a verificação de identidade aprovada e uma chave de API. O caminho básico leva poucos passos.

Passo a passo

1. Envie a criação. Faça POST /api/charges com value em reais e description. Sem paymentMethod, a cobrança é PIX.
2. Guarde os identificadores. O correlationID que você enviar é descartado: a Dotfy gera o identificador e devolve em data.id e data.correlationID. Grave-os junto do seu pedido.
3. Mostre o PIX ao pagador. A resposta traz data.qrCode, o texto do copia e cola, e data.qrCodeImage. Em outros endpoints e nos webhooks, o mesmo texto aparece como brCode. Há também data.paymentLink, uma página pública da cobrança.
4. Espere o webhook. Cadastre um endpoint e assine EVENT:CHARGE_PAID. Esse é o sinal para liberar o produto ou serviço.

Campos úteis

• expiresIn: validade do QR em segundos, de 60 a 86400 (24 horas).
• customer: dados do pagador.
• webhook_url: URL que recebe também as entregas daquela cobrança.

A lista completa está na referência da API.

O que costuma pegar quem integra

• Valor entra em reais e sai em centavos. Enviar 250.00 devolve "value": 25000.
• Sucesso é 200, não 201. Trate toda a faixa 2xx como sucesso.
• 200 nem sempre traz o QR. Se a resposta vier com queued: true e data.status igual a QUEUED, a cobrança existe, mas ainda não tem código. Teste queued antes de exibir o QR e espere o webhook EVENT:CHARGE_CREATED.
• Não há ambiente de teste. Cobranças criadas com qualquer chave são reais.
• Boleto usa o mesmo endereço, com corpo e regras próprios, e depende de liberação da conta.

Para o fluxo completo, siga o Início rápido.