Visa Module

The visa module handles Visa checkout and payment processing via partner gateway.

Import

const visa = await brdzSDK.visa;

Methods Overview

Method	Description	Auth Required	HTTP Endpoint
getTransactionByReference	Get transaction by reference ID	✅	GET /vs-checkout/visa/reference/:reference_id
validateCard	Validate Visa card (legacy)	✅	POST /vs-checkout/visa/validate
validateCardCC	Validate card with currency	✅	POST /vs-checkout/visa/validatecc
checkout	Checkout with Visa (legacy)	✅	POST /vs-checkout/visa
checkoutCC	Checkout with currency selection	✅	POST /vs-checkout/visacc
refund	Refund transaction	✅	POST /vs-checkout/visa/refund
manualRefund	Manual push to card	✅	POST /vs-checkout/visa/manual_refund
getHistory	Get transaction history	✅	GET /vs-checkout/visa/history
getFee	Get checkout fee	❌	GET /vs-checkout/visa/fee
callbackHandler	Webhook callback	❌	POST /vs-checkout/visa/callback

Card Validation Examples

Legacy Card Validation (USD Only)

// Validate Visa card - legacy USD only
const validation = await visa.validateCard({
  card_number: "4111111111111111",
  expiry_date: "1225",
  cvv: "123"
});

console.log('Validation result:', validation);
// Output: { message: "Visa Card Validation Successful", data: { wallet_id, card_last4, validation_status } }

Modern Card Validation with Currency

// Validate card with currency selection
const validationCC = await visa.validateCardCC({
  card_number: "4111111111111111",
  expiry_date: "1225", 
  cvv: "123",
  currency: "SGD"
});

console.log('Currency validation:', validationCC);
// Output: { message: "Visa Card Validation Successful", data: { wallet_id,           currency: "IDR", validation_status } }

Checkout Processing Examples

Legacy Checkout (USD Only)

// Process checkout - legacy USD only
const checkoutResult = await visa.checkout({
  card_number: "4111111111111111",
  expiry_date: "1225",
  amount: 100.00,
  currency_code: "USD"
});

console.log('Checkout successful:', checkoutResult);
// Output: { data: { reference_id, amount: 100, platform_fee: 3, net_amount: 97 } }

Modern Checkout with Currency Selection

// Process checkout with currency selection
const checkoutCC = await visa.checkoutCC({
  card_number: "4111111111111111", 
  expiry_date: "1225",
  amount: 1500000.00,
  currency_code: "IDR"
});

console.log('Multi-currency checkout:', checkoutCC);
// Output: { data: { reference_id, amount: 1500000, currency: "IDR", platform_fee: 45000, net_amount: 1455000 } }

Fee Management

// Get current checkout fee percentage
const feeInfo = await visa.getFee();
console.log('Current fee rate:', feeInfo.fee_percentage + '%');

// Calculate fees before checkout
const amount = 1000000; // IDR
const feeAmount = (amount * feeInfo.fee_percentage) / 100;
const netAmount = amount - feeAmount;

console.log(`RP${amount} → RP${feeAmount} fee → RP${netAmount} net`);

Refund Operations

Transaction-Based Refund

// Refund existing transaction
const refundResult = await visa.refund({
  amount: 500000.00,
  currency_code: "IDR", 
  card_number: "4111111111111111",
  expiry_date: "1225",
  reference_id: "visa_1705123456789"
});

console.log('Refund processed:', refundResult);
// Output: { data: { refund_id, original_reference, amount: 500000, status: "REFUND_PROCESSED" } }

Manual Push to Card

// Manual push funds to card (no original transaction required)
const manualPush = await visa.manualRefund({
  amount: 250000.00,
  currency_code: "IDR",
  card_number: "4111111111111111", 
  recipient_name: "John Doe"
});

console.log('Manual push successful:', manualPush);
// Output: { data: { push_id, amount: 250000, card_last4: "1111", status: "PUSH_PROCESSED" } }

Transaction Management

Get Transaction by Reference

// Lookup specific transaction
const transaction = await visa.getTransactionByReference("visa_1705123456789");

console.log('Transaction details:', transaction);
// Output: { data: { reference_id, amount, currency, status, approval_code, created_at } }

Get Transaction History

// Get transaction history for wallet
const history = await visa.getHistory({
  wallet_id: "wallet_456789"
});

console.log('Transaction history:', history);
// Output: { data: [{ type: "TOPUP", amount: 100, status: "SUCCESS_RECEIVED", created_at }] }

Complete Payment Workflow

async function processVisaPayment(cardData, amount, currency) {
  try {
    // Step 1: Get fee information
    const feeInfo = await visa.getFee();
    console.log(`Processing with ${feeInfo.fee_percentage}% fee`);
    
    // Step 2: Validate card with currency
    const validation = await visa.validateCardCC({
      card_number: cardData.number,
      expiry_date: cardData.expiry,
      cvv: cardData.cvv,
      currency: currency
    });
    
    if (validation.data.validation_status !== 'APPROVED') {
      throw new Error('Card validation failed');
    }
    
    // Step 3: Process checkout  
    const checkout = await visa.checkoutCC({
      card_number: cardData.number,
      expiry_date: cardData.expiry,
      amount: amount,
      currency_code: currency
    });
    
    // Step 4: Return result
    return {
      success: true,
      reference_id: checkout.data.reference_id,
      amount: checkout.data.amount,
      fee: checkout.data.platform_fee,
      net_amount: checkout.data.net_amount,
      wallet_id: validation.data.wallet_id
    };
    
  } catch (error) {
    console.error('Payment failed:', error.message);
    return {
      success: false,
      error: error.message
    };
  }
}

// Usage
const result = await processVisaPayment(
  { number: "4111111111111111", expiry: "1225", cvv: "123" },
  100.00,
  "USD"
);

console.log('Payment result:', result);

Webhook Handling

// Handle Visa webhook callbacks (server-side)
async function handleVisaWebhook(webhookData) {
  try {
    const result = await visa.callbackHandler(webhookData);
    console.log('Webhook processed:', result.message);
    
    // Additional processing based on transaction status
    if (webhookData.status === 'COMPLETED') {
      await notifyUserOfCompletion(webhookData.transactionIdentifier);
    }
    
    return result;
  } catch (error) {
    console.error('Webhook processing failed:', error.message);
    throw error;
  }
}

Error Handling

// Robust error handling for Visa operations
async function safeVisaOperation(operation) {
  try {
    return await operation();
  } catch (error) {
    if (error.message.includes('Card declined')) {
      return { error: 'card_declined', suggestion: 'Try a different card' };
    } else if (error.message.includes('Insufficient funds')) {
      return { error: 'insufficient_funds', suggestion: 'Reduce amount or add funds' };
    } else if (error.message.includes('Wallet not found')) {
      return { error: 'wallet_missing', suggestion: 'Create wallet for this currency' };
    } else if (error.message.includes('Invalid card')) {
      return { error: 'invalid_card', suggestion: 'Check card number and details' };
    } else {
      console.error('Unexpected Visa error:', error.message);
      throw error;
    }
  }
}

// Usage with error handling
const safeCheckout = await safeVisaOperation(() => 
  visa.checkoutCC({
    card_number: "4111111111111111",
    expiry_date: "1225", 
    amount: 100,
    currency_code: "USD"
  })
);

if (safeCheckout.error) {
  console.log('Error:', safeCheckout.error);
  console.log('Suggestion:', safeCheckout.suggestion);
} else {
  console.log('Success:', safeCheckout);
}

Multi-Currency Support

// Support for multiple currencies
const supportedCurrencies = ['USD', 'IDR', 'SGD', 'AUD', 'INR', 'VND'];

async function processMultiCurrencyPayment(cardData, amount, preferredCurrency) {
  // Validate currency support
  if (!supportedCurrencies.includes(preferredCurrency)) {
    throw new Error(`Currency ${preferredCurrency} not supported`);
  }
  
  // Use modern endpoints for multi-currency
  const validation = await visa.validateCardCC({
    ...cardData,
    currency: preferredCurrency
  });
  
  const checkout = await visa.checkoutCC({
    ...cardData,
    amount,
    currency_code: preferredCurrency
  });
  
  return checkout;
}

Fee Calculation Helper

// Helper function for fee calculation
class VisaFeeCalculator {
  static async calculateFees(amount) {
    const feeResponse = await visa.getFee();
    const feePercentage = feeResponse.fee_percentage / 100;
    
    return {
      gross_amount: amount,
      fee_amount: parseFloat((amount * feePercentage).toFixed(2)),
      net_amount: parseFloat((amount * (1 - feePercentage)).toFixed(2)),
      fee_percentage: feeResponse.fee_percentage
    };
  }
  
  static displayBreakdown(fees) {
    return [
      `Gross amount: $${fees.gross_amount}`,
      `Platform fee (${fees.fee_percentage}%): $${fees.fee_amount}`, 
      `Net amount: $${fees.net_amount}`
    ].join('\n');
  }
}

// Usage
const fees = await VisaFeeCalculator.calculateFees(100);
console.log(VisaFeeCalculator.displayBreakdown(fees));