Enrollment & Signup

Overview

Enrollment turns a phone number the cashier typed into a verified Feddi customer who can spend, in two calls: POST /enroll/initiate creates a PENDING_PROOF proto-wallet and texts a verification link, then POST /enroll/verify proves phone ownership and atomically resolves every deferred side-effect. The single rule that governs everything on this page: a LOCKED promotional grant releases only when the customer reaches VERIFIED and the merchant claim-gate is satisfied. Proof of phone is the one deliberate exception in the money model, and it is non-negotiable.

The signup flow is the acquisition flywheel. Cashback accrues on every transaction (even a cash or card purchase) as a LOCKED PromoGrant. That locked promo is the "money waiting for you" that pulls the customer into the wallet. Enrollment is how they unlock it.

Read The PENDING_PROOF Invariant before you wire any cashback or signup path. This page assumes you know it.

What this flow does

Enrollment binds three things that were previously loose:

• A phone number to a verified WalletUser (the POS-facing identity).
• The POS provider's customer-id to that WalletUser (a ProviderCustomerMap), so future orders auto-identify.
• Any LOCKED promo escrowed against the proto-wallet to spendable promo balance.

WalletUser is unique per (enterprise, normalized_phone). The same phone at a different merchant is a different customer, with a different balance, by design. This is the closed-loop isolation that keeps each merchant's stored value its own. See Identity & Credentials.

Operations

The three live signup calls are Beta: callable today, shape may still tighten. POST /claims is Beta and exists for ops re-drive (the common path runs the claim engine inline inside verify). Everything else in this tag is Planned: shape-frozen in the spec, not yet mounted, treat as not-callable until it flips.

The PENDING_PROOF signup flow

POST /enroll/initiate find-or-creates a WalletUser in PENDING_PROOF state for the merchant and normalized phone, mints a single-use signed verification link (a short-TTL JWT), and sends it by SMS. No money moves at this step and no ProviderCustomerMap is created yet. The transactional SMS needs no consent opt-in: it is triggered by the customer's own counter activity.

POST /enroll/verify decodes the signed token, guards that it is not expired, not consumed, and that the WalletUser is still PENDING_PROOF, then in one transaction flips PENDING_PROOF → VERIFIED and resolves every deferred side-effect atomically:

None of these resolve partially. If any step fails the whole flip rolls back and the link stays consumable. Domain events (wallet_user.verified, promo_grant.released, provider_customer_map.created) publish after commit, never inside the transaction.

Initiate the signup

POST /enroll/initiate opens the flow. Supply the phone the cashier entered. Pass feddi_session_id in context to hang the enrollment off the live checkout_session; omit it for a standalone signup. Idempotent on the Idempotency-Key header: a retry replays the original proto-wallet and link without re-sending a fresh SMS and without resetting the resend window.

curl -X POST https://api.feddi.io/v1/partner/enroll/initiate \
  -H "Authorization: Bearer $TERMINAL_JWT" \
  -H "Idempotency-Key: 1a2b3c4d-0001-4f9b-9d1e-1a2b3c4d5e6f" \
  -H "Content-Type: application/json" \
  -d '{
    "meta": { "partner_request_id": "1a2b3c4d-0001-4f9b-9d1e-1a2b3c4d5e6f", "occurred_at": "2026-06-05T09:40:00Z", "sent_at": "2026-06-05T09:40:01Z", "api_version": "2026-06-01" },
    "context": { "merchant_id": "11111111-1111-1111-1111-111111111111", "branch_id": "22222222-2222-2222-2222-222222222222", "terminal_id": "POS-360-0007", "cashier_id": "cashier-42", "partner_session_id": "ord-99841", "feddi_session_id": "33333333-3333-3333-3333-333333333333" },
    "phone": "+97433001122",
    "provider_customer_id": "odoo-cust-5521",
    "language": "en"
  }'

{
  "ok": true,
  "data": {
    "wallet_user_id": "wu_aa01",
    "customer_state": "pending_proof",
    "phone": "+97433001122",
    "wallet_program_id": "wp_77",
    "verification_sent": true,
    "verification_channel": "sms",
    "verification_expires_at": "2026-06-05T10:10:00Z",
    "provider_customer_map_created": false,
    "is_new": true,
    "session_id": "33333333-3333-3333-3333-333333333333"
  },
  "error": null,
  "meta": { "request_id": "req_en1", "idempotency_replayed": false, "api_version": "2026-06-01", "data_completeness_score": 55 }
}

Verify the phone

POST /enroll/verify proves phone ownership. The customer clicks the SMS link, or the cashier keys the code. Pass the signed verification_token (or the code). This is a Tier 1 money path: it releases promo. Idempotent on the Idempotency-Key header.

curl -X POST https://api.feddi.io/v1/partner/enroll/verify \
  -H "Authorization: Bearer $TERMINAL_JWT" \
  -H "Idempotency-Key: 2b3c4d5e-0002-4f9b-9d1e-1a2b3c4d5e6f" \
  -H "Content-Type: application/json" \
  -d '{
    "meta": { "partner_request_id": "2b3c4d5e-0002-4f9b-9d1e-1a2b3c4d5e6f", "occurred_at": "2026-06-05T09:45:00Z", "sent_at": "2026-06-05T09:45:01Z", "api_version": "2026-06-01" },
    "context": { "merchant_id": "11111111-1111-1111-1111-111111111111", "branch_id": "22222222-2222-2222-2222-222222222222", "terminal_id": "POS-360-0007" },
    "verification_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.proof.signature"
  }'

{
  "ok": true,
  "data": {
    "wallet_user_id": "wu_aa01",
    "customer_state": "verified",
    "verified_at": "2026-06-05T09:45:02Z",
    "wallet_id": "wal_5512",
    "wallet_program_id": "wp_77",
    "provider_customer_map_created": true,
    "balance_minor": 5000,
    "promo_balance_minor": 250,
    "currency": "QAR",
    "released_grants": [
      { "promo_grant_id": "pg_bb02", "released_minor": 250, "source": "SKU_TOPUP_BONUS" }
    ]
  },
  "error": null,
  "meta": { "request_id": "req_ev1", "idempotency_replayed": false, "api_version": "2026-06-01", "data_completeness_score": 78 }
}

Resend the verification SMS

POST /enroll/resend mints a fresh single-use token and invalidates the prior one. It is rate-limited to protect the customer from SMS bombing: max 3 sends per 24h, minimum 60s between sends. The 4th send in a window is rejected with RATE_LIMITED (HTTP 429) and error.details.retry_after_seconds. Only valid while the WalletUser is still PENDING_PROOF; a verified customer needs no link and returns VALIDATION_ERROR. Resolve the target by wallet_user_id or by phone. Transactional message, so no consent gate.

curl -X POST https://api.feddi.io/v1/partner/enroll/resend \
  -H "Authorization: Bearer $TERMINAL_JWT" \
  -H "Idempotency-Key: 3c4d5e6f-0003-4f9b-9d1e-1a2b3c4d5e6f" \
  -H "Content-Type: application/json" \
  -d '{
    "meta": { "partner_request_id": "3c4d5e6f-0003-4f9b-9d1e-1a2b3c4d5e6f", "occurred_at": "2026-06-05T09:50:00Z", "sent_at": "2026-06-05T09:50:00Z", "api_version": "2026-06-01" },
    "context": { "merchant_id": "11111111-1111-1111-1111-111111111111", "branch_id": "22222222-2222-2222-2222-222222222222", "terminal_id": "POS-360-0007" },
    "wallet_user_id": "wu_aa01"
  }'

{
  "ok": true,
  "data": {
    "wallet_user_id": "wu_aa01",
    "verification_sent": true,
    "verification_expires_at": "2026-06-05T10:20:00Z",
    "sends_used_24h": 2,
    "sends_remaining_24h": 1,
    "next_send_allowed_at": "2026-06-05T09:51:00Z"
  },
  "error": null,
  "meta": { "request_id": "req_rs1", "idempotency_replayed": false, "api_version": "2026-06-01" }
}

Claims: drive the release-engine directly

POST /claims is the explicit, idempotent driver for the claim release-engine: it converts a verified customer's LOCKED cashback-class grants into spendable promo balance. The common signup path does not need it because POST /enroll/verify invokes the same engine inline. Reach for POST /claims for ops re-drive, and for the top-up-before-register ordering where verification already happened but a later accrual needs releasing.

The engine is the day-1 riskiest money path because it must converge across event orderings. Register-before-accrual and accrual-before-register both converge to the same released balance. A claim after clawback releases 0. A duplicate claim is idempotent. Concurrent claims collapse to exactly one creditor.

Resolve the customer by wallet_user_id or an identity credential. Idempotent on the Idempotency-Key header. A claim against an unverified customer returns FORBIDDEN (HTTP 403). A claim that finds nothing claimable returns state: released with released_minor: 0.

{
  "ok": true,
  "data": {
    "claim_id": "clm_01",
    "wallet_user_id": "wu_aa01",
    "state": "released",
    "customer_state": "verified",
    "wallet_id": "wal_5512",
    "released_minor": 250,
    "promo_balance_after_minor": 250,
    "currency": "QAR",
    "released_grants": [
      { "promo_grant_id": "pg_bb02", "released_minor": 250, "source": "SKU_TOPUP_BONUS", "state": "released", "expires_at": "2026-09-05T00:00:00Z" }
    ],
    "skipped_grants": []
  },
  "error": null,
  "meta": { "request_id": "req_cl1", "idempotency_replayed": false, "api_version": "2026-06-01", "data_completeness_score": 80, "decision_trace_id": "dt_claim_7af2" }
}

GET /claims/{claimId} reads a claim's state (pending, released, expired, clawed_back) plus the released and skipped grant breakdown. It is Planned, read-only, and tenant-scoped: a claim belonging to another integration resolves to NOT_FOUND.

Consent (Planned)

POST /customer/{customerId}/consent records a marketing or personalization consent decision as an append-only ConsentRecord ledger row, not an upsert. The latest row per (customer, channel, enterprise) wins for the live gate; older rows stay for audit. Consent is per-channel (SMS, WHATSAPP, EMAIL, PUSH) and captures the exact prompt text version the customer saw.

The consent model has three tiers. The API only records the second and third:

The gate is real. A recorded opt-in is honored by the actual SMS sending gate, which reads the latest ConsentRecord. A v1-to-v2 bump in the prompt text means marketing messages stay gated until the customer re-consents under v2. A transactional message may carry light promotional language (for example, "You earned 5 SAR cashback, balance 25 SAR. Top up 50, get 10 bonus.") while staying primarily transactional. That is not marketing and needs no opt-in.

Reading identity and resolving duplicates (Planned)

These operations are Planned. Build against the shape, treat as not-callable until they flip.

GET /customer/{customerId}/identity reads the full identity record: state machine value, verified_at, resolved wallet_id and wallet_program_id, balance and released promo, the ProviderCustomerMap entries, enrollment provenance (which credential identified, when, by which branch and cashier), and any unclaimed locked grant total. A PENDING_PROOF customer surfaces only state, created-at, and the locked-grant total, because no canonical wallet exists yet.

POST /customers/{customerId}/merge folds a duplicate or recycled-SIM proto-wallet into a surviving customer. Balances and released promo sum into the survivor; LOCKED grants carry over but stay LOCKED (a merge never releases a locked grant on its own); the source's ProviderCustomerMap entries re-point to the survivor. Merge is one-way and idempotent.

POST /customer/{customerId}/attach-order (Planned, deferred to v1.5) links an already-finalized cash or card order to an identified customer after the fact, so the spend still feeds history and any order-level cashback. The cashback is derived server-side from the finalized order, never from POS-submitted money fields.

POST /customer/session/initiate (Planned) opens an identify-only checkout_session. It is an alias for POST /checkout/sessions with no basket and no tender, giving a terminal an audit-linked identification window before a sale. Prefer a full session when a basket exists.

Errors

Every error is a typed string code in error.code, never a bare HTTP number. See Idempotency & Errors and the Error Reference.

Where to go next