ZypfyDocs Acessar painel
Saques PIX

Criar saque PIX (cash-out)

POSThttps://api.zypfy.com/api/withdrawals/withdraw

Dispara 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

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

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

Respostas

200Saque aceito e em processamento.
  • messagestring
    exemplo: Withdrawal processed successfully.
  • withdrawalobject
    campos de withdrawal
    • transaction_idstring
      exemplo: b2c3d4e5-f6a7-8901-bcde-f23456789012
    • statusstring

      Estado do saque no momento da resposta. COMPLETED só aparece aqui para gateways síncronos; a maioria retorna PENDING e confirma por webhook.

      valores: PENDING QUEUE COMPLETED FAILED REFUNDED PARTIALLY_REFUNDED
      exemplo: PENDING
    • amountnumber (float)
      exemplo: 50
    • feenumber (float)
      exemplo: 2.5
    • totalnumber (float)

      amount + fee — valor efetivamente debitado.

      exemplo: 52.5
400Campos ausentes, key_type inválido, ou taxId obrigatório não informado.
  • messagestring
  • codestring
    valores: MISSING_RECEIVER_DOCUMENT DOCUMENT_MISMATCH QR_CODE_EXPIRED INSUFFICIENT_BALANCE WITHDRAWAL_COOLDOWN
  • withdrawalobject | null
    campos de withdrawal
    • transaction_idstring | null
    • statusstring
      exemplo: FAILED
  • retry_after_secondsinteger | null

    Presente quando code=WITHDRAWAL_COOLDOWN.

401Não autenticado.
  • messagestring

    Mensagem humana descrevendo o erro.

    exemplo: Invalid amount.
  • codestring | null

    Código opcional de erro para roteamento no seu sistema.

  • min_amountnumber (float) | null

    Presente em erros de valor abaixo do mínimo configurado.

  • max_amountnumber (float) | null

    Presente em erros de valor acima do máximo absoluto.

  • limitnumber (float) | null

    Presente em erros de limite diário por transação excedido.

  • retry_after_secondsinteger | null

    Presente em erros WITHDRAWAL_COOLDOWN / 429.

403IP não autorizado (fora da whitelist) ou valor acima do limite diário.
  • messagestring

    Mensagem humana descrevendo o erro.

    exemplo: Invalid amount.
  • codestring | null

    Código opcional de erro para roteamento no seu sistema.

  • min_amountnumber (float) | null

    Presente em erros de valor abaixo do mínimo configurado.

  • max_amountnumber (float) | null

    Presente em erros de valor acima do máximo absoluto.

  • limitnumber (float) | null

    Presente em erros de limite diário por transação excedido.

  • retry_after_secondsinteger | null

    Presente em erros WITHDRAWAL_COOLDOWN / 429.

404Usuário não encontrado.
  • messagestring

    Mensagem humana descrevendo o erro.

    exemplo: Invalid amount.
  • codestring | null

    Código opcional de erro para roteamento no seu sistema.

  • min_amountnumber (float) | null

    Presente em erros de valor abaixo do mínimo configurado.

  • max_amountnumber (float) | null

    Presente em erros de valor acima do máximo absoluto.

  • limitnumber (float) | null

    Presente em erros de limite diário por transação excedido.

  • retry_after_secondsinteger | null

    Presente em erros WITHDRAWAL_COOLDOWN / 429.

429Cooldown de saque ativo (gateway em falha anterior).
  • messagestring

    Mensagem humana descrevendo o erro.

    exemplo: Invalid amount.
  • codestring | null

    Código opcional de erro para roteamento no seu sistema.

  • min_amountnumber (float) | null

    Presente em erros de valor abaixo do mínimo configurado.

  • max_amountnumber (float) | null

    Presente em erros de valor acima do máximo absoluto.

  • limitnumber (float) | null

    Presente em erros de limite diário por transação excedido.

  • retry_after_secondsinteger | null

    Presente em erros WITHDRAWAL_COOLDOWN / 429.