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

# Payment reviews

> Handle payment uncertainty and policy thresholds without duplicate provider requests.

NorthFond pauses a checkout when it cannot safely determine whether another provider request should be sent or when the payment crosses a configured manual-review threshold. The payment enters `review_required` and no automatic retry is performed.

## Safe decision flow

<Steps>
  <Step title="Review required">The business receives an in-dashboard notification and, when subscribed, a `payment_intent.review_required` webhook.</Step>
  <Step title="Operator decision">An authorized NorthFond administrator inspects the provider reference, failure context, amount, customer, and audit trail.</Step>
  <Step title="Approve or reject">Approval changes the checkout to `approved`. Rejection changes it to `failed`. Every decision requires a reason and is written to the audit log.</Step>
  <Step title="Customer continuation">After approval, the customer returns to the original checkout and selects **Continue with M-Pesa**. Only this customer action creates a fresh quote and payment prompt.</Step>
</Steps>

## Guarantees

* Approval itself never sends an STK prompt.
* Review decisions are atomic and cannot be applied twice.
* Resume attempts are rate limited.
* A quote is consumed once.
* Treasury settlement is idempotent.
* Reviews have an expiry time and fail closed after expiry.

## Review events

| Event                            | Meaning                                                                    |
| -------------------------------- | -------------------------------------------------------------------------- |
| `payment_intent.review_required` | The checkout is paused for an operator decision.                           |
| `payment_intent.approved`        | The customer may return and continue. No payment prompt has been sent yet. |
| `payment_intent.resumed`         | The customer continued and a fresh provider request began.                 |
| `payment_intent.rejected`        | The review was rejected and the checkout cannot continue.                  |
| `payment_intent.completed`       | Payment and treasury credit completed.                                     |

Reviews approaching expiry appear in operator health metrics and produce a single merchant reminder. Never build an automated provider retry around `review_required`.