Skip to guide
LoyumiDocumentation
ContactProduct

REWARD GIFTS · INTEGRATION GUIDE

Gift the outcome.
Keep value governed.

Build durable invitations, verified sender and recipient decisions, private just-in-time delivery, tracked entitlement use, and exact restoration—without turning points into transferable currency.

Start with the flowOpen API contractTalk to Loyumi

LAUNCH BOUNDARY

Recipient-bound entitlement gifting—not balance transfer.

A sender redeems points for one merchant-defined reward that only the named recipient can accept and use. It has no cash value and cannot be sold, split, merged, regifted, or transferred onward.

INVITATION-FIRST WORKFLOW

Eight checkpoints from intent to final receipt.

Keep each checkpoint durably encrypted. Retry the same operation after an ambiguous response; never infer finality from a popup, callback, or webhook alone.

  1. 01

    Create a pre-value invitation

    Store personalization, delivery intent, and one to four equal-policy catalog options. No points, inventory, reward promise, or claim capability moves yet.

  2. 02

    Resolve participant readiness

    Refresh enrollment, provider verification, and cooling state. Send only an onboarding notice until the recipient is ready.

  3. 03

    Collect exact sender approval

    Resolve the live sender identity, show the immutable choice set and terms in Loyumi's hosted ceremony, and treat the browser callback only as a hint.

  4. 04

    Reserve value and inventory

    After authoritative approval, reserve the sender's eligible point lots and each finite option together. Persist the encrypted workflow checkpoint before every external effect.

  5. 05

    Deliver without a bearer reward

    Send the merchant's authenticated invitation URL. A dedicated delivery credential schedules the notice and records the provider outcome.

  6. 06

    Mint the handoff just in time

    Only after confirmed delivery and exact recipient authentication does the server mint the 60-second, one-use recipient handoff.

  7. 07

    Choose, accept, and use

    The hosted recipient experience selects one approved option. Acceptance commits value and releases unchosen holds atomically; fulfillment later records single use.

  8. 08

    Reconcile every terminal outcome

    Render finality from the authoritative receipt. Decline, cancellation, expiry, and governed reversal preserve exact restoration and evidence.

Need the concrete SDK sequence?

The product integration section shows the exact 2.2 framework calls and server/browser boundary.

Open the annotated example

PURPOSE-BOUND AUTHORITY

One credential must never become the whole gift.

Use a distinct client and stable principal for each authority. The server rejects mixed-zone credentials, including legacy stored keys.

ClientScopeMayMay not
Valuegifts:read / gifts:writeInvite, quote, reserve, and reconcileCannot impersonate a customer
Widgetwidgets:sessionsIssue short hosted customer sessionsCannot move gift value
Deliverygifts:deliverySchedule notices and attest provider outcomesCannot read or reserve value
Fulfillmentfulfillments:writeRecord entitlement use and cancellation evidenceCannot create or approve a gift
Recoverygifts:reverseExecute an approved compensating reversalIsolated from maker and checker roles

PRODUCTION CHECKLIST

Technical readiness is necessary—not sufficient.

Complete these gates with your identity, operations, finance, risk, privacy, support, and legal owners before live gifts.

  • Apply migrations 0054 and 0055 through the governed deployment path.
  • Configure distinct value, Widget, delivery, fulfillment, dispute, and recovery principals.
  • Configure Google or Apple customer authorization and complete participant linking and cooling.
  • Publish an exact-origin Widget deployment and a bounded giftable entitlement catalog.
  • Run leased maintenance, webhook verification, delivery retries, and receipt reconciliation.
  • Approve customer terms, privacy, tax, accounting, fraud, support, retention, and dispute policy.
Machine contract121 operations · 106 pathsRead OpenAPI JSON
Customer experienceInvitation, choice, wallet, useExplore the journey
Try safelyModel policies before ProductionOpen Sandbox