Lanza Wallets y Programas de Lealtad

Lanza wallets para clientes con saldos, puntos y recompensas. Sin infraestructura de ledger requerida.

Problema

• Los clientes quieren un checkout rápido sin reingresar información de pago
• Los programas de lealtad tradicionales carecen de flexibilidad y recompensas en tiempo real
• Los sistemas de tarjetas regalo requieren infraestructura compleja
• Los vendedores de marketplace necesitan pagos instantáneos

Lo que construirás

• Wallets de clientes con saldos almacenados
• Puntos y recompensas con reglas de expiración
• Tarjetas regalo con seguimiento de redención
• Pagos instantáneos a vendedores

Arquitectura

Cliente gana → Se agrega saldo → Wallet actualizada → Cliente gasta → Saldo descontado

Todas las transacciones se registran con entradas de ledger para compliance y auditoría.

Pasos

1. Crea Tipos de Wallet

Define la configuración de la wallet:

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. Emite Wallets a Clientes

Crea una wallet cuando un cliente se registra:

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. Agrega Fondos a la Wallet

Acredita la wallet con compras o campañas:

// 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. Habilita Checkout con Wallet

Permite a los clientes pagar con saldo de la wallet:

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. Crea Puntos de Lealtad

Emite puntos con expiración:

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. Lanza Tarjetas Regalo

Crea un producto de tarjeta regalo:

// 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. Rastrea el Historial de Saldo

Visualiza el ledger para 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" }

Ejemplo de Código

Flujo completo de wallet + lealtad:

// 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");
  }
}

Resultado

Los clientes hacen checkout más rápido con saldo almacenado. Las recompensas de lealtad impulsan compras repetidas. Las tarjetas regalo amplían tu alcance.

Resultados típicos:

• 40-50% checkout más rápido con saldo de wallet
• 25-35% de aumento en la tasa de compra repetida con lealtad
• 20-30% de adquisición de nuevos clientes vía tarjetas regalo
• 3x pagos a vendedores más rápidos con transferencias instantáneas de wallet