Status de Pagamento na Bestfy
Este documento descreve os status utilizados pela plataforma para representar o ciclo de vida de um pagamento. Eles aparecem em respostas da API, painéis administrativos e notificações (webhooks) enviadas aos integradores.Visão geral#
Os status se dividem em dois grupos:Status da transação — representa a cobrança em si (cartão, PIX ou boleto).
Status de saque — representa uma retirada de saldo pelo vendedor.
Status da transação#
O status da transação descreve em que fase do ciclo de cobrança o pagamento se encontra — desde a criação até a liquidação, reembolso ou disputa.Fluxo inicial#
| Status | Significado | Quando é atribuído |
|---|
PROCESSING | A transação foi criada e está sendo submetida para processamento. | Logo após o registro da cobrança, antes de qualquer retorno do meio de pagamento. |
PENDING | A cobrança foi aceita e está aguardando o pagamento do cliente. | Assim que o meio de pagamento confirma o registro da cobrança (ex.: QR Code PIX emitido, boleto gerado). |
Fluxo de conclusão#
| Status | Significado | Quando é atribuído |
|---|
PAID | O pagamento foi confirmado e o valor foi efetivamente recebido. | Na confirmação da liquidação pelo meio de pagamento. |
REJECTED | O pagamento foi recusado ou não pôde ser concluído. | Em caso de recusa do emissor, cancelamento antes da liquidação ou falha no processamento. |
EXPIRED | O prazo para pagamento expirou sem que a cobrança fosse quitada. | Quando o prazo de vencimento do PIX ou boleto é ultrapassado. |
Fluxo de reembolso#
| Status | Significado | Quando é atribuído |
|---|
PROCESSING_REFUND | Um reembolso foi solicitado e está em processamento. | A partir do pedido de estorno, enquanto a devolução ao cliente não é confirmada. |
REFUNDED | O valor foi devolvido ao cliente. | Quando o reembolso é efetivamente concluído. |
Fluxo de disputa e chargeback#
| Status | Significado | Quando é atribuído |
|---|
IN_DISPUTE | O cliente abriu uma contestação sobre o pagamento. | Ao receber a notificação de abertura da disputa. |
DISPUTE_ACCEPTED | A disputa foi acatada em favor do cliente. | Quando a contestação é aceita pela instituição financeira. |
DISPUTE_REJECTED | A disputa foi rejeitada em favor do vendedor. | Quando a contestação é negada pela instituição financeira. |
DISPUTE_CANCELED | A disputa foi cancelada antes de uma decisão final. | Quando o próprio cliente ou a instituição encerra a contestação. |
CHARGEBACK | O valor da transação foi revertido por decisão da instituição financeira. | Ao receber a confirmação do chargeback. |
Status residual#
| Status | Significado | Quando é atribuído |
|---|
UNKNOWN | Status não reconhecido pela plataforma. | Situação excepcional, normalmente usada como salvaguarda para evitar estados inconsistentes. |
Diagrama simplificado#
┌────────────┐
│ PROCESSING │──────────────┐
└─────┬──────┘ │
▼ ▼
┌────────────┐ ┌──────────┐
│ PENDING │────┬───►│ REJECTED │
└─────┬──────┘ │ └──────────┘
▼ ▼
┌────────┐ ┌──────────┐
│ PAID │ │ EXPIRED │
└───┬────┘ └──────────┘
│
┌────────────┼──────────────┐
▼ ▼ ▼
┌───────────────┐ ┌────────────┐ ┌────────────┐
│ PROCESSING_ │ │ IN_DISPUTE │ │ CHARGEBACK │
│ REFUND │ └─────┬──────┘ └────────────┘
└──────┬────────┘ │
▼ ▼
┌──────────┐ ┌──────────────────────┐
│ REFUNDED │ │ DISPUTE_ACCEPTED │
└──────────┘ │ DISPUTE_REJECTED │
│ DISPUTE_CANCELED │
└──────────────────────┘
Status de saque#
Representa uma solicitação de retirada de saldo da conta do vendedor para uma conta externa.| Status | Significado | Quando é atribuído |
|---|
UNDER_REVIEW | Saque solicitado, aguardando validação. | Logo após a solicitação pelo vendedor. |
APPROVED | Saque aprovado internamente, pronto para ser executado. | Após a validação dos dados e saldo disponível. |
PROCESSING | Saque em processamento pelo sistema financeiro. | Após a aprovação, enquanto a transferência é executada. |
REJECTED | Saque recusado. | Quando a solicitação não atende aos critérios (ex.: saldo insuficiente, dados inválidos). |
FAILED | Saque aprovado, mas a transferência falhou durante a execução. | Quando ocorre falha na liquidação da transferência após a aprovação. |
Diagrama simplificado#
┌──────────────┐
│ UNDER_REVIEW │
└──────┬───────┘
├─────────────► REJECTED
▼
┌──────────────┐
│ APPROVED │
└──────┬───────┘
▼
┌──────────────┐
│ PROCESSING │
└──────┬───────┘
├─────────────► FAILED
▼
(concluído)
Modified at 2026-04-23 14:08:30
