Skip to main content
O saque PIX (PIX-OUT) permite que o seller transfira saldo da wallet Linka para qualquer chave PIX. O débito e atomico — o saldo e reservado no momento da criacao do saque, antes do envio para a IP.

​
Visao Geral do Fluxo

​
Verificando o Saldo Disponível

Antes de criar um saque, verifique o saldo disponível para PIX: 
curl https://api.linka.com/seller-wallet \
  -H "Authorization: Bearer {seu_token}"
Resposta
{
  "balance": 50000,
  "blockedBalance": 0,
  "boletoBalance": 0,
  "boletoPendingBalance": 3000,
  "cardBalance": 0,
  "cardPendingBalance": 12000
}
O saldo disponível para saque PIX e calculado como balance - blockedBalance. Os campos *PendingBalance representam valores ainda em período de retenção (boleto/cartão) — ainda não disponeis para saque.

​
Criando um Saque

1

Solicite o saque

curl -X POST https://api.linka.com/withdrawals \
  -H "Authorization: Bearer {seu_token}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: {uuid_v4_unico}" \
  -d '{
    "amount": 50000,
    "method": "PIX",
    "pixKey": "[email protected]",
    "pixKeyType": "EMAIL",
    "description": "Saque mensal",
    "metadata": {
      "referenceId": "withdraw-2026-04"
    }
  }'
2

Guarde o ID do saque

A resposta 201 confirma que o saldo foi reservado e o saque esta em processamento.
Resposta 201
{
  "status": true,
  "data": {
    "id": "wd_uuid_aqui",
    "status": "PENDING",
    "amount": 50000,
    "feeAmount": 200,
    "netAmount": 49800,
    "method": "PIX",
    "pixKey": "[email protected]",
    "pixKeyType": "EMAIL",
    "createdAt": "2026-04-09T12:00:00.000Z"
  }
}
O campo netAmount e o valor que chegara ao destinatario (amount - feeAmount).
3

Aguarde o webhook de confirmação

Quando a transferencia for concluida, a Linka envia um evento WITHDRAWAL_COMPLETED:
Payload WITHDRAWAL_COMPLETED
{
  "eventType": "WITHDRAWAL_COMPLETED",
  "signature": "hmac-v1-sha256-...",
  "id": "wd_uuid_aqui",
  "amount": 50000,
  "method": "PIX",
  "pixKey": "***@exemplo.com.br",
  "pixKeyType": "EMAIL",
  "status": "COMPLETED",
  "withdrawalType": "STANDARD",
  "approvedAt": "2026-04-09T12:01:00.000Z",
  "processedAt": "2026-04-09T12:01:05.000Z",
  "end2end": "E12345678202604091201...",
  "externalRef": "ref-ip-123",
  "metadata": null,
  "createdAt": "2026-04-09T12:00:00.000Z"
}

​
Campos da Requisicao

CampoTipoObrigatórioDescrição
amountintegerSimValor em centavos. Mínimo: 500 (R$ 5,00)
methodstringSimDeve ser "PIX"
pixKeystringSimChave PIX do destinatario
pixKeyTypestringSimTipo da chave: CPF, CNPJ, EMAIL, PHONE, EVP
descriptionstringNãoDescrição interna do saque
metadataobjectNãoDados extras para controle interno

​
Tipos de Chave PIX

pixKeyTypeFormato esperadoExemplo
CPF11 digitos numericos12345678901
CNPJ14 digitos numericos12345678000190
EMAILEmail valido[email protected]
PHONE+55DDD9XXXXXXXX+5511999998888
EVPUUID v4 (chave aleatoria)550e8400-e29b-41d4...

​
Status do Saque

StatusDescrição
PENDINGSaldo debitado, aguardando processamento
PROCESSINGEm processamento pela IP
APPROVEDAprovado pela IP, aguardando liquidacao
COMPLETEDTransferencia concluida com sucesso
FAILEDFalha — saldo reembolsado automaticamente
CANCELLEDCancelado — saldo reembolsado automaticamente
Em caso de falha (FAILED ou CANCELLED), o amount + feeAmount e reembolsado automaticamente para a wallet do seller. O saldo fica disponível imediatamente para nova tentativa.

​
Eventos de Webhook

EventoQuando ocorre
WITHDRAWAL_PROCESSINGSaque em processamento pela IP
WITHDRAWAL_COMPLETEDTransferencia concluida
WITHDRAWAL_FAILEDFalha na transferencia, saldo reembolsado

​
Tratamento de Erros

Status HTTPCódigo de erroCausa
400INSUFFICIENT_WALLET_BALANCESaldo disponível menor que amount + fee
400AMOUNT_BELOW_MINIMUMValor menor que R$ 5,00 (500 centavos)
409IDEMPOTENCY_CONFLICTIdempotency-Key ja usada
422ACQUIRER_NOT_CONFIGUREDNenhuma IP configurada para saques PIX

​
Verificando o Status Manualmente

curl https://api.linka.com/withdrawals/{id} \
  -H "Authorization: Bearer {seu_token}"
O saldo e debitado atomicamente no momento da criacao do saque, não quando a transferencia e concluida. Isso garante que o saldo não fique negativo, mas significa que o valor fica indisponível até a conclusao ou falha do saque.