Ciclo de vida da venda
Entenda cada status da venda, o que leva a venda até ele e qual evento de webhook avisa a mudança.
O problema: a venda muda depois da resposta
Quando você cria uma cobrança, a resposta chega na hora. Mas o pagamento acontece depois: o cliente paga o PIX minutos mais tarde, o boleto vence, o cartão é contestado.
Por isso a venda tem um status (status), que muda com o tempo. Você fica sabendo da mudança pelos webhooks ou consultando GET /sales/{identifier}.
Diagrama de status
O diagrama mostra os caminhos mais comuns de uma venda.
O que cada status significa
| Status | Significado | Evento que avisa | O que fazer |
|---|---|---|---|
DRAFT | A venda foi registrada e a cobrança ainda está sendo criada no gateway. | TRANSACTION_CREATED | Registre a venda. Não libere nada. |
PROCESSING | A cobrança existe no gateway e espera o pagamento. | TRANSACTION_CREATED | Mostre o PIX ou o boleto ao cliente. |
FAILED | O gateway recusou a cobrança, na criação ou depois. Acontece no cartão. | Nenhum evento avisa a recusa. Se ela veio na criação, o TRANSACTION_CREATED já chega com FAILED. Se veio depois, a venda passa para FAILED sem evento: confira em GET /sales/{identifier}. | Peça outro cartão e crie uma nova cobrança. |
PAID | O pagamento foi confirmado. | TRANSACTION_PAID | Libere o que foi vendido. |
EXPIRED | O PIX ou o boleto venceu sem pagamento. | TRANSACTION_EXPIRED | Não libere. Crie outra cobrança se o cliente ainda quiser comprar. |
CANCELED | A venda foi cancelada sem ter sido paga. | TRANSACTION_CANCELED | Cancele o pedido. |
ASK_REFUND | O cliente pediu reembolso da venda inteira. O dinheiro ainda não voltou. | TRANSACTION_ASK_REFUNDING | Registre o pedido. Espere o estorno. |
ASK_PARTIAL_REFUND | O cliente pediu reembolso de parte dos itens. | TRANSACTION_ASK_REFUNDING | Registre o pedido. Espere o estorno. |
REFUNDED | O estorno foi concluído. | TRANSACTION_REFUNDED | Revogue o acesso. |
CHARGEBACK_APPROVED | O banco do cliente aprovou a contestação da compra. | TRANSACTION_CHARGEBACK_APPROVED | Revogue o acesso. |
Detalhes que mudam a sua integração
Vencimento do PIX e do boleto. O PIX vence quando o QR Code expira. O boleto vence 5 dias depois de criado. A PagPolar confere os vencimentos a cada 3 horas, então o status EXPIRED e o evento podem chegar algumas horas depois.
Pagamento atrasado não desfaz reembolso. Se a confirmação do pagamento chega quando a venda já está em reembolso, cancelada ou contestada, o status não volta para PAID.
Estorno de venda não paga. Se o gateway estorna uma venda que não contava como paga, ela vai para CANCELED, e o evento é TRANSACTION_CANCELED.
Volta para PAID sem evento. Acontece quando o pedido de reembolso em ASK_REFUND ou ASK_PARTIAL_REFUND é cancelado ou recusado, e quando um item é estornado e ainda restam itens na venda. TRANSACTION_REFUNDED só chega quando o último item é estornado. Para saber o que aconteceu com o pedido, consulte GET /refunds. Veja Acompanhar reembolsos e chargebacks.
Contestação de venda já reembolsada. Se a venda já estava REFUNDED ou CANCELED, o status não muda, mas o evento TRANSACTION_CHARGEBACK_APPROVED é enviado assim mesmo.
Status sem descrição nesta página
O campo status também pode trazer OPEN, REFUNDING, PARTIALLY_REFUNDED, ABANDONED e CHARGEBACK_REQUESTED. Esta documentação ainda não descreve quando esses status aparecem. Se receber um deles, não libere o que foi vendido.