Branded SP Integration Flows

Overview

Branded SP tokens (partner-specific points) are designed to be fully interoperable with the universal SP token. All Branded SP are backed 1:1 by SP, which in turn is backed 1:1 by a basket of stablecoins. This unlocks native interoperability and ecosystem functionality for all reward points.

Flow 1: SP → Branded SP (Minting)

When users want to convert SP into Branded SP (partner points):

Source Platform                Spree API                    Partner Platform
     │                              │                           │
     │─── Check whitelist ─────────▶│                           │
     │    GET .../whitelist/mint/...│                           │
     │                              │                           │
     │─── Add to whitelist ────────▶│ (if needed)               │
     │    PUT .../whitelist/mint/...│                           │
     │                              │                           │
     │─── Send webhook ────────────────────────────────────────▶│
     │    { user_id, wallet, amount, txn_id }                   │
     │                              │                           │
     │◀──────────────────── Confirmation ──────────────────────│

Sequence:

1. User initiates conversion on source platform

2. Source backend verifies user's SP balance

3. Source backend locks/burns SP from user's wallet

4. Source backend calls Spree API to check whitelist status

5. If not whitelisted, source backend adds EOA to mint whitelist

6. Source backend sends webhook to partner system

7. Partner system credits user's Branded SP balance

8. Partner confirms completion via callback webhook

Processing Time: < 30 seconds

Flow 2: Branded SP → SP (Redemption)

When users want to convert Branded SP back to SP:

Partner Platform               Spree API                    User Wallet
   │                              │                              │
   │─── Create redeem ───────────▶│                              │
   │    POST .../redeem/create    │                              │
   │                              │                              │
   │                        [Delay Period]                       │
   │                              │                              │
   │─── Finalize redeem ─────────▶│                              │
   │    POST .../redeem/finalize  │────── SP ───────────────────▶│
   │                              │                              │

Sequence:

1. User initiates redemption on partner platform

2. Partner verifies user's Branded SP balance

3. Partner debits Branded SP from user's balance

4. Partner calls Spree API: POST .../redeem/create

5. Spree creates pending redemption request (enters delay period)

6. After delay period, executor calls: POST .../redeem/finalize

7. SP tokens minted/transferred to user's wallet

8. Confirmation webhook sent to partner

Processing Mode Comparison

Aspect	SP → Branded SP (Mint)	Branded SP → SP (Redeem)
Processing	Near-instant (< 30s)	Async with delay
Delay Period	None	Configurable, but needs to be redeemed by EXECUTOR authority
Confirmation	Webhook callback	Webhook callback
Cancellable	No	During delay period only