hamid
93 lines
5.5 KiB
Markdown
93 lines
5.5 KiB
Markdown
# bnpl — provider-financed installments
|
||
|
||
> Client seam `client/src/services/bnpl/` · `USE_BNPL_MOCK = true` (**mock is primary**) · 9 server ops
|
||
> Last verified: 2026-07-30 against commit `d3ec723` and swagger.v1.json (2026-07-29).
|
||
|
||
The second checkout rail. **Balinyaar does not finance anything** — a provider (SnappPay, Digipay, …) pays
|
||
the platform net of its commission and carries the customer's installments itself. Card checkout is
|
||
[payment.md](payment.md).
|
||
|
||
## Endpoints
|
||
|
||
| Method | Path | Auth | Verdict |
|
||
| --- | --- | --- | --- |
|
||
| POST | `/api/v1/checkout_bnpl/eligibility` | `[Authorize]` · `sensitive` | wired |
|
||
| POST | `/api/v1/checkout_bnpl/initiate` | `[Authorize]` · `sensitive` | wired · **`Idempotency-Key`** |
|
||
| GET | `/api/v1/checkout_bnpl/{id}` | `[Authorize]` · `sensitive` | wired |
|
||
| GET | `/api/v1/checkout_bnpl/by_request/{bookingRequestId}` | `[Authorize]` · `sensitive` | wired |
|
||
| POST | `/api/v1/webhooks_bnpl/{provider}` | **anonymous** · `webhook` 120/min | server-only — the provider calls it |
|
||
| GET | `/api/v1/admin_bnpl/{id}` | admin · `sensitive` | **unwired** — no console screen |
|
||
| POST | `/api/v1/admin_bnpl/{id}/verify` | admin · `sensitive` | **unwired** |
|
||
| POST | `/api/v1/admin_bnpl/{id}/settle` | admin · `sensitive` | **unwired** |
|
||
| POST | `/api/v1/admin_bnpl/{id}/revert` | admin · `sensitive` | **unwired** — the reversal is driven from [refunds.md](refunds.md) instead |
|
||
|
||
### Phantom — 3
|
||
|
||
All three are REQ-022's deferred half. Written real-shaped so the swap is one line.
|
||
|
||
| Client call | REQ | Note |
|
||
| --- | --- | --- |
|
||
| `GET /api/v1/checkout_bnpl/options/{bookingRequestId}` | REQ-022 | The D1/D2 provider + plan list, per-plan monthly / down-payment / total |
|
||
| `GET /api/v1/checkout_bnpl/schedule/{id}` | REQ-022 | The D4 repayment schedule |
|
||
| `GET /api/v1/checkout_bnpl/wallet_installments` | REQ-024 | The D5 wallet installment list |
|
||
|
||
REQ-022 was **partially** delivered: `balinyaar` was added to the `provider_code` enum; `options` and
|
||
`schedule` were deferred. `BnplEligibilityDto` carries a single `planSummary` + `installmentCount`, not a
|
||
list of plans — which is exactly why the client needs `options`.
|
||
|
||
## The money shape
|
||
|
||
Two facts that make BNPL different from card, and both are easy to get wrong:
|
||
|
||
1. **The card payment is recorded net of the provider's fee.** The provider deducts its commission before
|
||
remitting, so the platform receives `orderAmount − bnplCommission`. `settledAmountIrr` and
|
||
`bnplCommissionIrr` are both on `BnplOrderStatusDto`, and the handler reads the **actual deducted
|
||
amount from the settlement response** — never a rate from config. `Seams:Bnpl:CommissionRate` tunes the
|
||
*mock* only.
|
||
2. **Settlement is not necessarily instant.** `settledAt` is nullable, modelling the deferred / T+1–3 /
|
||
weekly reality. A null `settledAt` on a `settled` order is normal, not an inconsistency.
|
||
|
||
`BnplStatus` is **forward-only**. A reversal is `reverted`, with `revertTransactionId`,
|
||
`revertedAmountIrr`, `revertedAt` and — when the provider returns it — `providerCommissionReversedAmount`,
|
||
which the reconciliation needs and which most providers do not send. See [refunds.md](refunds.md) for the
|
||
`bnpl_revert` refund channel.
|
||
|
||
## Shape rules the JSON does not express
|
||
|
||
- **Eligibility accepts the credit-check inputs** `{ nationalId, mobile, consent }` (REQ-023, delivered).
|
||
Consent is **required** when the KYC inquiry runs — it is a legal precondition, not a checkbox.
|
||
- **`eligibilityStatus` distinguishes three outcomes**, and the third is not a failure:
|
||
`not_eligible` (provider declined) vs `ceiling_exceeded` (order above `creditCeilingIrr` — offer card
|
||
instead) vs `eligible`. The UI must fall back to card, not show an error, on either negative.
|
||
- **`bookingId` is on the settled order** (REQ-024, confirmed) so the wallet can link an installment plan
|
||
to its booking.
|
||
- **D5 installment status is provider-reported, not ledger-derived.** The platform does not track the
|
||
customer's repayment; whatever the provider says is the truth. Never compute an installment state from
|
||
Balinyaar's own ledger.
|
||
- **`currency` is on the wire and matters.** `Seams:Bnpl:WireCurrency` is `IRR` by default; SnappPay and
|
||
Digipay speak Rial. Conversion happens **only** inside the adapter via `ICurrencyNormalizer`.
|
||
- Provider credentials proper live in the encrypted `payment_gateways.config_json`; only non-secret
|
||
connection facts (base URL, sandbox flag, merchant handle) come from `Seams:Bnpl:Providers`.
|
||
- `Seams:Bnpl:NotEligibleMobile` (`09120000099`) is the designated test mobile that returns
|
||
`not_eligible`, so the fall-back-to-card path is testable.
|
||
|
||
## Enums
|
||
|
||
| Vocabulary | Values |
|
||
| --- | --- |
|
||
| `BnplStatus` | `eligible` `token_issued` `verified` `settled` `reverted` `cancelled` `failed` |
|
||
| `BnplEligibilityStatus` | `eligible` `not_eligible` `ceiling_exceeded` |
|
||
| `ProviderCode` | `snapppay` `digipay` `tara` `torobpay` `balinyaar` |
|
||
| `BnplInstallmentStatus` *(D5, provider-reported)* | `paid` `due_soon` `upcoming` `overdue` |
|
||
| `BnplHandoffOutcome` *(client, from the return URL)* | `success` `failure` |
|
||
|
||
The first three are verified identical to `Entities/Bnpl/BnplStatus.cs`,
|
||
`BnplEligibilityStatus.cs` and `BnplProviderCodes.cs`. Note `snapppay` has **three** `p`s.
|
||
|
||
## Open REQs
|
||
|
||
| REQ | Status | Effect |
|
||
| --- | --- | --- |
|
||
| REQ-022 | partially delivered | `options` and `schedule` deferred → 3 phantom routes. D1/D2/D4 are mock-only |
|
||
| REQ-024 | partially delivered | `bookingId` confirmed present; the wallet installment list is deferred |
|