API Reference

Visão geral

A Linka API é uma API REST que permite processar pagamentos PIX, gerenciar saques, consultar extratos e configurar webhooks. Todos os dados financeiros são expressos em centavos (integers) para evitar erros de arredondamento.

No momento, o único método de pagamento disponível é PIX.

Base URL

https://api.linkagateway.com

Autenticação

Todas as requisições são autenticadas via API Key no header x-api-key:

x-api-key: sk_live_sua_api_key_aqui

A API Key é gerada por você na tela de Integrações do Dashboard e exibida uma única vez na criação. Veja Autenticação para detalhes.

Valores monetários

Todos os valores monetários são representados em centavos (inteiros, sem decimais):

Valor real	Valor na API
R$ 1,00	100
R$ 10,00	1000
R$ 150,00	15000
R$ 1.000,00	100000

Identificadores

Os IDs de recursos (transações, saques, disputas) são strings opacas (formato CUID, ex: clxyz1234abcdef). Trate-os como texto, sem assumir formato ou tamanho fixo.

Paginação

Os parâmetros de paginação variam por recurso — consulte cada endpoint. Em resumo:

Recurso	Parâmetros	Padrão
Extrato, Saques, Disputas	`take` / `skip`	`take=10`, `skip=0`
Transações	`limit` / `offset`	`limit=50`, `offset=0`

O extrato detalhado (GET /v1/balance-statement/statements) também aceita um cursor — o id do último item da página anterior — mais eficiente que offset para grandes volumes. O envelope de resposta varia por recurso e está documentado em cada endpoint.

Formato de data

Todas as datas seguem o formato ISO 8601:

2026-03-06T10:00:00.000Z

Filtros de data aceitam o formato YYYY-MM-DD.

Erros

A API retorna erros em um formato JSON padronizado, com código de erro estável no campo erro:

{
  "status": false,
  "erro": "INSUFFICIENT_WALLET_BALANCE",
  "mensagem": "Saldo insuficiente para o saque solicitado.",
  "requestId": "3f9c2a17-...",
  "timestamp": "2026-03-06T10:00:00.000Z",
  "path": "/api/v1/cobranca/withdrawals"
}

Campo	Descrição
`status`	Sempre `false` em erros
`erro`	Código estável do erro (use este campo na sua lógica)
`mensagem`	Descrição legível em português
`requestId`	Identificador da requisição — informe ao suporte ao abrir chamados
`timestamp` / `path`	Data/hora e rota da requisição

Tabela de códigos HTTP

Status	Significado	Ação recomendada
`400`	Bad Request	Parâmetros inválidos, API Key ausente/inválida ou `Idempotency-Key` ausente
`401`	Unauthorized	Credencial expirada ou não autorizada
`403`	Forbidden	Sem permissão para este recurso (ex: 2FA exigido, escopo insuficiente)
`404`	Not Found	Recurso não encontrado ou não pertence a você
`409`	Conflict	Requisição com a mesma `Idempotency-Key` ainda em processamento (aguarde `Retry-After`)
`422`	Unprocessable Entity	Regra de negócio violada (ex: `Idempotency-Key` reutilizada com body diferente, pagamento recusado)
`429`	Too Many Requests	Limite de requisições excedido — aguarde o `Retry-After`
`500`	Internal Server Error	Erro interno. Contate o suporte com o `requestId`
`503`	Service Unavailable	Serviço temporariamente indisponível

Códigos de erro comuns

Código	HTTP	Descrição
`UNAUTHORIZED`	401	API Key ausente, inexistente, revogada ou expirada
`IDEMPOTENCY_KEY_MISSING`	400	Header `Idempotency-Key` ausente em endpoint que o exige
`IDEMPOTENCY_KEY_CONFLICT`	422	Mesma `Idempotency-Key` com body diferente
`IDEMPOTENCY_IN_FLIGHT`	409	Requisição original ainda em processamento
`RATE_LIMITED`	429	Limite de requisições excedido

POST/GET /api/v1/cobranca/* (criação, consulta e listagem de transação e saque PIX) é servido por um serviço diferente do restante da API. Erros de validação/negócio nesses endpoints usam o envelope {code, message, correlationID} em vez do {status, erro, mensagem, requestId, timestamp, path} acima. Erros de autenticação (API Key ausente/inválida/revogada) continuam no formato padrão desta seção.

Idempotência

Operações de criação (POST /api/v1/cobranca/transactions, POST /api/v1/cobranca/withdrawals, POST /v1/disputes/appeal) exigem o header Idempotency-Key (UUID v4 recomendado, até 128 caracteres). Comportamento:

Repetir a mesma key com o mesmo body retorna a resposta original (mesmo status HTTP), sem reprocessar.
Repetir a mesma key com body diferente retorna 422 IDEMPOTENCY_KEY_CONFLICT.
Se a requisição original ainda estiver em processamento, retorna 409 IDEMPOTENCY_IN_FLIGHT com Retry-After: 5.
A chave é armazenada por 24 horas em POST /api/v1/cobranca/transactions, 72 horas nos demais endpoints acima.

Detalhes em Idempotência.

Rate limits

Os limites padrão por conta (ajustáveis conforme o volume contratado):

Operação	Limite padrão
Criação de transações	20 req/s (rajadas de até 200 req/min)
Criação de saques	5 req/s
Uso agregado da API Key	1000 req/min

Ao exceder um limite, a API retorna 429 com código RATE_LIMITED e o header Retry-After indicando quantos segundos aguardar.

Ciclo de vida de uma transação

PENDING → WAITING_PAYMENT → PAID
PENDING → PAID (confirmação direta)
PENDING → EXPIRED (QR Code vencido)
WAITING_PAYMENT → EXPIRED (QR Code vencido)
PENDING → FAILED (erro técnico)
PAID → REFUNDED
PAID → PARTIALLY_REFUNDED
PAID → DISPUTE → PAID
               → CHARGEDBACK
PAID → CHARGEDBACK (MED)

Veja a máquina de estados completa em Status de Transação.

Ciclo de vida de um saque

PENDING → APPROVED → PROCESSING → PAID
        ↘ REJECTED
                   ↘ FAILED
PAID → REFUNDED (devolução pelo banco destino)

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

Visao Geral

Transações

Saques

Saldo e Extrato

Disputas

Visão geral

Autenticação

Valores monetários

Identificadores

Paginação

Formato de data

Erros

Tabela de códigos HTTP

Códigos de erro comuns

Idempotência

Rate limits

Ciclo de vida de uma transação

Ciclo de vida de um saque

​Visão geral

​Autenticação

​Valores monetários

​Identificadores

​Paginação

​Formato de data

​Erros

​Tabela de códigos HTTP

​Códigos de erro comuns

​Idempotência

​Rate limits

​Ciclo de vida de uma transação

​Ciclo de vida de um saque

Visão geral

Autenticação

Valores monetários

Identificadores

Paginação

Formato de data

Erros

Tabela de códigos HTTP

Códigos de erro comuns

Idempotência

Rate limits

Ciclo de vida de uma transação

Ciclo de vida de um saque