Overview & Features

Altima Pay is a modern, secure payment gateway built on Merchant Warrior PayFrame. It provides full multi-tenant support, enabling a single deployment to serve unlimited organisations with completely separate configurations, merchant accounts, and branding.

Live Demo & Tenant Reference

The application is deployed at:

Key Features

Multi-Tenant Architecture

The application supports multiple tenant configurations without separate builds, enabling both hosted multi-tenancy and self-hosting scenarios with complete configuration isolation.

Tenant Detection & Configuration Flow

Tenant Detection Methods

The system resolves the active tenant using the following priority order. The first method that returns a valid tenant ID wins.

Detection Examples

# URL Parameter (highest priority)
https://paymentgateway.com/?tenant=altima-community&amount=50.00

# Path Method
https://paymentgateway.com/tenant/charity-donations/?amount=25.00

# Subdomain Method
https://altima.paymentgateway.com/?amount=100.00

# Self-Hosting (environment variable)
https://payments.altima-community.org/?amount=75.00

Tenant Configuration Structure

Each tenant can have completely separate settings across four areas:

Tenant Configuration Example

'altima-community': {
  tenantId: 'altima-community',
  tenantName: 'Altima Community',
  merchantWarrior: {
    merchantUUID: import.meta.env.VITE_ALTIMA_MW_MERCHANT_UUID,
    apiKey:       import.meta.env.VITE_ALTIMA_MW_API_KEY,
    passphrase:   import.meta.env.VITE_ALTIMA_MW_PASSPHRASE,
    payframeJsUrl:import.meta.env.VITE_ALTIMA_MW_PAYFRAME_JS_URL,
    payframeUrl:  import.meta.env.VITE_ALTIMA_MW_PAYFRAME_URL,
    submitUrl:    import.meta.env.VITE_ALTIMA_MW_SUBMIT_URL,
  },
  email: {
    serviceId:  import.meta.env.VITE_ALTIMA_EMAILJS_SERVICE_ID,
    adminEmail: 'admin@altima-community.org',
    // ... template IDs
  },
  branding: {
    companyName:    'Altima Community',
    primaryColor:   '#059669',
    secondaryColor: '#047857',
    supportEmail:   'support@altima-community.org',
  },
  features: {
    vatuConverter:     true,
    emailNotifications: true,
    streamlinedFlow:   true,
    customReturnUrls:  true,
  }
}

Adding a New Tenant — 3 Steps

'your-organisation': {
  tenantId:   'your-organisation',
  tenantName: 'Your Organisation Name',
  merchantWarrior: {
    merchantUUID: import.meta.env.VITE_YOUR_MW_MERCHANT_UUID || 'test_fallback',
    apiKey:       import.meta.env.VITE_YOUR_MW_API_KEY       || 'test_fallback',
    passphrase:   import.meta.env.VITE_YOUR_MW_PASSPHRASE    || 'test_fallback',
    // ... other MW config
  },
  branding: {
    companyName:  'Your Organisation',
    primaryColor: '#007b8f',
    supportEmail: 'support@yourorganisation.com',
  },
  features: {
    vatuConverter:      false,
    emailNotifications: true,
    streamlinedFlow:    true,
    customReturnUrls:   true,
  }
}

# Your Organisation — add to deployment platform environment
VITE_YOUR_MW_MERCHANT_UUID=live_merchant_uuid
VITE_YOUR_MW_API_KEY=live_api_key
VITE_YOUR_MW_PASSPHRASE=live_passphrase
VITE_YOUR_MW_PAYFRAME_JS_URL=https://secure.merchantwarrior.com/payframe/payframe.js
VITE_YOUR_MW_PAYFRAME_URL=https://secure.merchantwarrior.com/payframe/
VITE_YOUR_MW_SUBMIT_URL=https://api.merchantwarrior.com/payframe/
VITE_YOUR_EMAILJS_SERVICE_ID=service_your_org
VITE_YOUR_EMAILJS_PUBLIC_KEY=your_public_key
VITE_YOUR_ADMIN_EMAIL=admin@yourcompany.com

URL Parameters & Integration

The gateway accepts a comprehensive set of URL query parameters that pre-populate form fields, select tenants, configure amounts, and control post-payment behaviour.

Tenant Selection

Amount & Currency

Customer Information

These parameters pre-fill the customer form. When all required parameters are supplied (see Streamlined Flow), the form step is skipped entirely.

Return URL

Integration Examples

Direct AUD Payment with Pre-filled Customer

VATU Conversion Payment

Fully Pre-filled — Streamlined Flow (no form shown)

Payment with Return URL

JavaScript Integration Example

// Redirect to the payment gateway from your application
function initiatePayment(customerData, amount, tenant = 'default') {
  const baseUrl     = 'https://altimapay.com/demo';
  const returnUrl   = encodeURIComponent(window.location.origin + '/payment-complete');

  const params = new URLSearchParams({
    tenant,
    amount:     amount.toString(),
    name:       customerData.name,
    email:      customerData.email,
    phone:      customerData.phone,
    address:    customerData.address,
    city:       customerData.city,
    state:      customerData.state,
    postcode:   customerData.postcode,
    country:    customerData.country || 'AU',
    product:    customerData.product || 'Purchase',
    return_url: returnUrl,
  });

  window.location.href = baseUrl + '?' + params.toString();
}

// Handle the user returning from the gateway
function handlePaymentReturn() {
  const p             = new URLSearchParams(window.location.search);
  const paymentStatus = p.get('payment_status'); // 'success' | 'failed'
  const transactionId = p.get('transaction_id');
  const amount        = p.get('amount');

  if (paymentStatus === 'success') {
    console.log(`Payment OK — Transaction: ${transactionId}, Amount: $${amount}`);
  } else {
    console.log('Payment failed or cancelled');
  }
}

Return URL Parameters

After payment the gateway appends the following to the return_url:

Payment Flow

The gateway supports two distinct flows depending on how much information is supplied via URL parameters.

Standard Flow

Used when partial or no customer information is pre-filled. The user completes a customer information form before proceeding to card entry.

• Customer Information Form — user enters personal details; URL parameters pre-fill known fields.
• Currency Conversion — optional VATU to AUD conversion with live exchange rates (tenant configurable).
• Secure Payment — PayFrame loads card input fields hosted by Merchant Warrior.
• Comprehensive Response — transaction receipt, download option, next-step buttons.
• Email Notifications — customer confirmation and admin notification sent via tenant-specific templates.

Streamlined Flow

When all required data is already known, the customer form is skipped and the user is taken directly to card entry.

• Skip Form — no customer data entry step; user goes straight to card input.
• Automatic VATU Conversion — AUD equivalent displayed if vatu parameter was used.
• Simple Response — success shows a Finish button; failure shows a Retry button.
• Automatic Return — seamless redirect to return_url with payment status parameters.
• Minimal UI — focused, distraction-free interface suited for embedded scenarios.

Email Notifications

Both flows trigger email notifications on payment completion, sent via the tenant's configured EmailJS service.

Security & Configuration

Enterprise-grade security with comprehensive environment variable support. Sensitive configuration data is never hard-coded in production builds.

Environment Variables

Multi-Tenant Example

# Altima Community Tenant
VITE_ALTIMA_MW_MERCHANT_UUID=altima_live_uuid
VITE_ALTIMA_MW_API_KEY=altima_live_key
VITE_ALTIMA_MW_PASSPHRASE=altima_live_passphrase
VITE_ALTIMA_MW_PAYFRAME_JS_URL=https://secure.merchantwarrior.com/payframe/payframe.js
VITE_ALTIMA_MW_PAYFRAME_URL=https://secure.merchantwarrior.com/payframe/
VITE_ALTIMA_MW_SUBMIT_URL=https://api.merchantwarrior.com/payframe/
VITE_ALTIMA_EMAILJS_SERVICE_ID=service_altima
VITE_ALTIMA_EMAILJS_PUBLIC_KEY=altima_public_key
VITE_ALTIMA_EMAILJS_USER_SUCCESS_TEMPLATE_ID=template_altima_success
VITE_ALTIMA_EMAILJS_USER_FAILURE_TEMPLATE_ID=template_altima_failure
VITE_ALTIMA_EMAILJS_ADMIN_NOTIFICATION_TEMPLATE_ID=template_altima_admin
VITE_ALTIMA_ADMIN_EMAIL=admin@altima-community.org
VITE_ALTIMA_EXCHANGE_RATE_API_KEY=altima_fx_api_key

# Charity Tenant
VITE_CHARITY_MW_MERCHANT_UUID=charity_live_uuid
VITE_CHARITY_MW_API_KEY=charity_live_key
VITE_CHARITY_MW_PASSPHRASE=charity_live_passphrase
VITE_CHARITY_EMAILJS_SERVICE_ID=service_charity
VITE_CHARITY_EMAILJS_PUBLIC_KEY=charity_public_key
VITE_CHARITY_ADMIN_EMAIL=donations@charity.org

Self-Hosting Example

# Force a specific tenant
VITE_TENANT_ID=your-organisation

# Gateway credentials
VITE_YOUR_MW_MERCHANT_UUID=your_merchant_uuid
VITE_YOUR_MW_API_KEY=your_api_key
VITE_YOUR_MW_PASSPHRASE=your_passphrase
VITE_YOUR_MW_PAYFRAME_JS_URL=https://secure.merchantwarrior.com/payframe/payframe.js
VITE_YOUR_MW_PAYFRAME_URL=https://secure.merchantwarrior.com/payframe/
VITE_YOUR_MW_SUBMIT_URL=https://api.merchantwarrior.com/payframe/

# Email notifications
VITE_YOUR_EMAILJS_SERVICE_ID=service_your_org
VITE_YOUR_EMAILJS_PUBLIC_KEY=your_public_key
VITE_YOUR_ADMIN_EMAIL=admin@yourcompany.com

Gateway URLs by Environment

Security Best Practices

Deployment & Hosting

The application supports multiple deployment scenarios — from a multi-tenant SaaS platform serving dozens of organisations to a self-hosted single-organisation installation.

Multi-Tenant Hosting

A single build serves all configured tenants. Tenant routing is resolved by subdomain, URL path, or query parameter.

DNS — Subdomain Routing

# Wildcard CNAME covers all tenants automatically
*.yourgateway.com        → yourgateway.com
altima.yourgateway.com   → yourgateway.com
charity.yourgateway.com  → yourgateway.com

Benefits of Multi-Tenant Hosting

Self-Hosting

Deploy on your organisation's own domain with custom branding by forcing a single tenant via environment variable.

VITE_TENANT_ID=your-organisation

VITE_YOUR_MW_MERCHANT_UUID=live_uuid
VITE_YOUR_MW_API_KEY=live_key
VITE_YOUR_MW_PASSPHRASE=live_passphrase
VITE_YOUR_MW_PAYFRAME_JS_URL=https://secure.merchantwarrior.com/payframe/payframe.js
VITE_YOUR_MW_PAYFRAME_URL=https://secure.merchantwarrior.com/payframe/
VITE_YOUR_MW_SUBMIT_URL=https://api.merchantwarrior.com/payframe/
VITE_YOUR_EMAILJS_SERVICE_ID=service_id
VITE_YOUR_EMAILJS_PUBLIC_KEY=public_key
VITE_YOUR_ADMIN_EMAIL=admin@yourcompany.com

payments.yourcompany.com
pay.yourorganisation.org
gateway.yourbusiness.net

Hosting Platform Examples

Netlify

Set environment variables under Site Settings → Environment Variables. Enable branch deploy previews for staging. Configure redirect rules for SPA routing:

# netlify.toml
[[redirects]]
  from = "/*"
  to   = "/index.html"
  status = 200

Vercel

Set environment variables under Project Settings → Environment Variables. Vercel handles SPA rewrites automatically for Vite projects.

Any Static Host (S3, GitHub Pages, cPanel)

Build locally with npm run build, upload the dist/ folder, and configure your server to serve index.html for all routes (SPA fallback).

Technical Reference

Architecture, technology stack, component structure, and API integration details.

Technology Stack

Component & File Structure

src/
├── components/
│   ├── CustomerForm.tsx          # Customer information form
│   ├── VatuConverter.tsx         # VATU → AUD conversion display
│   ├── PayFrameContainer.tsx     # Merchant Warrior PayFrame wrapper
│   ├── PaymentResponse.tsx       # Transaction result screen
│   ├── SurchargeDisplay.tsx      # Surcharge calculation display
│   └── TenantSelector.tsx        # Dev-only tenant switcher
├── services/
│   ├── emailService.ts           # Tenant-aware EmailJS integration
│   ├── receiptService.ts         # Text receipt generation
│   ├── fxService.ts              # Exchange rate API service
│   └── currencyService.ts        # Currency formatting utilities
├── config/
│   ├── tenantConfig.ts           # Multi-tenant configuration map
│   ├── settings.ts               # Legacy settings (backward compat)
│   └── merchantWarrior.ts        # Dynamic payment gateway config
├── hooks/
│   ├── useUrlParams.ts           # URL parameter parsing
│   └── useTenantColors.ts        # CSS variable injection for branding
└── types/
    └── payment.ts                # TypeScript interfaces

Application State Machine

The top-level App component manages a simple three-state flow:

API Integration — Return URL Handling

Express.js Example

// Server-side return URL handler
app.get('/payment-complete', async (req, res) => {
  const { payment_status, transaction_id, amount, tenant } = req.query;

  if (payment_status === 'success') {
    console.log(`Payment OK — ${transaction_id} for $${amount} (${tenant})`);

    switch (tenant) {
      case 'altima-community':
        await processEducationDonation(transaction_id, amount);
        break;
      case 'charity-donations':
        await processCharityDonation(transaction_id, amount);
        break;
    }
  }

  res.redirect('/dashboard');
});

React Component Example

function PaymentButton({ customerData, amount, tenant }) {
  const initiatePayment = () => {
    const params = new URLSearchParams({
      tenant,
      amount:     amount.toString(),
      name:       customerData.name,
      email:      customerData.email,
      phone:      customerData.phone,
      address:    customerData.address,
      city:       customerData.city,
      state:      customerData.state,
      postcode:   customerData.postcode,
      country:    customerData.country || 'AU',
      product:    customerData.product || 'Purchase',
      return_url: encodeURIComponent(window.location.origin + '/payment-complete'),
    });
    window.location.href = 'https://altimapay.com/demo?' + params.toString();
  };

  return <button onClick={initiatePayment}>Pay ${amount} AUD</button>;
}

Troubleshooting & Support

Common issues, their causes, and solutions. For all issues, start by opening the browser developer console — the application logs detailed configuration and error information.

Tenant Detection Issues

Payment Processing Issues

Email Notification Issues

Debugging Tools

Browser Console Debug Commands

// Check which tenant is active
console.log('Tenant:', getCurrentTenantConfig());

// Check email configuration status
EmailService.initialize(); // Logs all config checks to console

// Manually set tenant via localStorage (for testing)
localStorage.setItem('tenantId', 'altima-community');
location.reload();

Testing Tenant Detection Methods

# 1. URL Parameter (append to any URL)
?tenant=altima-community&amount=10.00

# 2. Path-based
/tenant/charity-donations/?amount=25.00

# 3. Subdomain (requires DNS)
https://altima.yourgateway.com/?amount=10.00

# 4. Environment variable (rebuild required)
VITE_TENANT_ID=altima-community

# 5. localStorage (browser console)
localStorage.setItem('tenantId', 'charity-donations');

Support Resources