Status de Transação

Uma transação na Linka API passa por uma máquina de estados bem definida. Entender cada status é essencial para implementar a lógica de negócio correta no seu sistema.

Máquina de Estados

Tabela de Status

Status	Terminal?	Ação financeira	Visível no filtro?
`PENDING`	Não	Nenhuma	Sim
`WAITING_PAYMENT`	Não	Nenhuma	Sim
`PROCESSING`	Não	Nenhuma	Sim
`PAID`	Não*	Crédito na wallet	Sim
`FAILED`	Sim	Nenhuma	Sim
`EXPIRED`	Sim	Nenhuma	Sim
`REFUNDED`	Sim	Débito na wallet	Sim
`CHARGEDBACK`	Sim	Débito na wallet	Sim
`DISPUTE`	Não	Bloqueio de saldo	Sim
`BLOCKED`	Sim	Nenhuma	Não (interno)
`PENDING_REVIEW`	Não	Bloqueio temporário	Não (raro — em análise)
`PARTIALLY_REFUNDED`	Não	Débito parcial	Não (interno)

*PAID pode transitar para REFUNDED, CHARGEDBACK ou PARTIALLY_REFUNDED.

Novos status podem ser adicionados. Trate valores desconhecidos com um fallback — não faça switch exaustivo.

Descrição Detalhada

PENDING

Estado inicial de toda transação, criado em POST /api/v1/cobranca/transactions. Representa “enviado para processamento, aguardando o primeiro retorno da instituição de pagamento”.

WAITING_PAYMENT

O QR Code foi gerado 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 transitório: a solicitação está sendo processada, sem resultado final ainda. Nenhuma ação financeira ocorre.

PAID

Pagamento confirmado. O crédito na sua wallet é processado imediatamente — PIX não tem período de retenção.

FAILED

Falha técnica ou terminal. Erro de processamento, status sem mapeamento conhecido, ou exceção durante a criação. Também funciona como fallback universal: qualquer status sem mapeamento definido resulta em FAILED.

EXPIRED

Transação expirada: o QR Code não foi pago dentro do prazo (padrão: 1 hora, configurável via campo expiration). Diferente de FAILED, EXPIRED indica que o pagador não tentou pagar — não houve falha técnica.

REFUNDED

Estorno total voluntário. Você decidiu devolver o dinheiro integralmente. Resulta em débito na sua wallet.

PARTIALLY_REFUNDED

Status atribuído quando um estorno parcial é processado e o valor estornado é menor que o total da transação.

PAID R$100 -> estorno de R$60 -> PARTIALLY_REFUNDED
           -> estorno de R$40 -> REFUNDED (total >= original)

Este status não aparece nos seus filtros de listagem, mas pode aparecer no GET /api/v1/cobranca/transactions/{id}.

CHARGEDBACK

O BACEN acionou o MED (Mecanismo Especial de Devolução) do PIX — devolução por suspeita de fraude ou erro, sem sua autorização. Ao receber este status:

Débito imediato na sua wallet
Uma disputa é criada automaticamente para rastreamento
Idempotência: apenas um débito por transação, mesmo com múltiplos webhooks

CHARGEDBACK vs REFUNDED: a devolução via MED é involuntária. O estorno é voluntário, feito por você. Nunca trate os dois da mesma forma na sua lógica de negócio.

DISPUTE

Contestação ativa em andamento. Diferente de CHARGEDBACK, ainda não há decisão — está sendo analisada pela Linka. O saldo é bloqueado na wallet durante a análise. Pode transitar para PAID (você ganha) ou CHARGEDBACK (comprador ganha).

BLOCKED

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

PENDING_REVIEW

Status raro: transação temporariamente em análise. O saldo relacionado fica bloqueado até a conclusão.

Hierarquia de Prioridade

Um status de maior prioridade nunca pode ser sobrescrito por um de menor. Isso garante que devoluções e bloqueios não sejam revertidos por webhooks tardios.

Prioridade 1 (menor): PENDING, WAITING_PAYMENT, PROCESSING
Prioridade 2:         PAID
Prioridade 3:         REFUNDED, DISPUTE
Prioridade 4:         CHARGEDBACK
Prioridade 5 (maior): BLOCKED, PARTIALLY_REFUNDED

Verificando o Status via API

Consulte o status de qualquer transação pelo GET /api/v1/cobranca/transactions/{id}:

curl https://api.linkagateway.com/api/v1/cobranca/transactions/{id} \
  -H "x-api-key: {sua_api_key}"

const response = await fetch('https://api.linkagateway.com/api/v1/cobranca/transactions/{id}', {
  headers: {
    'x-api-key': apiKey,
  },
});

const { data: transaction } = await response.json();

const response = await fetch('https://api.linkagateway.com/api/v1/cobranca/transactions/{id}', {
  headers: {
    'x-api-key': apiKey,
  },
});

const { data: transaction } = await response.json() as any;

import requests

response = requests.get(
    'https://api.linkagateway.com/api/v1/cobranca/transactions/{id}',
    headers={
        'x-api-key': api_key,
    },
)

transaction = response.json()['data']

package main

import (
    "encoding/json"
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "https://api.linkagateway.com/api/v1/cobranca/transactions/{id}", nil)
    req.Header.Set("x-api-key", apiKey)

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()

    var data map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&data)
    fmt.Println(data)
}

Fluxo PIX resumido

PENDING -> WAITING_PAYMENT -> PAID
                           -> EXPIRED (QR Code vencido sem pagamento)

Crédito na wallet é imediato após PAID.

Visao Geral

Onboarding

Guias

Referencia

Status de Transação

Máquina de Estados

Tabela de Status

Descrição Detalhada

PENDING

WAITING_PAYMENT

PROCESSING

PAID

FAILED

EXPIRED

REFUNDED

PARTIALLY_REFUNDED

CHARGEDBACK

DISPUTE

BLOCKED

PENDING_REVIEW

Hierarquia de Prioridade

Verificando o Status via API

Fluxo PIX resumido

​Máquina de Estados

​Tabela de Status

​Descrição Detalhada

​PENDING

​WAITING_PAYMENT

​PROCESSING

​PAID

​FAILED

​EXPIRED

​REFUNDED

​PARTIALLY_REFUNDED

​CHARGEDBACK

​DISPUTE

​BLOCKED

​PENDING_REVIEW

​Hierarquia de Prioridade

​Verificando o Status via API

​Fluxo PIX resumido

Máquina de Estados

Tabela de Status

Descrição Detalhada

PENDING

WAITING_PAYMENT

PROCESSING

PAID

FAILED

EXPIRED

REFUNDED

PARTIALLY_REFUNDED

CHARGEDBACK

DISPUTE

BLOCKED

PENDING_REVIEW

Hierarquia de Prioridade

Verificando o Status via API

Fluxo PIX resumido