KLYCoin Merchant Integration Guide

Customer Checkout
    ↓
Frontend (Web3 Wallet)
    ↓ (1) Create Charge
KLYCoin Payments API
    ↓ (2) Get Oracle Rate
Oracle Service
    ↓ (3) Sign Rate
KLYCoin Payments API
    ↓ (4) Return Signed Payload
Frontend
    ↓ (5) Execute payWithKolay()
KolayFacilitator Contract (BSC)
    ↓ (6) Emit Paid Event
Listener Service
    ↓ (7) Forward to KolayMiles
KolayMiles API
    ↓ (8) Credit Miles + Send Webhook
Merchant Backend

// lib/payment.ts
import { ethers } from 'ethers';
import KOLAY_FACILITATOR_ABI from '@/lib/abi/KolayFacilitator.json';

const CONFIG = {
  facilitator: '0x565a7Af88C3C00757a00098f3fcc6b8fB355c899',
  paymentsApi: process.env.NEXT_PUBLIC_PAYMENTS_URL || 'http://localhost:8081',
  facilitatorApi: process.env.NEXT_PUBLIC_FACILITATOR_URL || 'http://localhost:8082',
};

export async function executePayment({
  provider,
  amount,
  assetAddress,
  merchantAddress,
  receiptId
}: {
  provider: ethers.BrowserProvider;
  amount: string;
  assetAddress: string;
  merchantAddress: string;
  receiptId: string;
}) {
  const signer = await provider.getSigner();
  const payerAddress = await signer.getAddress();

  // Step 1: Get oracle-signed rate
  const prepareRes = await fetch(`${CONFIG.facilitatorApi}/api/v1/prepare-payment`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      payer: payerAddress,
      merchant: merchantAddress,
      asset: assetAddress,
      amount: ethers.parseUnits(amount, 18).toString()
    })
  });

  const { oracle, payment } = await prepareRes.json();

  // Step 2: Approve facilitator
  const erc20 = new ethers.Contract(
    assetAddress,
    ['function approve(address,uint256) external returns(bool)'],
    signer
  );

  const amountWei = ethers.parseUnits(amount, 18);
  const approveTx = await erc20.approve(CONFIG.facilitator, amountWei);
  await approveTx.wait();

  // Step 3: Execute payment
  const facilitator = new ethers.Contract(
    CONFIG.facilitator,
    KOLAY_FACILITATOR_ABI.abi,
    signer
  );

  const payTx = await facilitator.payWithKolay(
    assetAddress,
    amountWei,
    merchantAddress,
    receiptId,
    oracle.payload,
    oracle.signature
  );

  const receipt = await payTx.wait();
  
  return {
    txHash: receipt.hash,
    blockNumber: receipt.blockNumber,
    milesCredited: payment.milesCredited,
    fee: payment.fee
  };
}

// components/PayWithKolayButton.tsx
'use client';

import { useState } from 'react';
import { executePayment } from '@/lib/payment';
import toast from 'react-hot-toast';

export function PayWithKolayButton({
  amount,
  assetAddress,
  merchantAddress,
  orderId
}: {
  amount: string;
  assetAddress: string;
  merchantAddress: string;
  orderId: string;
}) {
  const [loading, setLoading] = useState(false);

  const handlePay = async () => {
    if (!window.ethereum) {
      toast.error('Please install MetaMask');
      return;
    }

    try {
      setLoading(true);

      const provider = new ethers.BrowserProvider(window.ethereum);
      
      const result = await executePayment({
        provider,
        amount,
        assetAddress,
        merchantAddress,
        receiptId: orderId
      });

      toast.success(`Payment confirmed! Miles credited: ${result.milesCredited}`);
      
      // Handle success (redirect, update UI, etc.)
      console.log('Payment result:', result);
      
    } catch (error: any) {
      console.error('Payment error:', error);
      toast.error(error.message || 'Payment failed');
    } finally {
      setLoading(false);
    }
  };

  return (
    <button
      onClick={handlePay}
      disabled={loading}
      className="px-6 py-3 bg-blue-600 text-white rounded-lg disabled:opacity-50"
    >
      {loading ? 'Processing...' : `Pay ${amount} with Kolay`}
    </button>
  );
}

import crypto from 'crypto';

function verifyWebhook(body: string, signature: string, secret: string): boolean {
  const hmac = crypto.createHmac('sha256', secret);
  const expected = `sha256=${hmac.update(body).digest('hex')}`;
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// In your webhook handler
app.post('/webhooks/payment', (req, res) => {
  const signature = req.headers['x-kolay-signature'];
  const isValid = verifyWebhook(
    JSON.stringify(req.body),
    signature,
    process.env.WEBHOOK_SECRET
  );

  if (!isValid) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Process webhook
  processPayment(req.body);
  
  res.json({ ok: true });
});