Cobranças
Formas de pagamento, campos da cobrança e ciclo de vida.
Uma cobrança é um valor a receber de um pagador até uma data de vencimento. Ela é criada com
POST /payments e acompanhada pela consulta de cobranças.
Formas de pagamento
O campo billingType define como o pagador paga:
billingType | Como o pagador paga | Link para enviar |
|---|---|---|
PIX | QR Code ou Pix copia-e-cola | checkoutUrl (ou monte sua tela com pix.copyPaste) |
CREDIT_CARD | Cartão de crédito, na página segura do provedor | invoiceUrl |
DEBIT_CARD | Cartão de débito, na página segura do provedor | invoiceUrl |
BOLETO | Boleto bancário | invoiceUrl |
UNDEFINED ou ausente | O pagador escolhe a forma na página de pagamento | invoiceUrl |
Dados de cartão nunca passam pela sua integração
Em cartão, o pagador digita os dados na página do provedor de pagamento, aberta pelo invoiceUrl. Nem o
seu sistema nem a U2D recebem o número do cartão.
Criando uma cobrança
| Campo | Obrigatório | Descrição |
|---|---|---|
payer.name | sim | Nome do pagador |
payer.document | sim | CPF (11) ou CNPJ (14), só dígitos |
payer.email | não | E-mail do pagador |
payer.phone | não | Telefone com DDD, só dígitos |
payer.address | não | Endereço (street, number, district, city, state com a UF, postalCode com 8 dígitos) |
amount | sim | Valor em reais, com ponto decimal (49.90) |
dueDate | sim | Vencimento, AAAA-MM-DD, hoje ou no futuro |
billingType | não | Forma de pagamento (tabela acima) |
description | não | Texto livre, até 500 caracteres |
pixExpiresInMinutes | não | Só com PIX: validade do QR Code em minutos (1 a 43200) |
A especificação completa, com exemplos, está na Referência da API.
Validade do Pix
Sem pixExpiresInMinutes, o QR Code vale 24 horas a partir da criação. Em qualquer caso, a validade
termina no fim do dia do dueDate (horário de Brasília), e o fim dela está em pix.expiresAt. Depois disso o
Pix deixa de ser pagável: crie uma nova cobrança.
Ciclo de vida
O status acompanha a cobrança do início ao fim:
status | Significado |
|---|---|
CREATING | Em criação no provedor. Passa para PENDING em instantes. |
PENDING | Aguardando pagamento. |
OVERDUE | Vencida sem pagamento. |
CONFIRMED | Pagamento confirmado, aguardando a liquidação (comum em cartão). |
RECEIVED | Pago e recebido. |
REFUNDING | Estorno em andamento. |
CHARGEBACK | Contestação aberta pelo pagador no cartão. |
REFUNDED | Estornado. |
CANCELED | Cancelada; não pode mais ser paga (inclui Pix com o QR Code vencido). |
Quando a cobrança é paga, a resposta passa a trazer paidOn (data do pagamento, horário de Brasília),
paidAmount (valor efetivamente pago, que pode diferir de amount por juros, multa ou desconto) e netAmount
(valor líquido, depois das tarifas).
Taxa da U2D
O campo fee traz a taxa da U2D sobre a cobrança, em reais, calculada pelo preço vigente na criação. Ela não
muda se o preço mudar depois.