Skip to main content
O recebimento via PIX e o método mais rapido da Linka API. Após o pagamento do comprador, o crédito e processado imediatamente na wallet do seller sem período de retenção.

​
Visao Geral do Fluxo

​
Criando uma Cobrança PIX

1

Crie a transação

Envie um POST /transactions com method: "PIX" e o valor em centavos.
curl -X POST https://api.linka.com/transactions \
  -H "Authorization: Bearer {seu_token}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: {uuid_v4_unico}" \
  -d '{
    "amount": 15000,
    "method": "PIX",
    "description": "Pedido #123",
    "customer": {
      "name": "Joao Silva",
      "email": "[email protected]",
      "document": "12345678901"
    },
    "items": [
      {
        "title": "Produto A",
        "quantity": 1,
        "unitPrice": 15000
      }
    ],
    "metadata": {
      "orderId": "order-abc-123"
    }
  }'
O header Idempotency-Key e obrigatório e deve ser um UUID v4 único por tentativa de criacao. Reenviar a mesma chave retorna a resposta original sem criar uma nova transação.
2

Exiba o QR Code para o comprador

A resposta 201 contém os dados PIX para exibição.
Resposta 201
{
  "status": true,
  "data": {
    "id": "txn_uuid_aqui",
    "status": "PENDING",
    "amount": 15000,
    "method": "PIX",
    "pix": {
      "qrcode": "data:image/png;base64,...",
      "copyPaste": "00020126580014br.gov.bcb.pix...",
      "expirationDate": "2026-04-09T13:00:00.000Z"
    },
    "createdAt": "2026-04-09T12:00:00.000Z"
  }
}
Use pix.qrcode para exibir a imagem do QR Code ou pix.copyPaste para o código Pix Copia e Cola. Exiba também o tempo de expiração para o comprador.
3

Aguarde o webhook de confirmação

Quando o comprador pagar, a Linka envia um evento TRANSACTION_PAID para o seu endpoint de webhook cadastrado. O crédito na wallet ja foi processado neste momento.
Payload TRANSACTION_PAID
{
  "eventType": "TRANSACTION_PAID",
  "signature": "hmac-v1-sha256-...",
  "id": "txn_uuid_aqui",
  "amount": 15000,
  "method": "PIX",
  "status": "PAID",
  "pix": {
    "copyPaste": "00020126580014br.gov.bcb.pix...",
    "expirationDate": "2026-04-09T13:00:00.000Z"
  },
  "end2endId": "E12345678202604091200...",
  "paidAt": "2026-04-09T12:05:00.000Z",
  "description": "Pedido #123",
  "metadata": { "orderId": "order-abc-123" },
  "customer": { "name": "Jo***", "email": "j***@exemplo.com.br" },
  "createdAt": "2026-04-09T12:00:00.000Z"
}
Sempre valide a signature HMAC-SHA256 antes de processar o webhook. Veja o guia de Eventos de Webhook para detalhes de validação.

​
Campos da Requisicao

CampoTipoObrigatórioDescrição
amountintegerSimValor em centavos (ex: 15000 = R$ 150,00)
methodstringSimDeve ser "PIX"
descriptionstringNãoDescrição exibida no comprovante
customer.namestringSimNome do comprador
customer.emailstringSimEmail do comprador
customer.documentstringSimCPF (11 digitos) ou CNPJ (14 digitos)
itemsarrayNãoItens do pedido
metadataobjectNãoDados extras (ex: ID do pedido no seu sistema)

​
Tratamento de Erros

Status HTTPCódigo de erroCausa
400INVALID_INPUTCampos obrigatórios ausentes ou invalidos
409IDEMPOTENCY_CONFLICTIdempotency-Key ja foi usada — retorna transação original
422FEE_EXCEEDS_AMOUNTTaxa configurada e maior que o valor da transação
503PROVIDER_UNAVAILABLEProvedor indisponível no momento

​
Verificando o Status Manualmente

Se precisar verificar o status de uma transação sem depender do webhook: 
curl https://api.linka.com/transactions/{id} \
  -H "Authorization: Bearer {seu_token}"
O PIX tem crédito imediato na wallet. Diferente do boleto (D+3) e cartão (D+N dias úteis), o netAmount fica disponível para saque assim que o status muda para PAID.

​
Pontos de Atencao

  • O QR Code PIX tem expiração padrão (geralmente 30-60 minutos). Exiba o tempo restante para o comprador.
  • Transações expiradas recebem o evento TRANSACTION_FAILED.
  • O end2endId no webhook identifica a transação de forma única no Sistema de Pagamentos Brasileiro (SPB) — use-o para conciliacao bancaria.
  • O campo customer no webhook tem dados PII mascarados (LGPD). Para dados completos, consulte GET /transactions/:id autenticado.