Entenda a agenda de recebíveis e como acompanhar seus pagamentos futuros
Recebíveis representam os valores que você tem a receber de cobranças processadas. Cada cobrança capturada gera um ou mais recebíveis, dependendo do método de pagamento e do número de parcelas.
Por exemplo, uma cobrança de R$ 300,00 em 3x no cartão de crédito gera 3 recebíveis de R$ 100,00 cada, com datas de liquidação diferentes.
Cada recebível é registrado em uma moeda (currency, ex: BRL, USD, EUR), herdada da cobrança que o originou. Use o filtro currency para restringir a consulta a uma moeda específica.
| Status | Descrição |
|---|---|
pending | Recebível criado, aguardando processamento |
scheduled | Agendado para liquidação na data prevista |
settled | Liquidado (valor creditado na carteira) |
anticipated | Antecipado (recebido antes da data original) |
canceled | Cancelado (estorno ou chargeback) |
failed | Falha na liquidação |
curl -X GET "https://api.worldfypayments.com/v1/receivables?status=scheduled¤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) |
payment_method | string | Filtrar por método de pagamento (credit_card, debit_card, pix, boleto) |
settlement_date_from | string | Data de liquidação inicial (ISO 8601) |
settlement_date_to | string | Data de liquidação final (ISO 8601) |
charge_id | string | Filtrar por cobrança específica |
curl -X GET https://api.worldfypayments.com/v1/receivables/{id} \
-H "Authorization: Basic {credentials}"{
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"charge_id": "660e8400-e29b-41d4-a716-446655440001",
"charge_external_id": "ext-abc-123",
"currency": "BRL",
"owner_type": "merchant",
"owner_id": "m1e2r3c4-h5a6-7890-ntid-000000000001",
"merchant_id": "m1e2r3c4-h5a6-7890-ntid-000000000001",
"payment_method": "credit_card",
"installment_number": 1,
"total_installments": 3,
"gross_amount": "10000",
"merchant_fee": "350",
"anticipation_fee": "0",
"net_amount": "9650",
"status": "scheduled",
"captured_at": "2026-02-10T14:30:00.000Z",
"original_settlement_date": "2026-03-15",
"settlement_date": "2026-03-15",
"settled_at": null,
"anticipation_id": null,
"created_at": "2026-02-10T14:30:00.000Z",
"updated_at": "2026-02-10T14:30:00.000Z"
}
}Os valores monetários são retornados como strings representando o total em centavos. As datas de liquidação (settlement_date, original_settlement_date) são retornadas no formato AAAA-MM-DD.
Cada recebível contém os seguintes valores monetários (strings em centavos):
| Campo | Descrição |
|---|---|
gross_amount | Valor bruto da parcela |
merchant_fee | Taxa cobrada pela Worldfy sobre a parcela |
anticipation_fee | Taxa de antecipação (preenchida quando o recebível é antecipado) |
net_amount | Valor líquido (bruto - taxas) |
Para ter uma visão geral dos seus recebíveis:
curl -X GET "https://api.worldfypayments.com/v1/receivables/summary?date_from=2026-01-01&date_to=2026-12-31" \
-H "Authorization: Basic {credentials}"| Parâmetro | Tipo | Descrição |
|---|---|---|
date_from | string | Data de liquidação inicial (ISO 8601) |
date_to | string | Data de liquidação final (ISO 8601) |
O resumo agrupa os recebíveis por status e retorna os totais consolidados:
{
"data": {
"byStatus": [
{ "status": "pending", "count": 0, "total_gross_amount": "0", "total_net_amount": "0" },
{ "status": "scheduled", "count": 45, "total_gross_amount": "940000", "total_net_amount": "900000" },
{ "status": "settled", "count": 30, "total_gross_amount": "545000", "total_net_amount": "525000" },
{ "status": "anticipated", "count": 5, "total_gross_amount": "80000", "total_net_amount": "75000" },
{ "status": "canceled", "count": 0, "total_gross_amount": "0", "total_net_amount": "0" },
{ "status": "failed", "count": 0, "total_gross_amount": "0", "total_net_amount": "0" }
],
"totals": {
"total_count": 80,
"total_gross_amount": "1565000",
"total_net_amount": "1500000",
"pending_amount": "900000",
"settled_amount": "525000"
}
}
}Campo (em totals) | Descrição |
|---|---|
total_count | Quantidade total de recebíveis no período |
total_gross_amount | Soma dos valores brutos (string, centavos) |
total_net_amount | Soma dos valores líquidos (string, centavos) |
pending_amount | Valor líquido de recebíveis pending + scheduled |
settled_amount | Valor líquido de recebíveis settled |
Use os filtros de data para consultar a agenda de recebíveis futuros e planejar seu fluxo de caixa.