> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xbridge.co.tz/llms.txt
> Use this file to discover all available pages before exploring further.

# BNPL (Buy Now, Pay Later)

> Hold a down-payment in escrow, finance the rest with a wallet-linked loan, disburse, then capture the down-payment.

Buy Now, Pay Later in one flow: hold the customer's down-payment in escrow, open a wallet and link a loan to it, disburse into that wallet, then capture the down-payment. This is the production-verified path.

<Note>Requires an active customer ([KYC](/recipes/kyc-onboarding)). Bearer token from [`/generate-token`](/authentication); re-token on `401`.</Note>

## Flow

```
open + approve + activate wallet
        │
        ▼
fund wallet ─▶ reserve down-payment (escrow hold)
        │
        ▼
create loan ──linkWalletId──▶ approve ─▶ disburse-to-savings (credits the wallet)
        │
        ▼
commit the down-payment hold
```

<Steps>
  <Step title="Open the customer's wallet">
    ```bash theme={null}
    WALLET=$(curl -s -X POST $BRIDGE_URL/v1/wms/wallets \
      -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
      -d "{\"customerId\":\"$CUSTOMER_ID\",\"productCode\":\"SAV2\"}")
    WALLET_ID=$(echo $WALLET | jq -r .id)

    curl -s -X POST $BRIDGE_URL/v1/wms/wallets/$WALLET_ID/approve  -H "Authorization: Bearer $TOKEN" -d '{}'
    curl -s -X POST $BRIDGE_URL/v1/wms/wallets/$WALLET_ID/activate -H "Authorization: Bearer $TOKEN" -d '{}'
    ```

    Use a published wallet product code from `GET /v1/wms/products`.
  </Step>

  <Step title="Reserve the down-payment">
    With the wallet funded (see [Collections](/recipes/collections)), place a hold for the down-payment.

    ```bash theme={null}
    RES=$(curl -s -X POST $BRIDGE_URL/v1/wms/wallets/$WALLET_ID/reserve \
      -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
      -d '{ "amount": 20000, "currency": "TZS", "reference": "BNPL-ORDER-77", "description": "Down payment" }')
    TX_ID=$(echo $RES | jq -r .transactionId)
    ```
  </Step>

  <Step title="Create the loan, linked to the wallet">
    Pass `linkWalletId` so disbursements and repayments route through this wallet.

    ```bash theme={null}
    LOAN=$(curl -s -X POST $BRIDGE_URL/v1/lms/loans \
      -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
      -d "{\"customerId\":\"$CUSTOMER_ID\",\"productCode\":\"DF-001\",\"principal\":100000,\"linkWalletId\":\"$WALLET_ID\"}")
    LOAN_ID=$(echo $LOAN | jq -r .loanId)
    ```

    <Note>Use a published loan product code from `GET /v1/lms/products`.</Note>
  </Step>

  <Step title="Approve and disburse into the wallet">
    ```bash theme={null}
    curl -s -X POST $BRIDGE_URL/v1/lms/loans/$LOAN_ID/approve \
      -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
      -d "{\"approvedOnDate\":\"$(date +%F)\"}"

    curl -s -X POST $BRIDGE_URL/v1/lms/loans/$LOAN_ID/disburse-to-savings \
      -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
      -d "{\"disbursedOnDate\":\"$(date +%F)\"}"
    ```
  </Step>

  <Step title="Capture the down-payment">
    With the goods delivered / order confirmed, commit the hold.

    ```bash theme={null}
    curl -s -X POST $BRIDGE_URL/v1/wms/transactions/$TX_ID/commit \
      -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
      -d '{ "note": "Down payment captured" }'
    ```

    If the order falls through instead, `POST /v1/wms/transactions/$TX_ID/release`.
  </Step>
</Steps>

## Manage repayments

Servicing a BNPL loan is identical to the [Lending recipe](/recipes/lending#record-repayments) — the loan is the system of record whether or not a wallet is linked. Two ways to settle each installment:

<Steps>
  <Step title="Collect from the customer">
    Trigger a mobile collection and wait for `COMPLETED` — see [Payment collections](/recipes/collections). You get back a `gatewayReference` (your `transactionId`).
  </Step>

  <Step title="Record the repayment (verified)">
    Post the collected payment against the loan. Bridge re-verifies it on the gateway before touching the ledger; idempotent on `gatewayReference`.

    ```bash theme={null}
    curl -s -X POST $BRIDGE_URL/v1/lms/loans/$LOAN_ID/submit-payment \
      -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
      -d '{ "gatewayReference": "ORDER_12345", "amount": 35000, "fspId": "CLICKPESA" }'
    ```

    Already reconciled the payment yourself? Record it directly with [`/repayments`](/recipes/lending#record-repayments) using a `receiptNumber` as the idempotency key.
  </Step>

  <Step title="Track the schedule">
    ```bash theme={null}
    curl -s $BRIDGE_URL/v1/lms/loans/$LOAN_ID/schedule -H "Authorization: Bearer $TOKEN" | jq
    ```

    Watch installments move from due to paid as repayments post.
  </Step>
</Steps>

### Auto-sweep (when available)

Because the loan is linked to a wallet, the platform can attach a **standing instruction** that sweeps each due installment straight from the wallet — so you just keep the wallet funded (via [Collections](/recipes/collections)) and never call a repayment endpoint. This auto-sweep is provisioned by the one-call `createWalletProductCode` shortcut, which is temporarily unavailable pending a platform fix. Until then, settle installments explicitly with `submit-payment` as above — same result, one extra call.

<Warning>
  Disbursed loans can't be cleanly un-disbursed. If a later step fails after disbursement, resolve forward (release the hold, contact Support) rather than rolling back the loan.
</Warning>