Skip to main content

Visa API - Complete Visa Checkout & Payment Processing

The Visa API provides comprehensive Visa card payment processing capabilities including card validation, checkout transactions, refunds, and transaction management. Built for enterprise-grade payment processing with multi-currency support, fee management, and webhook integration.

🎯 What Can You Manage?​

Your complete Visa payment ecosystem with these powerful tools:

  • Card Validation: Validate Visa cards before processing payments
  • Checkout Processing: Pull funds from Visa cards to wallets
  • Refund Management: Reverse transactions and manual refunds
  • Transaction History: Track all Visa transactions with detailed records
  • Fee Management: Dynamic fee calculation and revenue tracking
  • Webhook Integration: Real-time transaction status updates
  • Multi-Currency: Support for BRDZ currencies (USD, IDR, SGD, AUD, INR, VND)

🧩 Your Visa Payment Building Blocks​

💳 Card Validation Blocks​

  • POST /vs-checkout/visa/validate - Validate Visa card (legacy)
  • POST /vs-checkout/visa/validatecc - Validate with currency selection

🛒 Checkout Processing Blocks​

  • POST /vs-checkout/visa - Visa checkout (legacy USD only)
  • POST /vs-checkout/visacc - Visa checkout with currency selection
  • GET /vs-checkout/visa/fee - Get checkout fee percentage

💰 Refund & Transfer Blocks​

  • POST /vs-checkout/visa/refund - Reverse funds (refund)
  • POST /vs-checkout/visa/manual_refund - Manual push to card

📊 Transaction Management Blocks​

  • GET /vs-checkout/visa/reference/:reference_id - Get transaction by RRN
  • GET /vs-checkout/visa/history - Transaction history
  • POST /vs-checkout/visa/callback - Webhook callback handler

🏗️ Common Visa Payment Patterns​

Pattern 1: "I want to process a Visa payment"​

Validate card → Check fees → Process checkout → Track transaction

Use: POST /vs-checkout/visa/validatecc → GET /vs-checkout/visa/fee → POST /vs-checkout/visacc

Pattern 2: "I want to refund a transaction"​

Find transaction → Process refund → Update records

Use: GET /vs-checkout/visa/reference/:reference_id → POST /vs-checkout/visa/refund

Pattern 3: "I want to track payment history"​

Get user transactions → Review details → Generate reports

Use: GET /vs-checkout/visa/history

Pattern 4: "I want to handle webhook notifications"​

Receive callback → Process status → Update transaction

Use: POST /vs-checkout/visa/callback

💳 Card Validation Operations​

Validate Visa Card (Legacy)​

POST/api/vs-checkout/visa/validate

Validate Visa Card (Legacy - USD Only)

Validate Visa card information before processing payments. Legacy endpoint that automatically uses USD wallet. Performs card verification with address validation and merchant information.

Parameters

card_numberstringrequired

Visa card number (16 digits)

expiry_datestringrequired

Card expiry date (MMYY format)

cvvstringrequired

Card verification value (3 digits)

Request Body

{
  "card_number": "4111111111111111",
  "expiry_date": "1225",
  "cvv": "123"
}

Response

200Card validation successful
{
  "message": "Visa Card Validation Successful",
  "data": {
    "wallet_id": "wallet_456789",
    "card_last4": "1111",
    "validation_status": "APPROVED",
    "merchant_info": {
      "name": "AOL Checkout",
      "terminal_id": "AOL00001",
      "id_code": "AOL0000000001"
    },
    "address_verification": {
      "street": "801 Metro Center Blv",
      "postal_code": "94404",
      "city": "Foster City",
      "state": "CA",
      "country": "US"
    }
  }
}
400Invalid card information
{
  "error": "Card number, expiry date, CVV, street, and postal code are required."
}
401Authentication required
{
  "error": "Unauthorized: user_id missing"
}
404Wallet not found
{
  "error": "USD Wallet not found for user"
}
500Validation failed
{
  "error": "Visa Card Validation Failed",
  "details": "Invalid card number or expired card"
}

Validate Visa Card with Currency​

POST/api/vs-checkout/visa/validatecc

Validate Visa Card with Currency Selection

Validate Visa card with specific currency wallet selection. Updated endpoint that allows users to choose which currency wallet to use for the transaction.

Parameters

card_numberstringrequired

Visa card number (16 digits)

expiry_datestringrequired

Card expiry date (MMYY format)

cvvstringrequired

Card verification value (3 digits)

currencystringrequired

Target wallet currency (USD, IDR, SGD, AUD, INR, VND)

Request Body

{
  "card_number": "4111111111111111",
  "expiry_date": "1225",
  "cvv": "123",
  "currency": "IDR"
}

Response

200Card validation successful
{
  "message": "Visa Card Validation Successful",
  "data": {
    "wallet_id": "wallet_789012",
    "card_last4": "1111",
    "currency": "IDR",
    "validation_status": "APPROVED",
    "merchant_info": {
      "name": "AOL Checkout",
      "terminal_id": "AOL00001",
      "id_code": "AOL0000000001"
    }
  }
}
400Invalid parameters
{
  "error": "Card number, expiry date, CVV, and currency are required."
}
404Currency wallet not found
{
  "error": "IDR Wallet not found for user"
}

🛒 Checkout Processing Operations​

Visa Checkout (Legacy)​

POST/api/vs-checkout/visa

Visa Checkout (Legacy - USD Only)

Process Visa card payment by pulling funds from card to USD wallet. Legacy endpoint with fixed USD currency and automatic fee calculation with platform revenue tracking.

Parameters

card_numberstringrequired

Visa card number (16 digits)

expiry_datestringrequired

Card expiry date (MMYY format)

amountnumberrequired

Amount to charge from card

currency_codestringrequired

Currency code (must be USD for legacy endpoint)

Request Body

{
  "card_number": "4111111111111111",
  "expiry_date": "1225",
  "amount": 100,
  "currency_code": "USD"
}

Response

200Checkout successful
{
  "message": "Visa Checkout (Pull Funds) successful",
  "data": {
    "reference_id": "visa_1705123456789",
    "approval_code": "AUTH123456",
    "transaction_identifier": "TXN789012345",
    "card_last4": "1111",
    "amount": 100,
    "currency": "USD",
    "status": "SUCCESS_RECEIVED",
    "wallet_id": "wallet_456789",
    "platform_fee": 3,
    "net_amount": 97,
    "steps": [
      {
        "step": 1,
        "description": "Paid via Visa: $100.00"
      },
      {
        "step": 2,
        "description": "Transaction fee: $3.00"
      },
      {
        "step": 3,
        "description": "Net credited to wallet: $97.00"
      }
    ]
  }
}
400Invalid request parameters
{
  "error": "user_id, card number, expiry date, amount and currency_code are required."
}
404USD wallet not found
{
  "error": "USD Wallet not found for user"
}
500Checkout failed
{
  "error": "Visa Checkout Failed",
  "details": "Card declined or insufficient funds"
}

Visa Checkout with Currency​

POST/api/vs-checkout/visacc

Visa Checkout with Currency Selection

Process Visa card payment with specific currency wallet selection. Updated endpoint that allows charging to any supported BRDZ currency wallet with dynamic fee calculation.

Parameters

card_numberstringrequired

Visa card number (16 digits)

expiry_datestringrequired

Card expiry date (MMYY format)

amountnumberrequired

Amount to charge from card

currency_codestringrequired

Target wallet currency (USD, IDR, SGD, AUD, INR, VND)

Request Body

{
  "card_number": "4111111111111111",
  "expiry_date": "1225",
  "amount": 2500000,
  "currency_code": "IDR"
}

Response

200Checkout successful
{
  "message": "Visa Checkout (Pull Funds) successful",
  "data": {
    "reference_id": "visa_1705123456790",
    "approval_code": "AUTH789012",
    "transaction_identifier": "TXN345678901",
    "card_last4": "1111",
    "amount": 2500000,
    "currency": "IDR",
    "status": "SUCCESS_RECEIVED",
    "wallet_id": "wallet_789012",
    "platform_fee": 75000,
    "net_amount": 2425000,
    "steps": [
      {
        "step": 1,
        "description": "Paid via Visa: RP2,500,000.00"
      },
      {
        "step": 2,
        "description": "Transaction fee: RP75,000.00"
      },
      {
        "step": 3,
        "description": "Net credited to wallet: RP2,425,000.00"
      }
    ]
  }
}
404Currency wallet not found
{
  "error": "IDR Wallet not found for user"
}

Get Visa Checkout Fee​

GET/api/vs-checkout/visa/fee

Get Visa Checkout Fee Percentage

Retrieve current Visa checkout fee percentage for transaction cost calculation. Used by frontend to display fees before processing payments.

Response

200Fee percentage retrieved successfully
{
  "fee_percentage": 3
}
500Failed to retrieve fee
{
  "error": "Failed to retrieve Visa fee"
}

💰 Refund & Transfer Operations​

Visa Refund (Reverse Funds)​

POST/api/vs-checkout/visa/refund

Visa Refund via Reverse Funds

Process refund by reversing a previous Visa transaction. Returns funds from wallet back to the original Visa card using the transaction reference ID.

Parameters

amountnumberrequired

Refund amount

currency_codestringrequired

Currency code for refund (USD, IDR, SGD, AUD, INR, VND)

card_numberstringrequired

Original Visa card number

expiry_datestringrequired

Card expiry date (MMYY format)

reference_idstringrequired

Original transaction reference ID

Request Body

{
  "amount": 500000,
  "currency_code": "IDR",
  "card_number": "4111111111111111",
  "expiry_date": "1225",
  "reference_id": "visa_1705123456789"
}

Response

200Refund successful
{
  "message": "Visa Refund (Reverse) successful",
  "data": {
    "refund_id": "refund_1705123456800",
    "original_reference": "visa_1705123456789",
    "amount": 500000,
    "currency": "IDR",
    "status": "REFUND_PROCESSED",
    "refund_method": "REVERSE_FUNDS",
    "processed_at": "2024-01-15T11:00:00Z"
  }
}
400Missing required fields
{
  "error": "All refund fields are required."
}
500Refund failed
{
  "error": "Visa Refund Failed",
  "details": "Original transaction not found or already refunded"
}

Manual Refund (Push Funds)​

POST/api/vs-checkout/visa/manual_refund

Manual Refund via Push Funds

Manually push funds to a Visa card without requiring an original transaction reference. Used for compensation, bonuses, or manual refunds.

Parameters

amountnumberrequired

Amount to push to card

currency_codestringrequired

Currency code (USD, IDR, SGD, AUD, INR, VND)

card_numberstringrequired

Destination Visa card number

recipient_namestringrequired

Cardholder name

Request Body

{
  "amount": 250000,
  "currency_code": "IDR",
  "card_number": "4111111111111111",
  "recipient_name": "John Doe"
}

Response

200Manual push successful
{
  "message": "Visa Manual Push successful",
  "data": {
    "push_id": "push_1705123456801",
    "amount": 250000,
    "currency": "IDR",
    "card_last4": "1111",
    "recipient_name": "John Doe",
    "status": "PUSH_PROCESSED",
    "push_method": "MANUAL_FUNDS",
    "processed_at": "2024-01-15T11:05:00Z"
  }
}
400Missing required information
{
  "error": "Amount, currency_code, card number, and recipient name required."
}
500Push failed
{
  "error": "Visa Push Failed",
  "details": "Invalid card number or card does not support push transactions"
}

📊 Transaction Management Operations​

Get Transaction by Reference​

GET/api/vs-checkout/visa/reference/:reference_id

Get Transaction by Reference ID (RRN)

Retrieve specific Visa transaction details using the transaction reference ID or RRN (Retrieval Reference Number). Used for transaction lookup and verification.

Parameters

reference_idstringrequired

Transaction reference ID or RRN

Response

200Transaction found successfully
{
  "message": "Transaction retrieved by RRN",
  "data": {
    "id": 12345,
    "reference_id": "visa_1705123456789",
    "wallet_id": "wallet_456789",
    "user_id": 123,
    "type": "TOPUP",
    "card_last4": "1111",
    "amount": 2500000,
    "currency": "IDR",
    "status": "SUCCESS_RECEIVED",
    "approval_code": "AUTH123456",
    "transaction_identifier": "TXN789012345",
    "platform_fee": 75000,
    "net_amount": 2425000,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:31:00Z"
  }
}
404Transaction not found
{
  "error": "Transaction not found"
}
500Error retrieving transaction
{
  "error": "Error retrieving transaction",
  "details": "Database connection error"
}

Get Transaction History​

GET/api/vs-checkout/visa/history

Get Visa Transaction History

Retrieve Visa transaction history for a specific wallet. Returns paginated list of all Visa transactions with detailed information including fees and status.

Parameters

wallet_idstringrequired

Wallet ID to get transaction history for (query parameter)

Response

200Transaction history retrieved successfully
{
  "message": "Visa transaction history retrieved successfully",
  "data": [
    {
      "id": 12345,
      "type": "TOPUP",
      "card_last4": "1111",
      "amount": 2500000,
      "currency": "IDR",
      "status": "SUCCESS_RECEIVED",
      "approval_code": "AUTH123456",
      "transaction_identifier": "TXN789012345",
      "reference_id": "visa_1705123456789",
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": 12346,
      "type": "REFUND",
      "card_last4": "1111",
      "amount": 500000,
      "currency": "IDR",
      "status": "REFUND_PROCESSED",
      "approval_code": "REF789012",
      "transaction_identifier": "TXN345678901",
      "reference_id": "refund_1705123456800",
      "created_at": "2024-01-15T11:00:00Z"
    }
  ]
}
400Missing wallet ID
{
  "error": "Wallet ID is required."
}
500Failed to fetch history
{
  "error": "Failed to fetch Visa transaction history",
  "details": "Database query error"
}

Visa Callback Handler​

POST/api/vs-checkout/visa/callback

Visa Webhook Callback Handler

Handle webhook callbacks from Visa Direct for transaction status updates. Automatically updates transaction status based on Visa notifications.

Parameters

transactionIdentifierstring

Visa transaction identifier

statusstring

Updated transaction status

Request Body

{
  "transactionIdentifier": "TXN789012345",
  "status": "COMPLETED",
  "amount": 2500000,
  "currency": "IDR",
  "timestamp": "2024-01-15T10:31:00Z"
}

Response

200Callback processed successfully
{
  "message": "Callback received and processed."
}
500Callback processing failed
{
  "error": "Callback processing failed",
  "details": "Database update error"
}

🚀 Complete Visa Payment Workflows​

Workflow 1: Standard Visa Payment Processing​

// Complete Visa payment processing workflow with BRDZ currencies
async function processVisaPayment(cardData, amount, currency) {
  console.log('Starting Visa payment processing...');
  
  // Step 1: Get current fee rate
  const feeInfo = await fetch('/api/vs-checkout/visa/fee');
  const feeData = await feeInfo.json();
  console.log(`Fee rate: ${feeData.fee_percentage}%`);
  
  // Step 2: Validate card with BRDZ currency selection
  const validation = await fetch('/api/vs-checkout/visa/validatecc', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${userToken}`
    },
    body: JSON.stringify({
      card_number: cardData.number,
      expiry_date: cardData.expiry,
      cvv: cardData.cvv,
      currency: currency // IDR, SGD, AUD, INR, VND, USD
    })
  });
  
  if (!validation.ok) {
    throw new Error('Card validation failed');
  }
  
  console.log('Card validated successfully');
  
  // Step 3: Process checkout
  const checkout = await fetch('/api/vs-checkout/visacc', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${userToken}`
    },
    body: JSON.stringify({
      card_number: cardData.number,
      expiry_date: cardData.expiry,
      amount: amount,
      currency_code: currency
    })
  });
  
  const checkoutData = await checkout.json();
  console.log(`Payment processed: ${checkoutData.data.reference_id}`);
  
  return {
    reference_id: checkoutData.data.reference_id,
    amount: checkoutData.data.amount,
    fee: checkoutData.data.platform_fee,
    net_amount: checkoutData.data.net_amount
  };
}

Workflow 2: Multi-Currency Processing Examples​

// Indonesian Rupiah (IDR) Payment Example
const idrPayment = await processVisaPayment(
  { number: "4111111111111111", expiry: "1225", cvv: "123" },
  2500000.00, // RP 2.5 million
  "IDR"
);

// Singapore Dollar (SGD) Payment Example  
const sgdPayment = await processVisaPayment(
  { number: "4111111111111111", expiry: "1225", cvv: "123" },
  150.00, // S$150
  "SGD"
);

// Australian Dollar (AUD) Payment Example
const audPayment = await processVisaPayment(
  { number: "4111111111111111", expiry: "1225", cvv: "123" },
  200.00, // A$200
  "AUD"
);

// Indian Rupee (INR) Payment Example
const inrPayment = await processVisaPayment(
  { number: "4111111111111111", expiry: "1225", cvv: "123" },
  15000.00, // ₹15,000
  "INR"
);

// Vietnamese Dong (VND) Payment Example
const vndPayment = await processVisaPayment(
  { number: "4111111111111111", expiry: "1225", cvv: "123" },
  5000000.00, // ₫5 million
  "VND"
);

🎯 When to Use Which API​

Card Processing​

  • Legacy USD only: POST /vs-checkout/visa/validate → POST /vs-checkout/visa
  • Multi-currency BRDZ: POST /vs-checkout/visa/validatecc → POST /vs-checkout/visacc
  • Fee calculation: GET /vs-checkout/visa/fee

Refund Operations​

  • Transaction-based refund: POST /vs-checkout/visa/refund
  • Manual compensation: POST /vs-checkout/visa/manual_refund

Transaction Management​

  • Lookup transaction: GET /vs-checkout/visa/reference/:reference_id
  • View history: GET /vs-checkout/visa/history
  • Webhook handling: POST /vs-checkout/visa/callback

💡 Pro Tips for BRDZ Visa Integration​

Multi-Currency Support​

// BRDZ supported currencies
const BRDZ_CURRENCIES = {
  USD: { symbol: '$', decimals: 2, country: 'United States' },
  IDR: { symbol: 'RP', decimals: 2, country: 'Indonesia' },
  SGD: { symbol: 'S$', decimals: 2, country: 'Singapore' },
  AUD: { symbol: 'A$', decimals: 2, country: 'Australia' },
  INR: { symbol: '₹', decimals: 2, country: 'India' },
  VND: { symbol: '₫', decimals: 0, country: 'Vietnam' }
};

function formatCurrency(amount, currency) {
  const currencyInfo = BRDZ_CURRENCIES[currency];
  if (!currencyInfo) {
    throw new Error(`Unsupported currency: ${currency}`);
  }
  
  return `${currencyInfo.symbol}${amount.toLocaleString('en-US', {
    minimumFractionDigits: currencyInfo.decimals,
    maximumFractionDigits: currencyInfo.decimals
  })}`;
}

// Usage examples
console.log(formatCurrency(2500000, 'IDR')); // RP2,500,000.00
console.log(formatCurrency(150, 'SGD'));     // S$150.00
console.log(formatCurrency(5000000, 'VND')); // ₫5,000,000

Fee Management with Currency Support​

// BRDZ Fee Calculator with multi-currency support
class BRDZVisaFeeCalculator {
  static async calculateFees(amount, currency) {
    const feeResponse = await fetch('/api/vs-checkout/visa/fee');
    const feeData = await feeResponse.json();
    
    const feePercentage = feeData.fee_percentage / 100;
    const feeAmount = parseFloat((amount * feePercentage).toFixed(2));
    const netAmount = parseFloat((amount - feeAmount).toFixed(2));
    
    return {
      gross_amount: amount,
      fee_amount: feeAmount,
      net_amount: netAmount,
      fee_percentage: feeData.fee_percentage,
      currency: currency
    };
  }
  
  static displayFeeBreakdown(fees) {
    const currencyInfo = BRDZ_CURRENCIES[fees.currency];
    const symbol = currencyInfo ? currencyInfo.symbol : fees.currency;
    
    return {
      summary: `${symbol}${fees.gross_amount} → ${symbol}${fees.fee_amount} fee → ${symbol}${fees.net_amount} net`,
      breakdown: [
        `Gross amount: ${symbol}${fees.gross_amount}`,
        `Platform fee (${fees.fee_percentage}%): ${symbol}${fees.fee_amount}`,
        `Net amount: ${symbol}${fees.net_amount}`
      ]
    };
  }
}

// Usage
const fees = await BRDZVisaFeeCalculator.calculateFees(2500000, 'IDR');
console.log(BRDZVisaFeeCalculator.displayFeeBreakdown(fees));

🔐 Authentication & Authorization​

All Visa endpoints require authentication:

// Configure authentication for BRDZ Visa API
const headers = {
  'Content-Type': 'application/json',
  'Authorization': `Bearer ${userJWTToken}`,
  'x-api-key': `${apiKey}`
};

// User-level operations (card validation, checkout, refunds)
await fetch('/api/vs-checkout/visa/validatecc', { headers, method: 'POST', body: cardData });
await fetch('/api/vs-checkout/visacc', { headers, method: 'POST', body: checkoutData });

// Public endpoints (webhook callback, fee info)
await fetch('/api/vs-checkout/visa/fee'); // No auth required
await fetch('/api/vs-checkout/visa/callback', { method: 'POST', body: webhookData }); // No auth required

🌍 BRDZ Supported Features​

Multi-Currency Support​

  • Legacy endpoints: USD only (/visa, /visa/validate)
  • Modern endpoints: All BRDZ currencies (/visacc, /visa/validatecc)
  • Supported currencies: USD, IDR, SGD, AUD, INR, VND
  • Coverage: Indonesia, Singapore, Australia, India, Vietnam, United States

Transaction Types​

  • TOPUP: Funds pulled from card to wallet
  • REFUND: Funds returned from wallet to card
  • MANUAL_PUSH: Direct push to card without original transaction

Fee Structure​

  • Dynamic fees: Retrieved from database configuration
  • Platform revenue: Automatically tracked and logged
  • Net calculations: Fees deducted from gross amount
  • Multi-currency fees: Applied consistently across all BRDZ currencies
Currency Selection

Use the newer endpoints (/visa/validatecc and /visacc) for multi-currency support with BRDZ currencies: USD, IDR, SGD, AUD, INR, VND.

Card Data Security

Never log or store complete card numbers. Always use card_last4 for identification and ensure PCI DSS compliance in production environments.

BRDZ Coverage

BRDZ Visa processing is available in 6 countries: Indonesia, Singapore, Australia, India, Vietnam, and United States with full currency support.