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

# Payments

> Collect premiums via M-Pesa on Tier 2, or attest off-platform premium on Tier 1.

How premium reaches you depends on your [service tier](/guides/service-tiers).

| Your tier                               | How premium is collected                                                                           |
| --------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `DETERMINATION_AND_SETTLEMENT` (Tier 2) | MicroCrop triggers an M-Pesa STK push and activates the policy on confirmation.                    |
| `DETERMINATION` (Tier 1)                | **You** collect premium off-platform, then attest it with `PUT /api/policies/{policyId}/activate`. |

The gate is on the **policy**, not on your organization: `Policy.settlementMode` is frozen
at purchase, so a tier change never strands cover you already sold.

## Tier 2 — collecting a premium

```mermaid theme={null}
flowchart LR
  F[Farmer / payer] -->|M-Pesa KES| P[Payment provider]
  P -->|USDC| M[MicroCrop]
  M -->|policy created on-chain| A[ACTIVE]
```

After [purchasing a policy](/guides/policy-lifecycle#2-purchase) (status `PENDING`),
trigger an STK push to the payer's phone:

```bash theme={null}
curl -X POST https://app.microcrop.app/api/payments/initiate \
  -H "x-api-key: $KEY" -H "Content-Type: application/json" \
  -d '{ "reference": "po1…", "amount": 2500, "phoneNumber": "+254712345678" }'
```

* `reference` is the **policy id**.
* `amount` is local currency and must be at least the quoted premium.
* Returns a `transactionId` and `reference` (a transaction UUID) with `status: PENDING`.
  The payer approves the prompt on their phone.

<Note>
  `POST /api/payments/initiate` is rate limited to **10 requests/hour** per organization —
  see [Rate limits](/guides/rate-limits).
</Note>

<Warning>
  On a `DETERMINATION`-tier policy this endpoint returns **`403 TIER_NOT_ENTITLED`** before
  any transaction row is written and before any STK push is sent. Use
  [`PUT /api/policies/{policyId}/activate`](/guides/tier-1-integration#3-activate-the-policy-with-off-platform-premium)
  instead.
</Warning>

### Optional: pre-quote the conversion

```bash theme={null}
curl -X POST https://app.microcrop.app/api/payments/quote \
  -H "x-api-key: $KEY" -H "Content-Type: application/json" \
  -d '{ "amount": 2500, "fromCurrency": "KES", "toCurrency": "USDC" }'
```

### Confirming payment

On a successful charge, MicroCrop creates the policy on-chain and flips it to `ACTIVE`
automatically. Poll the transaction or the policy:

```bash theme={null}
# transaction
curl https://app.microcrop.app/api/payments/status/{reference} -H "x-api-key: $KEY"
# data.status: PENDING → COMPLETED | FAILED

# policy
curl https://app.microcrop.app/api/policies/po1…/status -H "x-api-key: $KEY"
# data.status → ACTIVE, data.premiumPaid → true
```

<Warning>
  Activation involves on-chain transactions and may lag the M-Pesa confirmation. Poll
  `policies/{id}/status` until `ACTIVE` rather than assuming immediate activation. If a
  payment succeeds but on-chain activation is delayed, it is retried automatically.
</Warning>

### Provider callbacks

The payment provider notifies MicroCrop directly at an internal, signature-verified
callback endpoint — you don't implement or call it. You observe results by polling, or
by subscribing to `policy.activated` on [webhooks](/guides/webhooks).

## Tier 1 — attesting off-platform premium

On the `DETERMINATION` tier MicroCrop never touches the premium. You collect it however
you already do — M-Pesa till, bank transfer, deduction from an input loan, cash — and
then tell MicroCrop that cover is paid for:

```bash theme={null}
curl -X PUT https://app.microcrop.app/api/policies/po1…/activate \
  -H "x-api-key: $KEY" -H "Content-Type: application/json" \
  -d '{
    "paymentReference": "SFH7TQ2K91",
    "reason": "Premium collected on the Acme till and reconciled against statement 2026-09-01"
  }'
```

Both fields are **required**: `paymentReference` is your own evidence that money was
received (3–200 chars), and `reason` justifies activating without a provider-verified
payment (10–500 chars). Requires the `policy:activate` capability, which your
organization API key holds.

This writes an audited `PREMIUM` transaction marked `manual: true` and
`providerVerified: false` — deliberately distinguishable from money a payment provider
actually settled — and flips the policy to `ACTIVE`.

It is refused if the policy is not `PENDING`, or if a provider premium payment is still
`PENDING` on it (`400 INVALID_INPUT`), so a farmer cannot be charged twice.

<Note>
  `PUT /api/policies/{policyId}/activate` is available on **both** tiers. It exists as a
  reconciliation fallback for Tier 2, and it is the normal path for Tier 1. See the
  [Tier 1 integration guide](/guides/tier-1-integration).
</Note>

## Paying the farmer

| Your tier                      | Who pays the farmer                                                                                                                                                                                                                                                    |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DETERMINATION_AND_SETTLEMENT` | MicroCrop originates and settles the payout; you observe `GET /api/payouts` and `payout.completed`.                                                                                                                                                                    |
| `DETERMINATION`                | **You do**, off-platform, off your own balance sheet. MicroCrop issues the signed determination and the amount owed in your own currency, and never moves the money. You then [report the settlement back](/guides/tier-1-integration#6-tell-microcrop-what-you-paid). |

<Warning>
  MicroCrop does **not** hold your capital in either tier. The org-facing wallet and
  reserve endpoints (`GET /me/wallet`, `POST /me/wallet/fund`, `GET /me/reserve`,
  `POST /me/reserve/deposit`, `POST /me/reserve/withdraw`) were removed with the
  non-custodial model and now return `404`. Underwriting capacity is recorded by MicroCrop
  as an attestation — see [Requirements](/requirements#the-capacity-model).
</Warning>