Launch Wallets and Loyalty Programs

Launch customer wallets with balances, points, and rewards. No ledger infrastructure required.

Problem

• Customers want fast checkout without re-entering payment info
• Traditional loyalty programs lack flexibility and real-time rewards
• Gift card systems require complex infrastructure
• Marketplace sellers need instant payouts

What You’ll Build

• Customer wallets with stored balances
• Points and rewards with expiration rules
• Gift cards with redemption tracking
• Instant seller payouts

Architecture

Customer Earns → Balance Added → Wallet Updated → Customer Spends → Balance Deducted

All transactions logged with ledger entries for compliance and audit.

Steps

1. Create Wallet Types

Define wallet configuration:

const walletType = await orangepill.wallets.types.create({
  name: "customer_balance",
  currency: "COP",
  features: {
    allow_negative: false,
    require_kyc: false,
    expiration_days: null // No expiration for cash balance
  }
});

2. Issue Customer Wallets

Create wallet when customer signs up:

const wallet = await orangepill.wallets.create({
  customer_id: "cus_abc123",
  type: "customer_balance",
  initial_balance: 0,
  metadata: { source: "signup_bonus" }
});

// Optionally add signup bonus
await orangepill.wallets.credit({
  wallet_id: wallet.id,
  amount: 10000, // 10,000 COP welcome bonus
  description: "Welcome bonus"
});

3. Add Funds to Wallet

Credit wallet from purchases or campaigns:

// Customer makes purchase, earn 5% back
app.post('/webhooks/orangepill', async (req, res) => {
  const event = req.body;

  if (event.type === 'payment.succeeded') {
    const payment = event.data;
    const cashback = Math.floor(payment.amount * 0.05);

    await orangepill.wallets.credit({
      wallet_id: payment.customer.wallet_id,
      amount: cashback,
      description: `5% cashback on order ${payment.metadata.order_id}`
    });
  }

  res.sendStatus(200);
});

4. Enable Wallet Checkout

Let customers pay with wallet balance:

const payment = await orangepill.paymentRequests.create({
  amount: 50000,
  currency: "COP",
  customer: "cus_abc123",
  payment_method_types: [
    "wallet",  // Use wallet balance first
    "bre_b",   // Fallback to Bre-B if insufficient balance
    "card"     // Final fallback to card
  ]
});

// Orangepill automatically deducts from wallet if balance sufficient
// Otherwise prompts for additional payment method

5. Create Loyalty Points

Issue points with expiration:

const pointsWallet = await orangepill.wallets.types.create({
  name: "loyalty_points",
  currency: "points",
  features: {
    allow_negative: false,
    expiration_days: 365, // Points expire after 1 year
    conversion_rate: 100  // 100 points = 1 COP
  }
});

// Award points
await orangepill.wallets.credit({
  wallet_id: customer.points_wallet_id,
  amount: 500,
  description: "Referral bonus"
});

6. Launch Gift Cards

Create gift card product:

// Customer purchases gift card
const giftCard = await orangepill.giftCards.create({
  amount: 100000,
  currency: "COP",
  recipient_email: "[email protected]",
  message: "Feliz cumpleaños!",
  expiration_date: "2026-12-31"
});

// Recipient receives email with code
// Code redeemed at checkout:
await orangepill.giftCards.redeem({
  code: giftCard.code,
  amount: 50000 // Partial redemption
});

// Remaining balance: 50,000 COP

7. Track Balance History

View ledger for compliance:

const transactions = await orangepill.wallets.transactions({
  wallet_id: "wal_abc123",
  limit: 50
});

// Returns:
// { type: "credit", amount: 10000, description: "Welcome bonus" }
// { type: "debit", amount: 5000, description: "Purchase deduction" }

Code Sample

Full wallet + loyalty flow:

// Customer completes purchase
async function processPurchaseWithRewards(payment) {
  // 1. Deduct from wallet if used
  if (payment.payment_method === "wallet") {
    await orangepill.wallets.debit({
      wallet_id: payment.customer.wallet_id,
      amount: payment.amount,
      description: `Purchase ${payment.id}`
    });
  }

  // 2. Award loyalty points
  const points = Math.floor(payment.amount / 100); // 1 point per 100 COP
  await orangepill.wallets.credit({
    wallet_id: payment.customer.points_wallet_id,
    amount: points,
    description: "Purchase reward"
  });

  // 3. Check for tier upgrade
  const totalPoints = await orangepill.wallets.balance(
    payment.customer.points_wallet_id
  );

  if (totalPoints >= 10000) {
    // Upgrade to VIP
    await upgradeCustomerTier(payment.customer.id, "vip");
  }
}

Outcome

Customers check out faster with stored balance. Loyalty rewards drive repeat purchases. Gift cards expand your reach.

Typical results:

• 40-50% faster checkout with wallet balance
• 25-35% increase in repeat purchase rate with loyalty
• 20-30% new customer acquisition via gift cards
• 3x faster seller payouts with instant wallet transfers