Criar saque PIX (cash-out)
https://api.zypfy.com/api/withdrawals/withdrawDispara um pagamento PIX saindo do saldo do merchant para uma chave PIX de destino ou para um código Copia e Cola (QR Code estático/dinâmico).
Pré-requisitos
- O IP de origem da requisição precisa estar na whitelist do
merchant. Adicione os IPs dos seus servidores no painel antes
(
https://app.zypfy.com/credentials). - O saldo disponível (
balance) precisa ser suficiente para cobriramount + fee. Do contrário:INSUFFICIENT_BALANCE.
Duas modalidades
A) Por chave PIX (key_type = CPF, CNPJ, EMAIL, PHONE, EVP):
informe pix_key com a chave destino. Dependendo da configuração de
saque da sua conta, o taxId pode ser obrigatório quando o
key_type for EMAIL, PHONE ou EVP (em algumas configurações a chave
por si só não identifica o documento do recebedor — nesses casos, sem
taxId o saque é rejeitado com MISSING_RECEIVER_DOCUMENT). Em outras
configurações o documento é dispensado. Consulte o campo
withdraw_receiver_document_required em GET /api/accounts/balance para
saber se a sua conta exige ou não o documento do recebedor. Quando não for
obrigatório, informá-lo mesmo assim pode acelerar o processamento.
B) Copia e Cola (key_type = COPIAECOLA): informe em pix_key o
EMV completo do QR (string começando com 00020101...). O valor
amount deve bater com o do QR Code. Se você enviar taxId junto, ele
deve coincidir com o CPF/CNPJ do beneficiário original da cobrança —
caso contrário: DOCUMENT_MISMATCH.
Timeout de COPIAECOLA
QR Codes dinâmicos têm janela de 10 minutos para processamento — se
expirar antes, a transação volta com QR_CODE_EXPIRED e o saldo é
devolvido.
Status do saque
PENDING: aceito, em processamento.QUEUE: aguardando janela do provedor (congestionamento momentâneo).COMPLETED: liquidado com sucesso — webhook enviado.FAILED: rejeitado ou falhou — saldo devolvido, webhook enviado comerror_code/error_message.REFUNDED/PARTIALLY_REFUNDED: devolução bancária (raro, apenas em casos de contestação).
Idempotência
external_id é a chave de idempotência. Uma segunda chamada com o
mesmo external_id retorna a mesma transação, nunca duplica o saque.
Campos financeiros NÃO aceitos no payload
Campos calculados pelo servidor (fee, total, split_total,
split_pct, fee_percent) são rejeitados se vierem no body —
a API retorna 400 e registra tentativa de mass-assignment. Nunca
envie esses campos.
Corpo da requisição
amountnumber (float)obrigatórioValor em BRL (deve coincidir com o do QR Code quando
key_type=COPIAECOLA).exemplo:50mín. 0.01external_idstringobrigatórioIdentificador único do seu lado. Serve como idempotency key.
exemplo:saque-0001pix_keystringobrigatórioChave PIX do recebedor OU, quando
key_type=COPIAECOLA, o EMV completo do QR (string começando com00020101...).exemplo:12345678901key_typestringobrigatórioTipo da chave ou da operação:
CPF— 11 dígitos.CNPJ— 14 dígitos.EMAIL— email válido. ExigetaxId(salvo se a config de saque da sua conta dispensar — ver/api/accounts/balance).PHONE— telefone BR. ExigetaxId(salvo se a config de saque da sua conta dispensar — ver/api/accounts/balance).EVP— UUID de chave aleatória. ExigetaxId(salvo se a config de saque da sua conta dispensar — ver/api/accounts/balance).COPIAECOLA— PIX Copia e Cola (BR Code EMV). Timeout 10 min.taxIdé opcional; quando presente, deve bater com o CPF/CNPJ do beneficiário original (senão:DOCUMENT_MISMATCH).
valores:CPFCNPJEMAILPHONEEVPCOPIAECOLAexemplo:CPFtaxIdstring | nullCPF (11 dígitos) ou CNPJ (14 dígitos) do recebedor. Pode ser obrigatório quando
key_typeéEMAIL,PHONEouEVP, dependendo da configuração de saque da sua conta (consultewithdraw_receiver_document_requiredemGET /api/accounts/balance). Opcional emCPF/CNPJ(já deriva da própria chave) e emCOPIAECOLA(quando informado, é validado contra o beneficiário original do QR).exemplo:12345678901namestring | nullNome do recebedor (opcional; apenas para referência em logs).
exemplo:João Silvadescriptionstring | nullDescrição livre (máx. 140 caracteres).
exemplo:Pagamento pedido #100clientCallbackUrlstring (uri) | nullURL HTTPS do webhook específico para este saque.
exemplo:https://minhaloja.com/webhooks/withdrawalsplitarray de objectSplits internos processados na confirmação do saque (somente EMAIL).
campos de split
usernamestring (email)obrigatórioDestino do split — somente EMAIL é aceito.
exemplo:[email protected]percentageSplitstringobrigatórioPercentual do valor a repassar (em string).
exemplo:10
Respostas
200Saque aceito e em processamento.
messagestringexemplo:Withdrawal processed successfully.withdrawalobjectcampos de withdrawal
transaction_idstringexemplo:b2c3d4e5-f6a7-8901-bcde-f23456789012statusstringEstado do saque no momento da resposta.
COMPLETEDsó aparece aqui para gateways síncronos; a maioria retornaPENDINGe confirma por webhook.valores:PENDINGQUEUECOMPLETEDFAILEDREFUNDEDPARTIALLY_REFUNDEDexemplo:PENDINGamountnumber (float)exemplo:50feenumber (float)exemplo:2.5totalnumber (float)amount + fee— valor efetivamente debitado.exemplo:52.5
400Campos ausentes, key_type inválido, ou taxId obrigatório não informado.
messagestringcodestringvalores:MISSING_RECEIVER_DOCUMENTDOCUMENT_MISMATCHQR_CODE_EXPIREDINSUFFICIENT_BALANCEWITHDRAWAL_COOLDOWNwithdrawalobject | nullcampos de withdrawal
transaction_idstring | nullstatusstringexemplo:FAILED
retry_after_secondsinteger | nullPresente quando
code=WITHDRAWAL_COOLDOWN.
401Não autenticado.
messagestringMensagem humana descrevendo o erro.
exemplo:Invalid amount.codestring | nullCódigo opcional de erro para roteamento no seu sistema.
min_amountnumber (float) | nullPresente em erros de valor abaixo do mínimo configurado.
max_amountnumber (float) | nullPresente em erros de valor acima do máximo absoluto.
limitnumber (float) | nullPresente em erros de limite diário por transação excedido.
retry_after_secondsinteger | nullPresente em erros
WITHDRAWAL_COOLDOWN/ 429.
403IP não autorizado (fora da whitelist) ou valor acima do limite diário.
messagestringMensagem humana descrevendo o erro.
exemplo:Invalid amount.codestring | nullCódigo opcional de erro para roteamento no seu sistema.
min_amountnumber (float) | nullPresente em erros de valor abaixo do mínimo configurado.
max_amountnumber (float) | nullPresente em erros de valor acima do máximo absoluto.
limitnumber (float) | nullPresente em erros de limite diário por transação excedido.
retry_after_secondsinteger | nullPresente em erros
WITHDRAWAL_COOLDOWN/ 429.
404Usuário não encontrado.
messagestringMensagem humana descrevendo o erro.
exemplo:Invalid amount.codestring | nullCódigo opcional de erro para roteamento no seu sistema.
min_amountnumber (float) | nullPresente em erros de valor abaixo do mínimo configurado.
max_amountnumber (float) | nullPresente em erros de valor acima do máximo absoluto.
limitnumber (float) | nullPresente em erros de limite diário por transação excedido.
retry_after_secondsinteger | nullPresente em erros
WITHDRAWAL_COOLDOWN/ 429.
429Cooldown de saque ativo (gateway em falha anterior).
messagestringMensagem humana descrevendo o erro.
exemplo:Invalid amount.codestring | nullCódigo opcional de erro para roteamento no seu sistema.
min_amountnumber (float) | nullPresente em erros de valor abaixo do mínimo configurado.
max_amountnumber (float) | nullPresente em erros de valor acima do máximo absoluto.
limitnumber (float) | nullPresente em erros de limite diário por transação excedido.
retry_after_secondsinteger | nullPresente em erros
WITHDRAWAL_COOLDOWN/ 429.