Dynamic Deposits

The SDK uses a Dynamic Payment Orchestrator. This means the SDK does not hardcode payment gateways like Stripe or PayPal. Instead, it fetches available methods dynamically from your backend, allowing you to add or remove payment gateways per region without updating the frontend SDK.

1. Fetching Available Methods

Before showing the deposit UI, ask the SDK what payment methods are available for the current user.

const methods = await sdk.wallet.getPaymentMethods();

methods.forEach(method => {
  console.log(`${method.name} (${method.category})`);
  console.log(`Min: ${method.minAmount}, Max: ${method.maxAmount}`);
});

Payment Method Interface:

interface PaymentMethod {
  id: string;             // e.g., 'gcash', 'stripe_card'
  category: PaymentMethodCategory; // 'CARD', 'CRYPTO', 'MOBILE_WALLET', 'UPI', etc.
  name: string;           // e.g., 'GCash', 'Credit/Debit Card'
  iconUrl?: string;
  minAmount?: number;
  maxAmount?: number;
  fields?: string[];      // Form fields required by the frontend
}

2. Initiating a Deposit

When the user selects a method and enters an amount, call initiateDeposit(). Because different payment methods have different flows, the SDK returns a PaymentIntent object. Your frontend must inspect the status to know what to do next.

const intent = await sdk.wallet.initiateDeposit({
  walletId: 'wallet_usd', // The wallet to credit
  methodId: 'upi_qr',     // Selected method ID
  amount: 50.00,
  currency: 'USD'
});

Handling the PaymentIntent Status

switch (intent.status) {
  case 'REQUIRES_REDIRECT':
    // 3D Secure, Hosted Pages, or App redirects (e.g., GCash)
    window.location.href = intent.redirectUrl;
    break;

  case 'REQUIRES_QR_SCAN':
    // Display the QR code to the user (e.g., UPI, Crypto)
    showQRCodeOnScreen(intent.qrCode);
    // Now, wait for the webhook event (see Payment Events page)
    break;

  case 'PENDING_VERIFICATION':
    // Manual Crypto or Bank Transfer. Show the wallet address.
    showWalletAddress(intent.walletAddress);
    // User must send funds and wait for backend confirmation.
    break;

  case 'COMPLETED':
    // Instant deposit (rare, usually requires async verification)
    alert('Deposit successful!');
    break;
}

3. Verifying Redirect Deposits

If the status was REQUIRES_REDIRECT, the user leaves your website. When they return (usually to a specific Return URL), you must call verifyDeposit() to finalize the transaction and update the user's balance.

// On the Return URL page (e.g., /deposit-success)
const pendingTxId = localStorage.getItem('pending_deposit_tx');

if (pendingTxId) {
  const finalIntent = await sdk.wallet.verifyDeposit(pendingTxId);
  
  if (finalIntent.status === 'COMPLETED') {
    alert('Deposit successful! Balance updated.');
  } else {
    alert('Deposit is still processing or failed.');
  }
}