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.
Ciclo de vida da transação#
O caminho até o pagamento depende do meio de pagamento. Depois do pagamento, o caminho é o mesmo para todos: a transação pode ser estornada, contestada ou sofrer chargeback.PIX e boleto#
A cobrança é emitida no meio de pagamento durante a própria requisição de criação. Quando a resposta chega, a transação já está PENDING, com o QR Code ou o boleto emitido, e o webhook de criação é enviado com esse status. Se a cobrança não puder ser emitida, a criação responde erro e a transação fica REJECTED.quando o pagamento é confirmado, a transação vai para PAID;
quando o prazo termina sem pagamento, a transação vai para EXPIRED. O PIX expira 2 minutos depois do vencimento. O boleto expira 2 dias úteis depois do vencimento, para dar tempo à compensação bancária de quem paga no último dia.
Cartão de crédito#
A transação nasce PROCESSING e fica assim até o meio de pagamento confirmar o pagamento, o que normalmente leva poucos segundos. Alguns meios de pagamento informam antes a autorização do emissor, e nesse caso a transação passa por AUTHORIZED. Com a confirmação, a transação vai para PAID. Se for recusada depois da criação (pela análise antifraude, por exemplo), vai para REJECTED.Quando o emissor recusa o cartão na hora, a criação responde 400 com o código FINANCIAL_TRANSACTION_E025 e a transação fica REJECTED, sem webhook. O cartão não gera webhook na criação: o primeiro evento que você recebe já é o desfecho (PAID ou REJECTED).Pagamento tardio#
EXPIRED e REJECTED não são definitivos. O pagamento que chega depois deles, como um PIX pago no último segundo ou confirmado pelo meio de pagamento depois do nosso prazo, é honrado: a transação passa para PAID e o webhook é enviado normalmente. Aceite PAID mesmo depois desses dois status.
Status da transação#
Em andamento#
| Status | Significado | Quando é atribuído |
|---|
PROCESSING | A transação foi criada e aguarda o retorno do meio de pagamento. | Cartão: da criação até a confirmação do pagamento. PIX e boleto: só durante a requisição de criação, então você não chega a ver esse status. |
PENDING | A cobrança foi emitida e está aguardando o pagamento do cliente. | PIX e boleto, assim que a cobrança é emitida (QR Code gerado, boleto emitido). É o status da resposta da criação e do webhook de criação. |
AUTHORIZED | O emissor autorizou o cartão, mas o pagamento ainda não foi confirmado. | Cartão, quando o meio de pagamento informa a autorização antes da confirmação. |
Desfecho#
| Status | Significado | Quando é atribuído |
|---|
PAID | O pagamento foi confirmado e o valor foi efetivamente recebido. | Na confirmação do pagamento pelo meio de pagamento, inclusive depois de EXPIRED ou REJECTED (pagamento tardio). |
REJECTED | O pagamento foi recusado ou a cobrança não pôde ser emitida. | Em caso de recusa do emissor ou da análise antifraude, falha ao emitir a cobrança ou cancelamento pelo meio de pagamento antes do pagamento. |
EXPIRED | O prazo para pagamento terminou sem que a cobrança fosse paga. | PIX: 2 minutos depois do vencimento. Boleto: 2 dias úteis depois do vencimento. |
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 o meio de pagamento não confirma a devolução. Se o meio de pagamento recusar o estorno, a transação volta ao status anterior. Esta etapa não gera webhook. |
REFUNDED | O valor foi devolvido ao cliente. | Quando o reembolso é efetivamente concluído. |
O estorno é sempre do valor integral e só pode ser pedido para uma transação PAID ou IN_PROTEST. Boleto não tem estorno.Fluxo de disputa e chargeback#
| Status | Significado | Quando é atribuído |
|---|
IN_PROTEST | O cliente indicou ao banco emissor que não reconhece o pagamento e iniciou um processo de chargeback (apenas cartão de crédito). | Ao receber o aviso de contestação do emissor. |
MED | O pagamento está em análise pelo Mecanismo Especial de Devolução (apenas PIX). | Ao receber o aviso de abertura do MED. |
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. |
Transações antigas podem trazer o status CANCELED, que não é mais atribuído. Trate-o como REJECTED.
O que esperar das mudanças de status#
Uma transação paga nunca volta para PENDING nem vira EXPIRED ou REJECTED.
EXPIRED e REJECTED podem virar PAID (pagamento tardio).
Uma transação estornada não volta para PAID.
Cada mudança de status gera um único webhook.
Diagrama simplificado#
PIX e boleto Cartão
┌─────────┐ ┌────────────┐
│ PENDING │ │ PROCESSING │
└────┬────┘ └─────┬──────┘
│ ▼
│ ┌────────────┐
│ │ AUTHORIZED │ (quando informado)
│ └─────┬──────┘
▼ ▼
┌───────────────────────────────────────┐
│ PAID │ REJECTED │ EXPIRED (*) │
└───────────────────────────────────────┘
(*) só PIX e boleto
REJECTED, EXPIRED ───► PAID (pagamento tardio)
┌────────┐
│ PAID │
└───┬────┘
┌──────────────┬─────┴────────┬──────────────┐
▼ ▼ ▼ ▼
┌──────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐
│ PROCESSING_ │ │ IN_PROTEST │ │ IN_DISPUTE │ │ CHARGEBACK │
│ REFUND │ │ MED │ └─────┬──────┘ └───── ───────┘
└──────┬───────┘ └─────┬──────┘ ▼
▼ ▼ DISPUTE_ACCEPTED
┌──────────┐ REFUNDED, DISPUTE_REJECTED
│ REFUNDED │ CHARGEBACK DISPUTE_CANCELED
└──────────┘ ou PAID
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. |
PROCESSING | Saque aprovado, com a transferência em execução. | Após a aprovação, enquanto a transferência é executada. |
APPROVED | Transferência concluída. | Quando a transferência é confirmada. |
REJECTED | Saque recusado. | Quando a solicitação é recusada na validação. |
FAILED | Saque aprovado, mas a transferência falhou durante a execução. | Quando a transferência não pode ser concluída após a aprovação. |
Diagrama simplificado#
┌──────────────┐
│ UNDER_REVIEW │
└──────┬───────┘
├─────────────► REJECTED
▼
┌──────────────┐
│ PROCESSING │
└──────┬───────┘
├─────────────► FAILED
▼
┌──────────────┐
│ APPROVED │
└──────────────┘
Modified at 2026-10-01 18:53:02
