PIX Recebimento

O recebimento via PIX é o método mais rápido da Linka API. Após o pagamento do comprador, o crédito é processado imediatamente na sua wallet sem período de retenção.

Visão Geral do Fluxo

Criando uma Cobrança PIX

Crie a transação

Envie um POST /api/v1/cobranca/transactions com paymentMethod: "PIX" (opcional, padrão) e o valor em centavos. A resposta vem no envelope {status, data} — o objeto da transação fica em data.

curl -X POST https://api.linkagateway.com/api/v1/cobranca/transactions \
  -H "x-api-key: {sua_api_key}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: {uuid_v4_unico}" \
  -d '{
    "amount": 15000,
    "paymentMethod": "PIX",
    "description": "Pedido #123",
    "customer": {
      "name": "Joao Silva",
      "email": "[email protected]",
      "phone": "11987654321",
      "document": "12345678901"
    },
    "items": [
      {
        "title": "Produto A",
        "amount": 15000,
        "quantity": 1,
        "tangible": false
      }
    ],
    "metadata": {
      "orderId": "order-abc-123"
    }
  }'

const response = await fetch('https://api.linkagateway.com/api/v1/cobranca/transactions', {
  method: 'POST',
  headers: {
    'x-api-key': apiKey,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    amount: 15000, // R$ 150,00 em centavos
    paymentMethod: 'PIX',
    description: 'Pedido #123',
    customer: {
      name: 'Joao Silva',
      email: '[email protected]',
      phone: '11987654321',
      document: '12345678901',
    },
    items: [
      {
        title: 'Produto A',
        amount: 15000,
        quantity: 1,
        tangible: false,
      },
    ],
    metadata: {
      orderId: 'order-abc-123',
    },
  }),
});

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

const response = await fetch('https://api.linkagateway.com/api/v1/cobranca/transactions', {
  method: 'POST',
  headers: {
    'x-api-key': apiKey,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    amount: 15000, // R$ 150,00 em centavos
    paymentMethod: 'PIX',
    description: 'Pedido #123',
    customer: {
      name: 'Joao Silva',
      email: '[email protected]',
      phone: '11987654321',
      document: '12345678901',
    },
    items: [
      {
        title: 'Produto A',
        amount: 15000,
        quantity: 1,
        tangible: false,
      },
    ],
    metadata: {
      orderId: 'order-abc-123',
    },
  }),
});

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

import requests
import uuid

response = requests.post(
    'https://api.linkagateway.com/api/v1/cobranca/transactions',
    headers={
        'x-api-key': api_key,
        'Content-Type': 'application/json',
        'Idempotency-Key': str(uuid.uuid4()),
    },
    json={
        'amount': 15000,  # R$ 150,00 em centavos
        'paymentMethod': 'PIX',
        'description': 'Pedido #123',
        'customer': {
            'name': 'Joao Silva',
            'email': '[email protected]',
            'phone': '11987654321',
            'document': '12345678901',
        },
        'items': [
            {
                'title': 'Produto A',
                'amount': 15000,
                'quantity': 1,
                'tangible': False,
            },
        ],
        'metadata': {
            'orderId': 'order-abc-123',
        },
    },
)

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

package main

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

    "github.com/google/uuid"
)

func main() {
    body := map[string]interface{}{
        "amount":        15000,
        "paymentMethod": "PIX",
        "description":   "Pedido #123",
        "customer": map[string]string{
            "name":     "Joao Silva",
            "email":    "[email protected]",
            "phone":    "11987654321",
            "document": "12345678901",
        },
        "items": []map[string]interface{}{
            {
                "title":    "Produto A",
                "amount":   15000,
                "quantity": 1,
                "tangible": false,
            },
        },
        "metadata": map[string]string{
            "orderId": "order-abc-123",
        },
    }
    jsonBody, _ := json.Marshal(body)

    req, _ := http.NewRequest("POST", "https://api.linkagateway.com/api/v1/cobranca/transactions", bytes.NewBuffer(jsonBody))
    req.Header.Set("x-api-key", apiKey)
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("Idempotency-Key", uuid.New().String())

    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)
}

O header Idempotency-Key é obrigatório e deve ser um UUID v4 único por tentativa de criação. Reenviar a mesma chave retorna a resposta original sem criar uma nova transação. Armazenada por 24 horas.

Exiba o QR Code para o comprador

A resposta 201 vem no envelope {status, data}; os dados PIX para exibição ficam em data.

Resposta 201

{
  "status": true,
  "data": {
    "id": "txn_uuid_aqui",
    "status": "PENDING",
    "amount": 15000,
    "paymentMethod": "PIX",
    "pix": {
      "qrCode": "data:image/png;base64,...",
      "copyPaste": "00020126580014br.gov.bcb.pix...",
      "expiresAt": "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 Cópia e Cola. Exiba também o tempo de expiração para o comprador.

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 já foi processado neste momento.

Payload TRANSACTION_PAID

{
  "eventType": "TRANSACTION_PAID",
  "signature": "v1=...",
  "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 Requisição

Campo	Tipo	Obrigatório	Descrição
`amount`	`integer`	Sim	Valor em centavos (ex: `15000` = R$ 150,00). Mínimo: 100
`paymentMethod`	`string`	Não	`"PIX"` (padrão se omitido)
`description`	`string`	Não	Descrição exibida no comprovante
`customer.name`	`string`	Sim	Nome do comprador
`customer.email`	`string`	Não	Email do comprador
`customer.phone`	`string`	Não	Telefone com DDD, apenas dígitos
`customer.document`	`string`	Sim	CPF (11 dígitos) ou CNPJ (14 dígitos) — o tipo é derivado automaticamente pelo tamanho
`items`	`array`	Sim	Itens do pedido (`title`, `amount`, `quantity`, `tangible`). Mínimo 1 item
`metadata`	`object`	Não	Dados extras (ex: ID do pedido no seu sistema)

Tratamento de Erros

Este endpoint usa o envelope {code, message, correlationID} para erros de validação/negócio (diferente do {status, erro, mensagem} usado no restante da API — veja Erros).

Status HTTP	Código de erro	Causa
`400`	`validation_error`	Campos obrigatórios ausentes ou inválidos
`400`	`IDEMPOTENCY_KEY_MISSING`	Header `Idempotency-Key` ausente
`409`	`IDEMPOTENCY_IN_FLIGHT`	Requisição com a mesma `Idempotency-Key` ainda em processamento (aguarde `Retry-After`)
`422`	`IDEMPOTENCY_KEY_CONFLICT`	`Idempotency-Key` reutilizada com body diferente
`422`	`provider_rejected`	Recusa permanente do provedor de pagamento

Verificando o Status Manualmente

Se precisar verificar o status de uma transação sem depender do webhook:

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

O PIX tem crédito imediato na wallet: o valor líquido fica disponível para saque assim que o status muda para PAID.

Pontos de Atenção

O QR Code PIX tem expiração padrão de 1 hora (configurável via campo expirationDate). Exiba o tempo restante para o comprador.
Transações expiradas recebem o evento TRANSACTION_EXPIRED.
O end2endId no webhook identifica a transação de forma única no Sistema de Pagamentos Brasileiro (SPB), use-o para conciliação bancária.
O campo customer no webhook tem dados PII mascarados (LGPD). Para dados completos, consulte GET /api/v1/cobranca/transactions/{id} autenticado.

Visao Geral

Onboarding

Guias

Referencia

Visão Geral do Fluxo

Criando uma Cobrança PIX

Campos da Requisição

Tratamento de Erros

Verificando o Status Manualmente

Pontos de Atenção

​Visão Geral do Fluxo

​Criando uma Cobrança PIX

​Campos da Requisição

​Tratamento de Erros

​Verificando o Status Manualmente

​Pontos de Atenção

Visão Geral do Fluxo

Criando uma Cobrança PIX

Campos da Requisição

Tratamento de Erros

Verificando o Status Manualmente

Pontos de Atenção