Buy Now Pay Later (BNPL)
SPI BNPL model, fees, customer interest, and currency constraints.
BNPL lets customers pay in installments while merchants are funded according to platform rules. Logic is implemented around SPI and organization BNPL configuration.
Currency scope
BNPL is restricted to SPI-enabled flows. In practice, configuration and breakdown functions target XOF for West Africa BNPL. Other currencies are rejected by validation in the BNPL breakdown path.
Configuration
Per-organization settings include:
- Customer interest rate — interest the customer pays on top of principal.
- Installment range — min and max number of installments.
- Merchant processing fee — percentage + fixed component (risk premium vs standard cards/Mobile Money).
Inactive or missing configuration causes BNPL operations to fail fast with a clear error.
Breakdown (calculate_bnpl_breakdown)
The breakdown separates:
| Party | What is computed |
|---|---|
| Customer | Principal, total interest, total to pay, per-installment amounts. |
| Merchant | Processing fee and net received after that fee. |
| Platform | Revenue split between processing-related and financing-related components (see migration comments for exact definitions). |
Use this to display transparent quotes in checkout and invoices.
Plans and installments
Creating a plan (e.g. create_bnpl_plan_with_spi) wires the BNPL schedule to SPI and stores installment/payment-request state. Subsequent SPI webhooks advance installments until the plan completes or fails.
Operational notes
- BNPL is not interchangeable with standard card or mobile-money one-shot pricing; fees and risk assumptions differ.
- Always quote customer total including interest and merchant net after BNPL fee separately to avoid confusion.