Cobranças

Como emitir uma cobrança Pix, o que cada campo exige, os status possíveis e o que o pagador recebe.

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

Regra	Detalhe
amount em reais, decimal	100 é R$100,00; `49.9` é R$ 49,90
Valor mínimo R$ 5,00	abaixo disso, 400 com codigo: VALOR_MINIMO — vale igual em teste e produção
customer_cpf aceita CPF ou CNPJ	os dígitos verificadores são conferidos; documento inválido é 400 na hora. Pode vir formatado ou só dígitos
expires_at obrigatório no modo manual, e sempre futuro	data no passado é 400 com codigo: EXPIRACAO_INVALIDA (tolerância de 1 minuto para diferença de relógio); no modo produto o padrão é 24 h
expires_at sempre com fuso (Z ou -03:00)	data sem fuso é lida no relógio do servidor — UTC em produção: quem manda 23:59:00 querendo horário de Brasília cria uma cobrança que expira 3 h antes, sem aviso
Obrigatórios no modo manual	amount, description, customer_name, customer_email, customer_cpf, expires_at

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

Status	Como chega nele
pending	acabou de ser emitida
paid	o pagamento foi confirmado (ou simulado, em teste)
canceled	cancelada por você
refunded	devolvida

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.