PIX Saque

O saque PIX (PIX-OUT) permite que você transfira saldo da sua wallet Linka para qualquer chave PIX. O débito é atômico: o saldo é reservado no momento da criação do saque, antes do envio para a instituição de pagamento.

Visão Geral do Fluxo

Verificando o Saldo Disponível

Antes de criar um saque, verifique o saldo disponível:

curl https://api.linkagateway.com/v1/balance-statement \
  -H "x-api-key: {sua_api_key}"

Resposta

{
  "status": true,
  "data": {
    "available": 50000,
    "blocked": 0,
    "total": 50000,
    "currency": "BRL"
  }
}

O saldo disponível para saque é o campo data.available. O campo data.blocked representa valores retidos (em disputa ou aguardando liberação), ainda não disponíveis para saque.

Criando um Saque

Solicite o saque

curl -X POST https://api.linkagateway.com/api/v1/cobranca/withdrawals \
  -H "x-api-key: {sua_api_key}" \
  -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"
    }
  }'

const response = await fetch('https://api.linkagateway.com/api/v1/cobranca/withdrawals', {
  method: 'POST',
  headers: {
    'x-api-key': apiKey,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    amount: 50000, // R$ 500,00 em centavos
    method: 'PIX',
    pixKey: '[email protected]',
    pixKeyType: 'EMAIL',
    description: 'Saque mensal',
  }),
});

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

const response = await fetch('https://api.linkagateway.com/api/v1/cobranca/withdrawals', {
  method: 'POST',
  headers: {
    'x-api-key': apiKey,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    amount: 50000, // R$ 500,00 em centavos
    method: 'PIX',
    pixKey: '[email protected]',
    pixKeyType: 'EMAIL',
    description: 'Saque mensal',
  }),
});

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

import requests
import uuid

response = requests.post(
    'https://api.linkagateway.com/api/v1/cobranca/withdrawals',
    headers={
        'x-api-key': api_key,
        'Content-Type': 'application/json',
        'Idempotency-Key': str(uuid.uuid4()),
    },
    json={
        'amount': 50000,  # R$ 500,00 em centavos
        'method': 'PIX',
        'pixKey': '[email protected]',
        'pixKeyType': 'EMAIL',
        'description': 'Saque mensal',
    },
)

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

package main

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

    "github.com/google/uuid"
)

func main() {
    body := map[string]interface{}{
        "amount":      50000,
        "method":      "PIX",
        "pixKey":      "[email protected]",
        "pixKeyType":  "EMAIL",
        "description": "Saque mensal",
    }
    jsonBody, _ := json.Marshal(body)

    req, _ := http.NewRequest("POST", "https://api.linkagateway.com/api/v1/cobranca/withdrawals", 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)
}

Guarde o ID do saque

A resposta 201 confirma que o saldo foi reservado e o saque está em processamento.

Resposta 201

{
  "status": true,
  "data": {
    "id": "wd_uuid_aqui",
    "status": "PENDING",
    "amount": 50000,
    "method": "PIX",
    "pixKey": "[email protected]",
    "pixKeyType": "EMAIL",
    "createdAt": "2026-04-09T12:00:00.000Z"
  }
}

A tarifa do saque é debitada do saldo junto com o valor, conforme o plano contratado.

Aguarde o webhook de confirmação

Quando a transferência for liquidada, a Linka envia um evento WITHDRAWAL_PAID:

Payload WITHDRAWAL_PAID

{
  "version": "1",
  "expires_at": "2026-04-10T12:01:05.000Z",
  "eventType": "WITHDRAWAL_PAID",
  "signature": "v1=...",
  "id": "wd_uuid_aqui",
  "amount": 50000,
  "method": "PIX",
  "pixKey": "***@exemplo.com.br",
  "pixKeyType": "EMAIL",
  "status": "PAID",
  "approvedAt": "2026-04-09T12:01:00.000Z",
  "processedAt": "2026-04-09T12:01:05.000Z",
  "end2end": "E12345678202604091201...",
  "externalRef": "ref-provider-123",
  "metadata": null,
  "createdAt": "2026-04-09T12:00:00.000Z"
}

Se o usuário dono da credencial tiver 2FA ativo, a criação do saque exige também o header X-MFA-Challenge com um token de confirmação 2FA — inclusive em chamadas via API Key. Sem ele, a API retorna 403 MFA_REQUIRED.

Campos da Requisição

Campo	Tipo	Obrigatório	Descrição
`amount`	`integer`	Sim	Valor em centavos. Mínimo: `500` (R$ 5,00)
`method`	`string`	Sim	Deve ser `"PIX"`
`pixKey`	`string`	Sim	Chave PIX do destinatário
`pixKeyType`	`string`	Sim	Tipo da chave: `CPF`, `CNPJ`, `EMAIL`, `PHONE`, `EVP`
`description`	`string`	Não	Descrição interna do saque
`metadata`	`object`	Não	Dados extras para controle interno

Tipos de Chave PIX

`pixKeyType`	Formato esperado	Exemplo
`CPF`	11 dígitos (pontuação ignorada)	`12345678901`
`CNPJ`	14 caracteres — numérico ou alfanumérico	`12345678000190` / `12ABC34501DE35`
`EMAIL`	Email válido	`[email protected]`
`PHONE`	E.164 recomendado; aceito sem `+` ou só DDD+número (normalizamos)	`+5511999998888`
`EVP`	UUID v4 (chave aleatória)	`550e8400-e29b-41d4...`

Status do Saque

Status	Descrição
`PENDING`	Saldo debitado, aguardando processamento
`APPROVED`	Aprovado, aguardando envio
`PROCESSING`	Em processamento pela instituição de pagamento
`PAID`	Transferência liquidada, crédito enviado ao destinatário
`FAILED`	Falha, saldo reembolsado automaticamente
`REJECTED`	Rejeitado, saldo reembolsado automaticamente
`REFUNDED`	Valor devolvido pelo banco de destino após a liquidação

Em caso de falha (FAILED ou REJECTED), o valor debitado (incluindo a tarifa) é reembolsado automaticamente para a sua wallet. O saldo fica disponível imediatamente para nova tentativa.

Eventos de Webhook

Evento	Quando ocorre
`WITHDRAWAL_CREATED`	Saque criado, saldo reservado
`WITHDRAWAL_APPROVED`	Saque aprovado, aguardando envio
`WITHDRAWAL_PROCESSING`	Saque em processamento pela instituição de pagamento
`WITHDRAWAL_PAID`	Transferência liquidada
`WITHDRAWAL_FAILED`	Falha na transferência, saldo reembolsado
`WITHDRAWAL_REJECTED`	Saque rejeitado, saldo reembolsado

Tratamento de Erros

Status HTTP	Código de erro	Causa
`400`	`INSUFFICIENT_WALLET_BALANCE`	Saldo disponível menor que o valor do saque + tarifa
`400`	`WITHDRAWAL_MIN_VALUE`	Valor menor que R$ 5,00 (500 centavos)
`400`	`MISSING_PIX_KEY_INFO`	`pixKey`/`pixKeyType` ausentes em saque PIX
`403`	`MFA_REQUIRED`	2FA ativo e header `X-MFA-Challenge` ausente
`409`	`IDEMPOTENCY_IN_FLIGHT`	Requisição com a mesma `Idempotency-Key` ainda em processamento
`422`	`IDEMPOTENCY_KEY_CONFLICT`	`Idempotency-Key` reutilizada com body diferente
`422`	`WITHDRAWAL_ALREADY_IN_PROGRESS`	Já existe um saque idêntico em processamento

Verificando o Status Manualmente

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

O saldo é debitado atomicamente no momento da criação do saque, não quando a transferência é concluída. Isso garante que o saldo não fique negativo, mas significa que o valor fica indisponível até a conclusão ou falha do saque.

Visao Geral

Onboarding

Guias

Referencia

Visão Geral do Fluxo

Verificando o Saldo Disponível

Criando um Saque

Campos da Requisição

Tipos de Chave PIX

Status do Saque

Eventos de Webhook

Tratamento de Erros

Verificando o Status Manualmente

​Visão Geral do Fluxo

​Verificando o Saldo Disponível

​Criando um Saque

​Campos da Requisição

​Tipos de Chave PIX

​Status do Saque

​Eventos de Webhook

​Tratamento de Erros

​Verificando o Status Manualmente

Visão Geral do Fluxo

Verificando o Saldo Disponível

Criando um Saque

Campos da Requisição

Tipos de Chave PIX

Status do Saque

Eventos de Webhook

Tratamento de Erros

Verificando o Status Manualmente