Eventos e dados do ciclo de aprovação, pagamento externo e conclusão dos saques manuais
Todas as moedas habilitadas para saque utilizam o método manual. Os eventos acompanham a solicitação e as decisões operacionais; criar ou aprovar um saque não executa transferência automática.
| Evento | Quando ocorre | Status resultante |
|---|---|---|
withdrawal.requested | Solicitação criada e valor bruto reservado na moeda de origem | pending |
withdrawal.approved | Administrador aprova a solicitação para pagamento manual | processing |
withdrawal.rejected | Administrador rejeita uma solicitação pendente ou aprovada ainda não concluída; a reserva retorna à mesma moeda | canceled |
withdrawal.completed | Administrador confirma que o pagamento foi realizado externamente e informa sua referência | completed |
A aprovação mantém a reserva e deixa a solicitação aguardando pagamento externo. O evento withdrawal.completed corresponde à confirmação do operador após pagar, sem chamada a um provedor de transferências. Não há aprovação automática para novas solicitações.
Os eventos withdrawal.processing e withdrawal.failed permanecem compatíveis com integrações e registros anteriores de provedores. Eles não fazem parte da execução de um novo saque Manual.
{
"id": "a1b2c3d4-e5f6-4890-abcd-ef1234567890",
"event": "withdrawal.completed",
"withdrawal": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"merchant_id": "550e8400-e29b-41d4-a716-446655440001",
"wallet_id": "550e8400-e29b-41d4-a716-446655440002",
"currency": "USD",
"method": "manual",
"provider": null,
"status": "completed",
"amount": 100000,
"fee": 1000,
"net_amount": 99000,
"recipient_snapshot": {
"type": "manual",
"details": {
"holder_name": "Example LLC",
"details": "Receber em USD. Banco Example, conta 123456, routing 000000000.",
"currency": "USD"
}
},
"failure_reason": null,
"external_id": "pagamento-externo-usd-001",
"metadata": {
"payout_execution_mode": "manual",
"manual_workflow": "same_currency",
"approved_by": "550e8400-e29b-41d4-a716-446655440003",
"approved_at": "2026-10-03T14:00:00.000Z",
"completed_by": "550e8400-e29b-41d4-a716-446655440003",
"completed_at": "2026-10-03T15:00:00.000Z",
"payment_reference": "pagamento-externo-usd-001"
},
"processed_at": "2026-10-03T14:00:00.000Z",
"completed_at": "2026-10-03T15:00:00.000Z",
"failed_at": null,
"created_at": "2026-10-02T13:55:00.000Z",
"updated_at": "2026-10-03T15:00:00.000Z"
},
"occurred_at": "2026-10-03T15:00:00.000Z"
}withdrawal| Campo | Tipo | Descrição |
|---|---|---|
id | string | ID único da solicitação |
merchant_id | string | Merchant proprietário |
wallet_id | string | Carteira de origem |
currency | string | Moeda do saque, correspondente à carteira |
method | string | Método de execução; manual nas novas solicitações |
provider | string ou null | Provedor de execução; null no método Manual |
status | string | Status atual da solicitação |
amount | number | Valor bruto inteiro em unidades mínimas da moeda |
fee | number | Taxa inteira em unidades mínimas da mesma moeda |
net_amount | number | Valor líquido inteiro (amount - fee) |
recipient_snapshot | object ou null | Dados de recebimento preservados no momento da solicitação |
failure_reason | string ou null | Motivo de falha ou rejeição |
external_id | string ou null | Referência do pagamento externo no fluxo Manual; identificador do provedor nos registros anteriores |
metadata | object ou null | Auditoria de aprovação, rejeição e conclusão, incluindo payment_reference |
processed_at | string ou null | Data/hora da aprovação para pagamento manual |
completed_at | string ou null | Data/hora em que o operador registrou a conclusão |
failed_at | string ou null | Data/hora de falha ou rejeição |
created_at | string | Criação da solicitação |
updated_at | string | Última atualização |
Todos os timestamps utilizam ISO 8601. occurred_at representa a criação da mensagem do webhook.
Os valores são expressos em unidades mínimas da moeda, sem conversão cambial. Consulte decimals nas opções de /v1/withdrawals/methods ou currency_decimals nos detalhes do saque para obter a precisão do catálogo.
Por exemplo, 100000 em uma moeda com duas casas equivale a 1000,00; com zero casas, equivale a 100000 unidades inteiras. Não aplique uma divisão fixa por 100 e não some valores de moedas diferentes. A desabilitação posterior de uma moeda não altera a moeda ou os valores de solicitações existentes.
{
"type": "manual",
"details": {
"holder_name": "Example LLC",
"details": "Instituição, conta/IBAN ou endereço e instruções para receber nesta moeda.",
"currency": "USD"
}
}O campo details contém as instruções fornecidas para análise do time da Worldfy. O snapshot não representa uma transferência executada automaticamente.
Registros anteriores podem preservar snapshots dos tipos pix ou ted, além dos dados originais de seus provedores. Consumidores devem considerar method, currency e status para interpretar a solicitação.