LOYUMI REWARDS EXCHANGE · DESIGN-PARTNER PILOT
Make one loyalty balance useful at the next brand.
A simple integration framework for enterprises to let a customer exchange rewards from one merchant into another—through a directional agreement, private account linking, an exact customer-confirmed quote, atomic ledger movement, and finance-ready settlement evidence.
- Merchant-authorized
- Customer-confirmed
- Bilaterally controlled
THE CUSTOMER PROBLEM
Rewards are abundant. Useful moments are scarce.
Customers accumulate value across brands, but each balance is isolated. Traditional transfer ideas often introduce a new wallet, an opaque rate, or a network nobody fully controls. Enterprises need the demand benefit of portability without surrendering economics, customer trust, or ledger truth.
A clear, intentional choice
Link two accounts with consent, see exactly what leaves and arrives, understand when new points expire, and confirm before any value is reserved.
Controlled utility for an existing balance
Choose where value can go, set the conversion and exposure ceiling, preserve source ledger lineage, and stop the corridor independently when risk changes.
Measurable, partner-funded demand
Accept only explicit terms, engage an opted-in member, issue points under your own expiration policy, and reconcile settlement against canonical exchanges.
“The customer chooses where their value becomes useful. Each merchant keeps control of the relationship, the economics, and the stop button.”
Loyumi exchange design principle
THE EXCHANGE FRAMEWORK
Seven governed steps. One simple customer moment.
The customer experiences a link, a quote, and a confirmation. Underneath, Loyumi gives product, risk, finance, support, and engineering a deterministic contract for the entire value lifecycle.
- 01
Govern the corridor
The source proposes one directional route with exact programs, environments, rates, rounding, limits, settlement currency, destination-point expiration, an effective date, and an optional end date. The destination must independently accept the identical terms hash.
No exchange before both merchants approve - 02
Link with two-sided consent
The source creates a short-lived, one-time challenge after recording consent. The customer carries that opaque challenge to the destination, where they consent again. Raw member identifiers stay inside each merchant boundary.
No shared cross-merchant customer ID - 03
Price an exact quote
Loyumi first requires source points to be an exact whole-block multiple, then applies the corridor's pinned conversion, floor/ceiling rules, limits, cap availability, and destination expiration policy. The result has a short deadline and a canonical confirmation fingerprint.
Full block, give, get, expiration, terms, deadline - 04
Confirm the transaction
For Production, the customer first establishes a cooled, durable Google or Apple identity link. Each exchange then requires a new provider authorization ceremony proving control of that linked account and an explicit top-level approval of the source points, destination points, expiration, finality policy, terms fingerprint, and deadline. A one-use assertion authorizes only that quote.
No confirmation, no reservation - 05
Reserve, then commit
Source value and monthly settlement capacity are reserved first. Commit burns the source lots and mints destination lots as one governed cross-ledger transition, preserving point-expiration lineage.
A controlled value lifecycle - 06
Settle and reconcile
The settlement obligation is calculated in integer minor currency units and attached to the exchange record. Finance records its external settlement reference while both participants retain role-appropriate state and evidence.
Operational state and money stay distinct - 07
Recover deterministically
A failed commit triggers a guarded release and an exact receipt for returned versus original-rule-expired source points. If the response is ambiguous, the SDK returns the exchange ID for polling instead of inviting a duplicate. Authorized reversals use explicit reason and settlement-reversal evidence when required.
Release, inspect, or reverse—never guess
ACCOUNT LINKING & PRIVACY
Link consented customer accounts without building a shared identity pool.
Linking is agreement-specific and consented on both sides. The customer—not a background data join—carries a one-time proof from source to destination.
Source consent
Record a durable consent reference and create a short-lived opaque challenge.
Customer carries proof
Only the one-time challenge crosses the boundary—never the source member ID.
Destination consent
Bind the destination member and its own consent reference to that challenge.
Scoped link token
Use the resulting short-lived token only for the agreed corridor and quote.
TRANSACTION-SPECIFIC AUTHORIZATION
Consent to link is not consent to move value.
The confirmation boundary is separate. A Production customer prelinks a verified Google or Apple identity, waits through a 24-hour activation period, and then completes a new provider authorization ceremony on a Loyumi top-level page before explicitly approving the exact quote. A separately zoned value credential can consume the resulting one-use assertion; no single integration credential can create the complete approval-and-movement chain.
- Source points the customer will give
- Destination points the customer will receive
- Destination-point expiration policy
- What is reversible, when, and through which exception path
- Terms fingerprint and exact quote deadline
LOYUMI SECURE EXCHANGERequired disclosure
The live surface renders only an issued quote.
No values are invented on this page. The authenticated approval ceremony must receive and disclose the runtime's immutable quote fields:
- Actual source points and destination points
- Destination expiration and finality policy
- Exact quote deadline and terms fingerprint
- Fresh provider authorization for the linked identity
- One-use assertion bound to that quote only
ATOMIC VALUE LIFECYCLE
Move value as a state machine, not a chain of hopeful API calls.
Every exchange has one canonical identity and a constrained next state. Idempotency is carried through orchestration, and recovery never relies on creating a second exchange to compensate for an unknown first one.
Return eligible source value and show any points that expired under their original rules.
Poll the exchange ID; never submit a duplicate while outcome is unknown.
Restore value through an authorized reversal with reason and settlement evidence.
ENTERPRISE CONTROLS
Both merchants keep a hand on the wheel.
The agreement is not a handshake hidden in application code. It is a versioned, canonical operating contract with independent authority, bounded exposure, participant-safe evidence, and a durable lifecycle.
Immutable economics
- Directional source and destination programs
- Independent proposal and exact-hash acceptance
- Integer conversion blocks and explicit rounding
- Pinned destination point-expiration policy
- Required effective date and optional end date
Bounded value movement
- Minimum and maximum source points per exchange
- Monthly settlement cap in ISO currency
- Reserved, committed, settled, and reversed usage
- Quote expiry bounded by corridor readiness
- No multi-hop routing or customer cash-out
Bilateral control
- Either participant can place its own pause hold
- Only the holder can clear that hold
- Reject, withdraw, resume, and terminate lifecycles
- Reason codes and evidence references
- Role-based, environment-scoped permissions
Safe execution
- Stable idempotency across quote, reserve, and commit
- Customer assertion consumed once
- Guarded release after commit failure
- Poll-by-exchange recovery for ambiguous outcomes
- Request IDs and participant-safe audit records
INDEPENDENT PAUSE HOLDS
One participant can stop the corridor. Neither can silently restart the other.
Active→ Source hold+ Destination hold→ Paused until both clear their own hold
SETTLEMENT & RECONCILIATION
Keep loyalty operations and money movement connected—but never confused.
Loyumi calculates and tracks the settlement obligation. The enterprises retain control of external funds movement, attach their settlement reference, and can reconcile the same canonical exchange from their authorized participant view.
RECONCILIATION VIEWAugust corridor window
ISO currency · integer minor unitsReserved exposureTrackedHeld, not yet committed
Committed obligationTrackedValue movement completed
Settled amountReferencedExternal settlement recorded
Reversed amountReconciledLiability restored with evidence
Available monthly capacityCap − active exposureChecked before every quote
Before launch
Agree valuation, currency, rounding, cadence, funding, breakage treatment, tax, and exception ownership.
During operation
Monitor reserved and committed exposure, settlement age, cap headroom, reversals, and participant holds.
At close
Match external settlement references to canonical exchange IDs and investigate differences before raising limits.
METRICS & ECONOMICS
Measure incrementality before you scale portability.
Exchange volume alone is not success. Define a pre-launch scorecard and compare eligible, exposed, linked, quoted, and transacting cohorts. Expand only when the corridor creates incremental customer and merchant value after reward, settlement, fraud, support, and operating costs.
Does exchange unlock action?
- Link completion rate
- Quote-to-confirm rate
- Time from quote to destination use
- Repeat exchange rate by cohort
Is the corridor incremental?
- Incremental destination conversion
- Incremental gross margin after reward cost
- Source settlement cost per activated member
- Acquisition cost versus paid channels
Can it scale safely?
- Commit success and recovery rate
- Unsettled exposure and settlement age
- Reversal rate by reason
- Support contacts per 1,000 exchanges
SOURCE CASEUseful liability relief + retained trustnet of settlement and support cost
DESTINATION CASEIncremental margin + acquired demandnet of issued reward and servicing cost
JOINT DECISIONScale only when both cases clearwith risk and settlement inside thresholds
SIMPLE TO INTEGRATE
One framework. Three surfaces. No new customer wallet.
Use the console to govern the corridor, the API or TypeScript SDK to connect merchant systems, and the Loyumi-hosted top-level surface for customer approval. Keep your existing loyalty accounts, channels, and settlement rails.
Merchant console
Propose and accept terms, prove Production readiness, inspect usage, pause independently, resume your own hold, terminate, and review outcomes.
Framework + REST primitives
Use one server-side framework for consent-bound linking, quoting, checkpointing, confirmed execution, and recovery—or compose the same typed primitives directly.
Verified approval surface
Start the exchange moment in your owned channel, then use a top-level Loyumi approval with a cooled, prelinked Google or Apple identity and a new provider authorization ceremony. Merchant styling uses approved theme tokens with validated accessible contrast.
TYPEScript FRAMEWORK · ABRIDGEDPrelink → prepare → approve → complete
Full API reference const exchange = new LoyumiPartnerExchangeFramework({
sourceValueClient,
sourceWidgetClient,
sourceIdentity: { resolve: resolveSourceMember },
destinationAccountLink: createLoyumiDestinationAccountLinkAdapter({
client: destinationClient, resolveDestinationIdentity
}),
widget: { deploymentId, origin }
});
// Before the first Production quote — prepare a customer-safe link handoff.
const linkHandoff = await exchange.prepareCustomerVerificationLink({
agreementId, sourceReference, sourceContext
});
// Merchant browser — Loyumi hosts verification; Production activates after cooling.
mountPartnerExchangeCustomerLinkFrame({
container: document.querySelector("#customer-verification")!,
handoff: linkHandoff,
onActive: () => requestExactQuote()
});
// Merchant backend — checkpoint every resumable stage.
const prepared = await exchange.prepare({
operationId, agreementId, sourceReference, sourcePoints,
sourceContext, destinationContext
}, {
onCheckpoint: saveEncryptedPreparationCheckpoint
});
await saveServerExchangeCheckpoint(prepared.checkpoint);
return prepared.customerHandoff;
// Merchant browser — Loyumi hosts the customer approval boundary.
mountPartnerExchangeFrame({
container: document.querySelector("#rewards-exchange")!,
handoff,
onConfirmed: ({ quoteId, confirmationAssertion }) =>
postToOwnBackend("/rewards-exchange/complete", {
quoteId, confirmationAssertion
})
});
// Merchant backend — credentials and checkpoint never enter the browser.
const checkpoint = await loadServerCheckpoint(quoteId);
await exchange.complete(checkpoint, confirmationAssertion);The checkpoint stays server-side; only the customer handoff reaches the hosted Widget and top-level approval. No merchant API credential or member token enters the browser. The same hosted customer-link frame supports verified unlinking; every re-link restarts Production cooling. Identity, Widget-session, and value credentials remain separately zoned. The lower-level typed API remains available for custom orchestration.
YOUR SYSTEM PROVIDESProgram IDs, member handles, consent evidence, source reference, and points
→LOYUMI GOVERNSTerms, link proof, quote, assertion, value states, caps, and evidence
→YOUR SYSTEM RECEIVESCustomer-safe progress, canonical exchange state, and settlement references
ENTERPRISE ROLLOUT
Start with one corridor. Earn the right to scale.
A large launch does not need a large first blast. Loyumi separates technical readiness from commercial authority so the teams can prove the experience, controls, recovery, and economics before increasing customer or financial exposure.
- Phase 0Signed commercial and control model
Define the governed corridor
Align customer promise, direction, economics, expiration, caps, settlement cadence, support ownership, and wind-down. Complete legal, privacy, tax, accounting, security, and fraud review before Production.
- Phase 1Joint technical acceptance evidence
Prove the integration in Sandbox
Connect the two member systems, render the exact quote, run deterministic success and failure cases, test pause and reversal, and reconcile the same exchange from both participant views.
- Phase 2Production readiness approval
Launch one bounded pilot
Use one direction, a limited eligible cohort, explicit per-exchange and monthly exposure, prefunded or otherwise agreed settlement, named operators, and a documented incident path.
- Phase 3Evidence—not volume—unlocks scale
Scale from measured economics
Expand eligibility, caps, program pairs, or the reverse direction only after incremental value, settlement quality, support load, fraud, and customer comprehension meet the agreed thresholds.
QUESTIONS ENTERPRISE TEAMS ASK
Clear answers before value moves.
Use these boundaries to align product, engineering, risk, finance, privacy, legal, and support around one operating model.
Is this a universal rewards currency?
No. Each route is a direct, directional agreement between two merchants. The customer does not receive a transferable Loyumi balance, there is no multi-hop marketplace, and every exchange uses the economics and controls of that corridor.
Do the merchants have to share customer identifiers?
No. The source and destination keep their own member identifiers. The customer carries a short-lived opaque challenge between them, and the resulting token is bound to the agreement and both consent events.
Who chooses the conversion rate and point expiration?
The merchants do. Rates, rounding, settlement value, limits, destination expiration, and any optional corridor end date are pinned in canonical terms. The destination must accept the exact terms hash before the route can activate.
Can either participant stop exchanges?
Yes. Either participant can add an independent pause hold, and the corridor remains paused until every active holder clears its own hold. The governed lifecycle also supports proposal rejection, withdrawal, and termination with evidence.
What happens if a request times out during value movement?
The orchestration uses stable idempotency keys. A failed commit leads to guarded release; an ambiguous response produces an exchange ID that the integration polls before retrying. Operators can inspect one canonical lifecycle instead of inferring from HTTP success alone.
How is customer approval separated from merchant credentials?
Production customers prelink a verified Google or Apple account, wait through a 24-hour activation period, and complete a new provider authorization ceremony on a Loyumi top-level page before approving an exact quote. Identity, customer-session, and value-movement credentials are issued in incompatible authority zones, so no single integration credential can manufacture the full flow. The merchant remains accountable for honest member enrollment and for operators who control multiple separately issued authorities.
Can a customer unlink or change the verified account?
Yes. Normal unlinking requires a new provider authorization ceremony for the exact account already linked, then invalidates open exchange approvals and quotes. For permanent provider loss, a dedicated revoke-only identity operation records recent merchant evidence and a notification reference but cannot create a replacement. The merchant remains responsible for its reviewer control and customer notice. Every re-link restarts the Production activation period; program re-enrollment cannot resurrect an old cooled link.
Does a Sandbox integration mean the corridor can go live?
No. Production is a separate decision. Commercial terms, consumer disclosures, legal and privacy review, tax and accounting treatment, fraud controls, settlement funding, reconciliation, support, and wind-down procedures must all be approved by the participating enterprises.
TURN THE PARTNERSHIP INTO A WORKING CORRIDOR
Put the first enterprise exchange in Sandbox.
Model the agreement, connect both accounts, prove the exact confirmation, exercise failure recovery, and reconcile the outcome before Production is considered.