Como antecipar recebíveis e receber seus valores antes do prazo
Antecipação é o processo de receber valores de recebíveis futuros antes da data de liquidação original. Ao antecipar, uma taxa de desconto é aplicada e o valor líquido é creditado imediatamente na sua carteira.
São elegíveis para antecipação os recebíveis com status pending, data de liquidação futura e que ainda não pertencem a nenhuma antecipação.
Cada antecipação é feita em uma única moeda. Não é possível antecipar recebíveis de moedas diferentes na mesma solicitação — a API retorna o erro MIXED_CURRENCY_ANTICIPATION. A moeda é definida pelos recebíveis selecionados.
Envie os IDs dos recebíveis (ou um intervalo de datas de liquidação) para visualizar taxas e valor líquido antes de confirmar.
Confirme a solicitação com o tipo de antecipação e os recebíveis selecionados.
A antecipação é aprovada automaticamente (quando o merchant tem aprovação automática habilitada) ou analisada pela equipe Worldfy.
Após aprovação e processamento, o valor líquido é creditado na sua carteira.
| Tipo | Descrição |
|---|---|
spot | Antecipação pontual de recebíveis selecionados |
batch | Antecipação em lote de múltiplos recebíveis |
curl -X GET "https://api.worldfypayments.com/v1/anticipations?status=completed¤cy=BRL&page=1&limit=20" \
-H "Authorization: Basic {credentials}"| Parâmetro | Tipo | Descrição |
|---|---|---|
status | string | Filtrar por status |
currency | string | Filtrar por moeda (ex: BRL, USD, EUR) |
anticipation_type | string | spot ou batch |
date_from | string | Data inicial (ISO 8601) |
date_to | string | Data final (ISO 8601) |
curl -X GET https://api.worldfypayments.com/v1/anticipations/{id} \
-H "Authorization: Basic {credentials}"Antes de solicitar, simule para ver os valores:
curl -X POST https://api.worldfypayments.com/v1/anticipations/simulate \
-H "Authorization: Basic {credentials}" \
-H "Content-Type: application/json" \
-d '{
"receivable_ids": [
"550e8400-e29b-41d4-a716-446655440001",
"550e8400-e29b-41d4-a716-446655440002"
]
}'const response = await fetch('https://api.worldfypayments.com/v1/anticipations/simulate', {
method: 'POST',
headers: {
'Authorization': `Basic ${credentials}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
receivable_ids: [
'550e8400-e29b-41d4-a716-446655440001',
'550e8400-e29b-41d4-a716-446655440002',
],
}),
});O corpo aceita os seguintes campos (todos opcionais):
| Campo | Tipo | Descrição |
|---|---|---|
receivable_ids | string[] | IDs específicos a antecipar |
settlement_date_from | string | Data de liquidação inicial (AAAA-MM-DD) |
settlement_date_to | string | Data de liquidação final (AAAA-MM-DD) |
Quando receivable_ids é omitido, o sistema seleciona automaticamente os recebíveis elegíveis, opcionalmente restringidos pelo intervalo settlement_date_from/settlement_date_to.
{
"data": {
"receivables_count": 2,
"gross_amount": 20000,
"anticipation_fee": 600,
"net_amount": 19400,
"reserve_hold": 0,
"available_amount": 19400,
"fee_rate": 0.03,
"min_anticipation_amount": 5000,
"below_minimum": false
}
}| Campo | Descrição |
|---|---|
receivables_count | Quantidade de recebíveis na simulação |
gross_amount | Valor bruto total (centavos) |
anticipation_fee | Taxa total de antecipação (centavos) |
net_amount | Valor líquido (bruto - taxa) |
reserve_hold | Valor retido em reserva (centavos) |
available_amount | Valor disponível após a reserva (net_amount - reserve_hold) |
fee_rate | Taxa de antecipação aplicada (fração) |
min_anticipation_amount | Valor líquido mínimo permitido (centavos) |
below_minimum | true se o líquido estiver abaixo do mínimo |
Após confirmar os valores da simulação, solicite a antecipação:
curl -X POST https://api.worldfypayments.com/v1/anticipations \
-H "Authorization: Basic {credentials}" \
-H "Content-Type: application/json" \
-d '{
"anticipation_type": "spot",
"receivable_ids": [
"550e8400-e29b-41d4-a716-446655440001",
"550e8400-e29b-41d4-a716-446655440002"
]
}'| Campo | Tipo | Descrição |
|---|---|---|
anticipation_type | string | Obrigatório. spot ou batch |
receivable_ids | string[] | IDs específicos a antecipar (opcional) |
settlement_date_from | string | Data de liquidação inicial (opcional) |
settlement_date_to | string | Data de liquidação final (opcional) |
metadata | object | Metadados customizados (opcional) |
Assim como na simulação, quando receivable_ids é omitido o sistema seleciona os recebíveis elegíveis automaticamente, respeitando o intervalo de datas informado.
| Status | Descrição |
|---|---|
pending | Solicitação criada, aguardando aprovação |
approved | Aprovada, aguardando processamento |
processing | Em processamento |
completed | Concluída, valor creditado na carteira |
rejected | Rejeitada |
canceled | Cancelada pelo solicitante |
Antecipações com status pending podem ser canceladas:
curl -X DELETE https://api.worldfypayments.com/v1/anticipations/{id} \
-H "Authorization: Basic {credentials}"Apenas antecipações com status pending podem ser canceladas. Após a aprovação, o processo não pode ser revertido.
curl -X GET https://api.worldfypayments.com/v1/anticipations/summary \
-H "Authorization: Basic {credentials}"Retorna a contagem por status, os totais antecipados (bruto, líquido e taxas de antecipações concluídas) e os recebíveis ainda antecipáveis.