Skip to main content
Esta página é para quem vai emitir cobranças — pelo painel ou por POST /pix. O passo a passo mínimo está no Quickstart; aqui estão as regras que valem sempre.

​
Os dois modos de emitir

Manual: você manda valor, descrição e os dados do pagador. Por produto: você manda product_id e o servidor calcula tudo — o valor é o preço do produto (com coupon_code opcional, mesmas regras do checkout), a descrição padrão é o nome do produto e a validade padrão é 24 h. O pagador vem de customer_id (cliente já cadastrado) ou dos campos inline; com novo_cliente: true, ele também entra no seu cadastro de clientes. success_url e cancel_url (http ou https) definem para onde o checkout leva o pagador depois.

​
Campos e regras

A resposta 201 traz a cobrança inteira: txid (o identificador que você vai usar em tudo), pix_code (copia e cola), qr_code_url (imagem em base64, gerada na hora a partir do código) e status: "pending".

​
Status e ciclo de vida

Uma cobrança pending que passou do expires_at aparece como expirada no checkout e não pode mais ser paga por ali — no banco ela continua pending, então filtre por expires_at ao reconciliar.
POST /pix/cancel e POST /pix/refund existem, mas ainda não executam o cancelamento nem a devolução na origem — respondem 502 explicando. Está dito na página de cada rota.

​
Como saber que foi paga

  • Webhook (recomendado): o evento charge.paid chega no seu endpoint com txid, paid_at e end_to_end_id. Veja Webhooks.
  • Consulta: GET /pix/status?txid=… a qualquer momento.

​
O que o pagador recebe

  • Checkout: toda cobrança tem uma página pública em https://pay.v4companyamaral.com/checkout/{txid} (é a checkout_url do evento charge.created) — QR code, copia e cola e a confirmação sozinha quando o Pix cai.
  • Comprovante: paga, a cobrança ganha um comprovante público em https://pay.v4companyamaral.com/comprovante/{txid}, com o documento do pagador mascarado.
  • E-mail: quando o servidor tem e-mail configurado, o pagador recebe o link do comprovante automaticamente na confirmação. Cobrança de teste não gera e-mail.

​
Emissão bloqueada?

409 com codigo: PRODUCAO_NAO_LIBERADA significa que a conta ainda não passou pela aprovação de produção. No modo subconta também existem SUBCONTA_INEXISTENTE e SUBCONTA_NAO_APROVADA — veja Erros e códigos.