Skip to main content
Uma transação na Linka API passa por uma maquina de estados bem definida. Entender cada status e essencial para implementar a logica de negocio correta no seu sistema.

​
Maquina de Estados

​
Tabela de Status

StatusTerminal?Ação financeiraVisivel no filtro?
PENDINGNãoNenhumaSim
WAITING_PAYMENTNãoNenhumaSim
PROCESSINGNãoNenhumaSim
AUTHORIZEDNãoNenhumaSim
PAIDNão*Crédito na walletSim
REFUSEDSimNenhumaSim
FAILEDSimNenhumaSim
REFUNDEDSimDébito na walletSim
CHARGEDBACKSimDébito na walletSim
DISPUTENãoBloqueio de saldoSim
BLOCKEDSimNenhumaNão (interno)
PARTIALLY_REFUNDEDNãoDébito parcialNão (interno)
*PAID pode transitar para REFUNDED, CHARGEDBACK ou PARTIALLY_REFUNDED.

​
Descrição Detalhada

​
PENDING

Estado inicial de toda transação. Criado em POST /transactions antes de qualquer resposta da IP. Representa “enviado para a IP, aguardando o primeiro retorno”. Muitas IPs mapeiam seus estados iniciais para PENDING: pending, ativa, approved (dependendo da IP).

​
WAITING_PAYMENT

O instrumento de pagamento foi gerado (QR Code PIX, boleto) e aguarda a ação do pagador. Diferente de PENDING, aqui o pagador precisa fazer algo.
Na reconciliação, PENDING e WAITING_PAYMENT são equivalentes — ambos significam “ainda não pago”.

​
PROCESSING

Status transitorio — a IP recebeu a solicitacao e esta processando, sem resultado final ainda. Nenhuma ação financeira ocorre.

​
AUTHORIZED

Status intermediario exclusivo de cartão de crédito. A bandeira aprovou mas o valor ainda não foi capturado/liquidado. O dinheiro ainda não entrou na wallet. Não e terminal — transita para PAID quando capturado ou para REFUSED se a captura for negada. Pagamento confirmado. Crédito na wallet do seller processado imediatamente (PIX) ou via agendamento após período de retenção (boleto D+3, cartão D+N dias úteis).

​
REFUSED

Negativa intencional da IP. A transação foi submetida e a IP respondeu com uma negativa de negocio: cartão bloqueado, limite excedido, dados invalidos, cancelamento pelo pagador. Sempre acompanhado de refusedReason.
REFUSED vs FAILED: REFUSED e uma decisão da IP (o banco rejeitou o cartão). FAILED e um erro técnico ou expiração (a maquina de cartão deu erro). REFUSED sempre tem refusedReason preenchido.

​
FAILED

Falha técnica ou terminal — expiração de boleto/PIX, erro de processamento, status sem mapeamento conhecido, ou exception durante a criacao síncrona. Também funciona como fallback universal: qualquer status de qualquer IP sem mapeamento definido resulta em FAILED.

​
REFUNDED

Estorno total voluntario. O seller decidiu devolver o dinheiro integralmente. Resulta em débito na wallet do seller.

​
PARTIALLY_REFUNDED

Status interno gerado exclusivamente por admin quando o valor estornado e menor que o total da transação. 
PAID R$100 -> admin estorna R$60 -> PARTIALLY_REFUNDED
           -> admin estorna R$40 -> REFUNDED (total >= original)
Este status não aparece nos filtros de listagem do seller, mas pode aparecer no GET /transactions/:id.

​
CHARGEDBACK

O comprador contestou diretamente no banco emissor, ou o BACEN acionou o MED (Mecanismo Especial de Devolução) via PIX. O banco reverteu sem autorizacao do seller. Ao receber este status:
  1. Débito imediato na wallet do seller
  2. MedDispute criado automaticamente para rastreamento
  3. Idempotencia: apenas um débito por transação, mesmo com multiplos webhooks
CHARGEDBACK vs REFUNDED: Chargeback e involuntario e pode incluir multa da bandeira. Estorno e voluntario pelo seller. Nunca trate os dois da mesma forma na sua logica de negocio.

​
DISPUTE

Contestacao ativa em andamento. Diferente de CHARGEDBACK, ainda não ha decisão — esta sendo analisada pelo time da Linka. O saldo e bloqueado na wallet durante a análise. Pode transitar para PAID (seller ganha) ou CHARGEDBACK (comprador ganha).

​
BLOCKED

Status interno. Transação bloqueada preventivamente por suspeita de fraude ou compliance. Nenhuma ação financeira ocorre.

​
Hierarquia de Prioridade

Um status de maior prioridade nunca pode ser sobrescrito por um de menor. Isso garante que chargebacks e bloqueios não sejam revertidos por webhooks tardios. 
Prioridade 1 (menor): PENDING, WAITING_PAYMENT, PROCESSING, AUTHORIZED
Prioridade 2:         PAID
Prioridade 3:         REFUNDED, DISPUTE
Prioridade 4:         CHARGEDBACK
Prioridade 5 (maior): BLOCKED, PARTIALLY_REFUNDED

​
Fluxos por Método de Pagamento

PENDING -> WAITING_PAYMENT -> PAID
                           -> FAILED (expiração)
                           -> REFUSED (cancelamento)
Crédito na wallet e imediato após PAID.