Auth: all routes use a benefit-provider (trusted-backend) actor. There is
no user_id in the path — the owning user is derived server-side — and the
sole authorization boundary is a strict per-order check against the order’s
benefit_provider_id.
Overview
A benefit provider order is an external purchase placed with a benefit
provider. Today the only flavour is an insurance-premium payment: the order
names an insurance_policy:<id> entity, the server derives the owning user and
the provider behind the policy, charges the premium out of the user’s PBA-backed
(HSA) account via PBA MakePayment, and tracks the outcome in wallet_txn_data.
There is no user_id in any path. On create the user is read from the named
policy’s primary_user_id; on get/sync it is read from the order row.
benefit_entity_id
Every order targets a tagged entity reference, <benefit_type>:<entity_id>:
benefit_entity_id value | Meaning |
|---|
insurance_policy:<policy-uuid> | Pay the premium for an insurance policy. The policy must exist and not be expired/rejected. |
Order lifecycle
- Create —
POST /benefit_provider_orders. The body names the entity via
benefit_entity_id. The server loads the policy, derives the owning user
(primary_user_id) and the provider (policy → benefit → provider),
authorizes the actor strictly against that provider, inserts the row with
wallet_txn_data = pending, pays the premium, then updates wallet_txn_data
to success:<payment_id> / failed.
- Get —
GET /benefit_provider_orders/{id}. Reads a single order by its
globally-unique id.
- List —
GET /benefit_provider_orders. Reads from the local DB with
optional benefit_entity_id, start_time/end_time, and limit/offset
filters; results are further filtered to the providers the actor can access.
- Sync —
PATCH /benefit_provider_orders/{id}/sync. Recovery endpoint —
re-attempts the PBA payment for an order whose create-time payment failed or
never reached PBA. Idempotent on the order id; a no-op once success.
wallet_txn_data
The PBA payment outcome, stored as a tagged string:
| Value | Meaning |
|---|
pending | Inserted, payment not yet settled. |
success:<payment_id> | Premium paid; carries PBA’s payment id. |
failed | Payment failed (and was determinate enough to mark). |
