Configuration

Configure the Altruon JS payment component to match your business requirements and customize the payment experience.

Initialization Configuration

Initialize Altruon with your public key and domain:

altruon.init("pk_sandbox_your_publishable_key", "your-domain");

The init() method returns the Altruon instance, allowing you to chain callback handlers:

altruon
  .init("pk_sandbox_your_publishable_key", "your-domain")
  .on("onSuccess", (data) => console.log("Payment success:", data))
  .on("onFailure", (error) => console.error("Payment failed:", error))
  .on("onActionRequired", (action) => console.log("Action required:", action))
  .on("onDataRequired", (info) => console.warn("Missing data:", info));

Init Parameters

Parameter	Type	Required	Description
`publicKey`	string	Yes	Your Altruon publishable API key (e.g., "pk_sandbox_...")
`siteName`	string	Yes	Your domain/site name (e.g., "mycompany")

Session Configuration

Set the session ID obtained from your backend:

altruon.setSession(sessionId);

Note: The session must be created via the Altruon Create Session API on your backend. See the Quick Start guide for details.

Customer Data Methods

Use setter methods to provide customer information.

Important: Only billingAddress.country can be set through the frontend. The fields currency, planId, and billingPlatformId must be initiated from the backend Create Session API call and cannot be modified from the frontend.

Basic Customer Information

altruon.setCustomer({
  firstName: "John",
  lastName: "Doe",
  email: "john.doe@example.com",
  phone: "+1234567890",
  ip: "127.0.0.1"  // Optional
});

Customer Object Properties:

Property	Type	Required	Description
`firstName`	string	No	Customer's first name
`lastName`	string	No	Customer's last name
`email`	string	No	Customer's email address
`phone`	string	No	Customer's phone number
`ip`	string	No	Customer's IP address

Addresses

altruon.setAddresses({
  billing: {
    street: "123 Main St",
    number: "Apt 4B",      // Optional
    city: "New York",
    state: "NY",
    zipCode: "10001",
    country: "US"
  },
  shipping: {              // Optional
    street: "456 Oak Ave",
    city: "Brooklyn",
    state: "NY",
    zipCode: "11201",
    country: "US"
  }
});

Address Object Properties:

Property	Type	Required	Description
`street`	string	No	Street address
`number`	string	No	Apartment, suite, or unit number
`city`	string	No	City
`state`	string	No	State/Province code
`zipCode`	string	No	Postal/ZIP code
`country`	string	Yes (if not provided in create session backend call already)	ISO 3166-1 alpha-2 country code (can be set from frontend)

Billing Platform Data

altruon.setBilling({
  planId: "price_1SMtJj4hYau76GhIakR22BKu",
  platformId: "3287b8c7-ce43-41fd-9d58-f510e610b8f3",
  platformName: "stripe"
});

Billing Object Properties:

Property	Type	Required	Description
`planId`	string	Yes	Subscription plan ID from billing provider (must be set via backend Create Session API)
`platformId`	string	Yes	Altruon billing platform connection ID (must be set via backend Create Session API)
`platformName`	string	No	Billing platform name (e.g., "stripe", "chargebee")
`frequency`	string	No	Billing frequency (e.g., "monthly", "yearly")

Rendering the Component

Once you've set the session and customer data, render the payment component:

altruon.renderComponent("#altruon-payment-container");

The component will be rendered inside the specified container element.

Component Rendering Behavior: The component's UI adapts based on the session configuration:

If no paymentMethod was specified during session creation and multiple routing entries match the currency, a drawer UI will be displayed allowing customers to select their preferred payment method

If only a single routing entry matches the currency, only the required payment fields for that method will be displayed (e.g., card number, expiry date, CVV, and optionally cardholder name)

Container Requirements:

Must be a valid CSS selector (e.g., #id, .class, or [data-attr])
Element must exist in the DOM before calling renderComponent()
Element should be empty or its contents will be replaced

Processing Payment

Important: Payment initiation is not automatically managed by the component. Merchants are expected to call altruon.processPaymentAndSubscription() once all data has been collected on their frontend and set via the proper setter methods (e.g., setCustomer(), setAddresses(), etc.).

First, set up callback handlers to respond to payment events:

altruon
  .init("pk_sandbox_your_key", "your-domain")
  .on("onSuccess", (data) => {
    console.log('Payment successful!', data);
    // Manages the display based on status. 
    // ...
  })
  .on("onFailure", (error) => {
    console.error('Payment failed:', error);
    alert('Payment failed: ' + error.message);
  })
  .on("onActionRequired", (action) => {
    console.log('Action required:', action);
    // Handle 3DS or other actions
  })
  .on("onDataRequired", (info) => {
    console.warn('Additional data needed:', info);
  });

After setting all required data using the setter methods, trigger payment and subscription creation:

altruon.processPaymentAndSubscription();

Callback Events

Event	Description	Response Data
`onSuccess`	Payment completed successfully	`{ transactionId: string, message: string }`
`onFailure`	Payment failed	`{ status: string, message: string }`
`onActionRequired`	Additional action needed (3DS, QR code, etc.)	`{ actionType: "redirect" \| "qrDataDisplay", data: object, message: string }`
`onDataRequired`	Additional data needed from user	`{ message: string, details: string, requiredFields: string }`

Action Types:

redirect - User needs to be redirected for authentication (e.g., 3D Secure)
qrDataDisplay - QR code should be displayed for payment (e.g., PIX, UPI)

Note: For detailed information about each callback and implementation examples, see the Callbacks documentation.

Method Reference

Here's a complete reference of all available methods:

Initialization Methods

Method	Parameters	Description
`altruon.init()`	`publicKey: string, siteName: string`	Initialize Altruon (returns `this` for chaining)
`altruon.setSession()`	`sessionId: string`	Set payment session

Customer Data Methods

Method	Parameters	Description
`altruon.setCustomer()`	`customer: object`	Set customer information
`altruon.setAddresses()`	`addresses: object`	Set billing and shipping addresses
`altruon.setBilling()`	`billing: object`	Set billing platform data

Component Methods

Method	Parameters	Description
`altruon.renderComponent()`	`selector: string`	Render payment component
`altruon.on()`	`eventName: string, callback: function`	Register event callback handler
`altruon.processPaymentAndSubscription()`	None	Process payment and create subscription after all data has been set

Usage Examples

Minimal Setup

// Initialize with callbacks
altruon
  .init("pk_sandbox_your_key", "your-domain")
  .on("onSuccess", (data) => window.location.href = '/success')
  .on("onFailure", (error) => alert(error.message));

// Set session (from backend)
altruon.setSession(sessionId);

// Render component
altruon.renderComponent("#payment-container");

// Process payment after user fills in payment details
altruon.processPaymentAndSubscription();

Complete Customer Information

// Initialize with callbacks
altruon
  .init("pk_sandbox_your_key", "your-domain")
  .on("onSuccess", (data) => window.location.href = '/success')
  .on("onFailure", (error) => alert(error.message));

// Set session
altruon.setSession(sessionId);

// Set all customer data
altruon.setCustomer({
  firstName: "Jane",
  lastName: "Smith",
  email: "jane.smith@example.com",
  phone: "+1234567890",
  ip: "127.0.0.1"
});

// Set addresses
altruon.setAddresses({
  billing: {
    street: "123 Main St",
    number: "Suite 100",
    city: "San Francisco",
    state: "CA",
    zipCode: "94102",
    country: "US"
  }
});

// Render component
altruon.renderComponent("#payment-container");

// Process payment after all data is set and user fills in payment details
altruon.processPaymentAndSubscription();

Progressive Data Collection

// Initialize early with callbacks
altruon
  .init("pk_sandbox_your_key", "your-domain")
  .on("onSuccess", (data) => window.location.href = '/success')
  .on("onFailure", (error) => alert(error.message));

altruon.setSession(sessionId);

// Collect and set data as user fills form
const customerData = {};

document.getElementById('email').addEventListener('blur', (e) => {
  customerData.email = e.target.value;
});

document.getElementById('firstName').addEventListener('blur', (e) => {
  customerData.firstName = e.target.value;
});

document.getElementById('lastName').addEventListener('blur', (e) => {
  customerData.lastName = e.target.value;
});

// When form is complete, set customer data and render
document.getElementById('continue-btn').addEventListener('click', () => {
  altruon.setCustomer(customerData);
  altruon.renderComponent("#payment-container");
});

// When user clicks submit payment button, process the payment
document.getElementById('submit-payment-btn').addEventListener('click', () => {
  altruon.processPaymentAndSubscription();
});

Next Steps

Event Callbacks - Handle payment events
Style Customization - Advanced styling
Examples - Real-world use cases

Initialization Configuration​

Init Parameters​

Session Configuration​

Customer Data Methods​

Basic Customer Information​

Addresses​

Billing Platform Data​

Rendering the Component​

Processing Payment​

Callback Events​

Method Reference​

Initialization Methods​

Customer Data Methods​

Component Methods​

Usage Examples​

Minimal Setup​

Complete Customer Information​

Progressive Data Collection​

Next Steps​

Initialization Configuration

Init Parameters

Session Configuration

Customer Data Methods

Basic Customer Information

Addresses

Billing Platform Data

Rendering the Component

Processing Payment

Callback Events

Method Reference

Initialization Methods

Customer Data Methods

Component Methods

Usage Examples

Minimal Setup

Complete Customer Information

Progressive Data Collection

Next Steps