Configuration

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

Working example: every method on this page is used in context in the Altruon Merchant Demo. See client/src/pages/CheckoutPage.jsx for the full, commented integration walkthrough.

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, lineItems (in billingData), 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({
  lineItems: [
    {
      type: "plan",
      id: "price_1SMtJj4hYau76GhIakR22BKu",
      quantity: "1"
    }
  ],
  platformId: "3287b8c7-ce43-41fd-9d58-f510e610b8f3",
  platformName: "stripe"
});

Billing Object Properties:

Property	Type	Required	Description
lineItems	array	Yes	Array of items to be purchased (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")

Payment Extra Data

Some payment methods require additional payment-level data, most notably a tax document (CPF/CNPJ) for Brazilian methods like Pix and Boleto, or a wallet username for UPI:

altruon.setPaymentExtra({
  document: "91051605962",      // CPF/CNPJ for Brazilian payment methods
  cardType: "visa",             // Optional card brand hint
  walletUsername: "user@upi"    // Wallet/UPI identifier
});

The Merchant Demo calls this before processing BRL payments. See the pay handler in client/src/pages/CheckoutPage.jsx:

// PagBrasil (BRL) requires a CPF/CNPJ document on the payment payload.
if (country === "BR" || currency === "BRL") {
  altruon.setPaymentExtra({ document: "91051605962" });
}

Payment Extra Properties:

Property	Type	Required	Description
document	string	No	Tax document number (e.g., CPF/CNPJ for Brazil)
cardType	string	No	Card brand/type hint
walletUsername	string	No	Wallet or UPI identifier

---

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" | "QR_CODE", message: string, redirectUrl?: string, qrData?: 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)
• QR_CODE - 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
altruon.setPaymentExtra()	extra: object	Set extra payment data (tax document, card type, wallet username)

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