Cobrança híbrida (boleto + Pix)

Na cobrança híbrida, a mesma cobrança com vencimento tem um QR Pix e um boleto registrado. Quem prefere Pix paga na hora; quem ainda usa boleto (caixa, lotérica, internet banking) paga pela linha digitável. É a mesma cobrança com vencimento, com boleto: true.

Criar

curl -X POST https://api.exemplo.com.br/v1/charges \
  -H "Authorization: Bearer $PIX_API_KEY" -H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/json" \
  -d '{
    "amount": "320.00",
    "due_date": "2026-10-15",
    "boleto": true,
    "description": "Mensalidade outubro",
    "payer": {
      "name": "Carlos Comprador",
      "document": "12345678909",
      "address": { "street": "Rua das Flores", "number": "100", "district": "Centro",
                   "city": "São Paulo", "state": "SP", "zip": "01001000" }
    }
  }'

• Exige due_date e o endereço do pagador (payer.address): o banco exige endereço no registro do boleto.
• Multa, juros, desconto e abatimento valem como na cobrança com vencimento.
• A resposta traz boleto.digitable_line (47 dígitos) e boleto.barcode (44), além do br_code do Pix. A página de pagamento (checkout_url) mostra os dois, com o código de barras desenhado.

Pagamento

O cliente pagou…	O que acontece
Pelo Pix	charge.paid na hora; o boleto é baixado no banco e deixa de valer.
Pelo boleto	charge.paid quando o banco confirma a liquidação (o boleto pode levar até 3 dias úteis para compensar); o QR deixa de valer. O pagamento vem com method: "boleto" e e2e_id: null.
Pelos dois (antes da baixa)	O segundo chega como payment.unmatched (charge_already_paid), sem devolução automática.

Devolução: pagamento por boleto não pode ser devolvido por Pix — a API responde 422 refund-not-supported. Devolva por transferência (TED) pelo seu banco. Pagamento pelo Pix se devolve normalmente (devoluções).

Cancelar a cobrança (POST /v1/charges/{id}/cancel) baixa o boleto também.

Testar no sandbox

Crie a cobrança com a chave sk_sandbox_… e use POST /v1/sandbox/charges/{id}/simulate_payment com {"method": "boleto"} para simular o pagamento pelo boleto (ou sem method, pelo Pix). Veja o sandbox.