API v1
Saques

Reservar saque Pix

POST/v1/withdrawalswithdrawals:write

Cria a reserva local do saque. O processamento posterior é assíncrono. Destino diferente do CPF/CNPJ próprio verificado exige também withdrawals:external_write e política administrativa efetiva para a conta. Nesse canal, o cliente autorizado escolhe a chave Pix destinatária.

Envie sempre o cabeçalho Idempotency-Key. Se a conexão cair, repita a chamada com a mesma chave: você recebe o mesmo recurso, nunca um segundo. Como repetir com segurança

Ciclo de vida

  1. RESERVEDSUBMITTING · QUEUEDreservado
  2. SUBMITTING · QUEUEDPROCESSINGenviado
  3. PROCESSINGCOMPLETEDwithdrawal.completed
  4. PROCESSINGFAILED · UNKNOWN · MANUAL_REVIEWfalha devolve o valor

Cabeçalhos

Authorizationstringobrigatório

Bearer seguido da sua chave: gw_test_ em teste, gw_live_ em produção.

Idempotency-Keystring · 8–128obrigatório

Identificador único da tentativa, entre 8 e 128 caracteres ASCII visíveis.

Corpo da requisição

external_idstring · 1–128obrigatório
amount_centsinteger · mín. 1obrigatório

Valor inteiro positivo em centavos.

exemplo 150000 = R$ 1.500,00
pix_keyobjectobrigatório
2 campos
typestringobrigatório
CPFCNPJEMAILTELEFONECHAVE_ALEATORIA
valuestring · 3–320obrigatório
descriptionstring · 1–255obrigatório
metadataobject · até 20 chavesopcionalNOVO

Pares chave-valor seus, até 20 chaves e 2 KB. Gravados uma vez na criação e devolvidos em toda consulta e webhook. Não guarde dados pessoais aqui.

Resposta 201

Saque reservado

iduuid
external_idstring
method"PIX"
statusstring
RESERVEDSUBMITTINGQUEUEDPROCESSINGCOMPLETEDFAILEDCANCELEDUNKNOWNMANUAL_REVIEW
amount_centsinteger

Valor inteiro em centavos.

exemplo 150000 = R$ 1.500,00
fee_centsinteger

Valor inteiro em centavos.

exemplo 150 = R$ 1,50
total_debit_centsinteger

Valor inteiro em centavos.

exemplo 150150 = R$ 1.501,50
pix_keyobject
2 campos
typestring
CPFCNPJEMAILTELEFONECHAVE_ALEATORIA
maskedstring
created_atdatetime
descriptionstringNOVO
metadataobject · até 20 chavesNOVO

Pares chave-valor seus, até 20 chaves e 2 KB. Gravados uma vez na criação e devolvidos em toda consulta e webhook. Não guarde dados pessoais aqui.

recipientobject | nullNOVO

Recebedor confirmado pelo banco, quando informado.

2 campos
namestring | null
bankstring | null
end_to_end_idstring | nullNOVO

ID fim a fim do Pix enviado.

failure_reasonstring | nullNOVO

Motivo estável quando status é FAILED ou CANCELED.

destination_rejectedreturned_by_bankprocessing_failed
completed_atdatetime | nullNOVO
updated_atdatetimeNOVO

Códigos de resposta

HTTPQuando acontece
201Saque reservado
400Requisição ou cursor inválido
401Chave ausente, inválida ou sem o escopo exigido
403Saque desabilitado pela política efetiva. Saques sempre exigem verificação bancária válida e podem também exigir KYC; bloqueios operacionais e de risco continuam prevalecendo. O campo error é withdrawal_not_permitted.
409Conflito de identificador externo, idempotência ou operação em andamento
422Saldo, limite financeiro ou precificação impediu o saque. Para os canais de documento próprio, error destination_ownership_not_verified informa que a prova de titularidade não é válida.
429Limite de requisições ou limite operacional da conta excedido. Para error operation_limit_exceeded, reasons identifica os limites efetivos atingidos; Retry-After só é garantido para rate_limit_exceeded.
503Serviço temporariamente indisponível

Cada código de erro está explicado em Erros.