The following fields, used in various invoice-related endpoints (such as List Invoices and Get Invoice Details), are critical to understanding how cashout requests and payments are calculated for an invoice. These fields dynamically reflect cashout opportunities when an invoice is PENDING and become fixed once a cashout request is processed.
This page explains the meaning and behavior of the fee_type, fee_percentage, eligible_advance_percentage, and eligible_advance_amount fields.
Field Explanations:
fee_type
The type of fee applied when calculating the cashout for the invoice. The fee can vary based on the payer, provider, and the date the invoice is accessed.
Behavior:
- Dynamically calculated when the invoice is PENDING.
- Once the cashout request is processed, this value is fixed.
- If the payer pays the invoice or is too close to the due date, the fee type will be
NONEor null.
Example Values:
MONTHLY: The fee percentage is multply by the difference of the months between the issue date and the calculated due date.FIXED: Static fee that doesn't change over time.NONE: No fee applies if the payer pays the invoice.
eligible_advance_percentage
The percentage of the invoice can be advanced to the provider via a cashout.
Behavior:
- Dynamically calculated when the invoice is PENDING.
- Once the cashout request is processed, the advance_percentage becomes fixed.
- If the payer or the payer pays the invoice is ineligible for cashout, the percentage will be 0.
Example Values:
- 0.07: 70% of the total invoice can be advanced.
- 0.0: No advance is available (e.g., the payer pays the invoice).
eligible_advance_amount
The amount of money that can be advanced to the provider through cashout. This value is calculated based on the advance_percentage and the fee_percentage and represents the net amount after applying fees.
Behavior:
- Dynamically calculated when the invoice is PENDING.
- Once the cashout request is processed, the disbursable amount is fixed.
- If the invoice is paid by the payer or ineligible for cashout, this value will be 0.
Example Values:
- 665.00: For an invoice with a total amount of $1,000, a 70% advance percentage, and a 5% fee, $665 will be disbursed.
- 0.00: No disbursal amount (e.g., the payer pays the invoice).