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.

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

After purchasing a policy (status PENDING), trigger an STK push to the payer’s phone:

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": "[phone]" }'

• 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.

POST /api/payments/initiate is rate limited to 10 requests/hour per organization — see Rate limits.

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 instead.

Optional: pre-quote the conversion

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:

# 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

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.

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.

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:

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.

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.

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.

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.