Saques

Saques em múltiplas moedas

Cada saque utiliza a moeda da carteira de origem. O merchant pode solicitar saques nas moedas do catálogo da Worldfy que estiverem habilitadas para sua conta. Cada moeda possui saldo disponível, valores, solicitações e histórico próprios.

Atualmente, o único método disponível é Manual. A Worldfy analisa a solicitação, realiza o pagamento fora da plataforma e registra a conclusão após efetuá-lo. A criação e a aprovação do saque não executam transferências automaticamente.

Moedas e métodos disponíveis

Consulte as opções da conta antes de solicitar um saque:

curl https://api.worldfypayments.com/v1/withdrawals/methods \
  -H "Authorization: Basic {credentials}"

{
  "data": {
    "methods": ["manual"],
    "currencies": [
      {
        "code": "USD",
        "name": "Dólar Americano",
        "symbol": "$",
        "decimals": 2,
        "wallet_id": "550e8400-e29b-41d4-a716-446655440000",
        "available_balance": 250000,
        "withdrawable_balance": 250000,
        "methods": ["manual"]
      }
    ]
  },
  "message": "Moedas e métodos de saque habilitados"
}

O exemplo mostra USD; a lista real depende da conta. Use currencies para construir as opções da sua aplicação, sem uma lista fixa de moedas. O filtro opcional ?currency=USD restringe a resposta à moeda informada.

wallet_id identifica a carteira disponível daquela moeda. Os saldos são inteiros em unidades mínimas: divida por 10 ** decimals para apresentá-los. Por exemplo, 250000 com decimals: 2 representa 2500,00; com decimals: 0, representa 250000 unidades inteiras.

Taxa de saque

Consulte a taxa para a moeda e o valor pretendidos:

curl "https://api.worldfypayments.com/v1/withdrawals/fee?currency=USD&amount_minor_units=100000" \
  -H "Authorization: Bearer {token}"

{
  "data": {
    "fee_fixed": 0,
    "fee_rate": 0.01,
    "calculated_fee": 10,
    "calculated_fee_minor_units": 1000,
    "currency": "USD",
    "currency_decimals": 2,
    "amount": 1000
  }
}

Prefira amount_minor_units, que preserva o valor inteiro. O parâmetro opcional legado amount aceita unidades da moeda; quando ambos são enviados, amount_minor_units tem prioridade. A moeda deve estar habilitada para a conta.

A taxa fixa possui uma moeda de denominação (withdrawal_fee_currency) e só se aplica a saques nessa moeda. A taxa percentual pode ser aplicada às demais moedas. Não ocorre conversão cambial.

Solicitar um saque Manual

curl -X POST https://api.worldfypayments.com/v1/withdrawals \
  -H "Authorization: Basic {credentials}" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "manual",
    "currency": "USD",
    "wallet_id": "550e8400-e29b-41d4-a716-446655440000",
    "amount": 100000,
    "idempotency_key": "saque-usd-2026-10-03-001",
    "manual_destination": {
      "holder_name": "Example LLC",
      "details": "Receber em USD. Banco Example, conta 123456, routing 000000000."
    }
  }'

Informe os dados de recebimento apropriados à moeda: instituição, conta ou IBAN, identificação do titular e instruções necessárias. Esses dados são preservados no saque para análise operacional. Eles não acionam uma integração bancária.

O valor bruto é reservado na moeda de origem ao criar a solicitação. O valor líquido a receber é amount - fee. A taxa é reconhecida quando o pagamento é concluído; se a solicitação for rejeitada antes disso, a reserva integral retorna ao saldo disponível da mesma moeda.

Idempotência

Use uma idempotency_key por intenção de saque e reutilize-a ao repetir a mesma requisição. Uma chave já utilizada pelo merchant retorna IDEMPOTENCY_CONFLICT sem criar outra solicitação.

Análise e pagamento pela Worldfy

1. A solicitação nasce com status pending.
2. O time analisa os dados no painel administrativo e aprova ou rejeita.
3. A aprovação muda o status para processing, mantendo o saldo reservado.
4. O time realiza o pagamento manualmente fora da plataforma.
5. Após pagar, o time confirma a conclusão e registra a referência externa do pagamento.

As ações administrativas usam uma sessão autorizada:

É possível rejeitar uma solicitação pendente ou aprovada que ainda não tenha sido concluída. A confirmação de pagamento exige status processing; uma solicitação concluída não pode ser concluída novamente.

Consultar saques e histórico

curl "https://api.worldfypayments.com/v1/withdrawals?currency=USD&status=completed&page=1&per_page=20" \
  -H "Authorization: Bearer {token}"

GET /v1/withdrawals/{id} retorna os detalhes. Listagem e detalhes incluem currency, currency_decimals, method, provider, valor bruto, taxa, valor líquido, destino e status. Os valores financeiros permanecem na moeda de cada registro, inclusive no histórico de moedas posteriormente desabilitadas.

Status e referência do pagamento

A conclusão registra completed_at, metadata.payment_reference e o responsável pela ação. external_id contém a referência informada pelo operador.

Para saques Manual, consulte a referência externa nos detalhes. O endpoint legado /receipt não gera comprovante bancário para esse fluxo e retorna MANUAL_PAYOUT_EXTERNAL_PROOF_REQUIRED. Comprovantes de transferências antigas por provedores mantêm seu fluxo existente.

Resumo por moeda

curl "https://api.worldfypayments.com/v1/withdrawals/summary?currency=USD" \
  -H "Authorization: Bearer {token}"

O resumo contém available_balance, withdrawable_balance, pending_count, today_amount, total_withdrawals e total_completed, além de currency e currency_decimals. O campo by_currency reúne esses dados por moeda.

Sem o filtro, use by_currency para apresentar os valores de cada moeda separadamente. As contagens podem ser agregadas; valores monetários de moedas diferentes não são somados. Quando há mais de uma moeda, os campos monetários no nível superior retornam zero e currency retorna null.