Enrollment

Enrollment is the binding action: the user is committing to a plan, money is about to move, and the HMO is about to take them on as a member. Treat the call as the moment of commitment in your UX — don't POST until the user clicks Buy.

Lifecycle#

Enrollments move through up to six states. The transitions are deterministic and you can observe each one via webhook (see Webhooks).

Enroll a member#

Returns 202 Accepted with the enrollment record in PENDING_PAYMENT state. Identity verification runs synchronously before the response — see identity in the response.

Request body

curl -X POST https://sandbox.api.pierflow.com/v1/enrollments \
  -H "Authorization: Bearer $PIERFLOW_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "plan_id": "plan_b3f9c21a",
    "quote_id": "quote_a1b2c3d4",
    "fintech_user_ref": "user_8821",
    "idempotency_key": "enr_user_8821_silver_v1",
    "identity": {
      "nin": "12345678901",
      "full_name": "Adaeze Margaret Nwosu",
      "date_of_birth": "1985-03-14",
      "sex": "F",
      "phone": "+2348012345678"
    }
  }'

Response

{
  "enrollment": {
    "id": "enr_9k3jx2p7",
    "partner_id": "ptr_fintechco",
    "provider_id": "prov_reliance",
    "plan_id": "plan_b3f9c21a",
    "quote_id": "quote_a1b2c3d4",
    "fintech_user_ref": "user_8821",
    "hmo_policy_id": null,
    "hmo_member_id": null,
    "status": "PENDING_PAYMENT",
    "effective_from": null,
    "effective_to": null,
    "wholesale_ngn": "850000",
    "markup_ngn": "150000",
    "member_pays_ngn": "1000000",
    "splits_snapshot": { /* same shape as quote.splits_snapshot */ },
    "contract_version": 1,
    "created_at": "2026-06-08T12:00:00.000Z",
    "updated_at": "2026-06-08T12:00:00.000Z"
  },
  "identity": {
    "status": "AUTO_APPROVED",
    "confidence": 95,
    "provider": "STUB"
  },
  "idempotent_replay": false
}

Confirm payment received#

Once you've debited the user's wallet for the full member_pays_ngn, call this endpoint. It moves the enrollment PENDING_PAYMENT → PENDING_HMO → ACTIVE by calling the HMO connector synchronously. Idempotent — calling twice after the enrollment is ACTIVE returns success without re-charging.

curl -X POST https://sandbox.api.pierflow.com/v1/enrollments/enr_9k3jx2p7/payment-received \
  -H "Authorization: Bearer $PIERFLOW_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "amount_ngn": "1000000", "payment_ref": "wallet_txn_42" }'

Cancel an enrollment#

Terminates the policy. If the HMO already issued one we call the connector to terminate on their side too. Cannot be undone.

curl -X POST https://sandbox.api.pierflow.com/v1/enrollments/enr_9k3jx2p7/cancel \
  -H "Authorization: Bearer $PIERFLOW_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "user_requested" }'

Retrieve an enrollment#

Returns the same shape as the create response. The list-by-ref endpoint is useful for "show this user's policies" surfaces in the fintech app.

Settlement instruction#

Every enrollment carries splits_snapshot — the same shape you saw on the quote. Use it to credit each party in your ledger:

{
  "mode": "MARKUP_FIXED",
  "wholesale_ngn": "850000",
  "markup_ngn": "150000",
  "member_pays_ngn": "1000000",
  "hmo_line": { "role": "HMO", "amount_ngn": "850000", "settlement_tag": null },
  "lines": [
    { "role": "PIERFLOW", "amount_ngn": "20000", "settlement_tag": "pierflow:platform_fee", "is_remainder": false },
    { "role": "EMR_VENDOR", "amount_ngn": "30000", "settlement_tag": "emr_vendor:default", "is_remainder": false },
    { "role": "FINTECH", "amount_ngn": "100000", "settlement_tag": "fintech:self", "is_remainder": true }
  ]
}

The HMO is paid the wholesale amount directly. The platform parties (you, Pierflow, EMR vendor) split the markup. The settlement_tag on each line is your hint about where the credit goes in your ledger — agreed during HMO onboarding.

Lifecycle events & webhooks#

Idempotency#

Pass idempotency_key on POST /v1/enrollments. Repeated calls with the same key under the same partner within 24 hours return the existing enrollment unchanged — the response carries idempotent_replay: true so you can log it. The key is any string ≤200 chars; we recommend including your user reference and the plan id to disambiguate.

Quote binding#

When you pass quote_id, the enrollment inherits the quote's frozen wholesale + markup + splits exactly. This is the safe path: the numbers the user saw at comparison are the numbers they pay. If the quote has expired (24h after creation), the call returns 404 — re-quote and show the user the new numbers before charging.