Embedded Elements

Quick Start

Installation

<!-- CDN (Recommended) -->
<script src="https://cdn.withacclaim.com/v1/acclaim.js"></script>

Basic Setup

const acclaim = new Acclaim({
    publishableKey: 'pk_live_your_api_key_here',
});

Core Concepts

Requests vs Elements

Acclaim uses two main concepts:

Requests: Server-side objects that define what you want to do (payment or tokenization)
Elements: Client-side UI components that collect payment information

Payment Request

Create a Payment Request for immediate processing
Create an Element to collect payment info
Mount the element to your page
Submit the element when the user clicks the pay button

Tokenization Request

Create a Tokenization Request to save payment methods
Create an Element to collect payment info
Mount the element to your page
Submit the element when the user clicks the submit button

Payment Processing

Creating Payment Requests

See the Payment Requests documentation for more information on how to create a payment request.

Creating and Mounting Elements

// Create payment element
const element = await acclaim.createElement(paymentRequest.session_identifier, {
    theme: 'clean',       // 'clean', 'material', 'minimal'
    locale: 'en',          // Language code
    appearance: {
        primaryColor: '#007bff',
        borderRadius: '8px',
        fontFamily: 'Inter, sans-serif'
    }
});

// Mount to DOM
await element.mount('#payment-container');

Element Options

Parameter	Type	Description
`theme`	string	Visual theme: `'clean'`, `'material'`, `'minimal'`
`locale`	string	Language code (e.g., `'en'`, `'fr'`, `'es'`)
`appearance`	object	Custom styling options

Appearance Customization

const element = await acclaim.createElement(sessionId, {
    appearance: {
        primaryColor: '#6366f1',        // Brand color
        backgroundColor: '#ffffff',     // Background color
        textColor: '#1f2937',          // Text color
        borderColor: '#d1d5db',        // Border color
        borderRadius: '8px',           // Border radius
        fontFamily: 'Inter, sans-serif', // Font family
        fontSize: '16px',              // Base font size
        padding: '12px',               // Input padding
        focusColor: '#3b82f6'          // Focus highlight color
    }
});

Handling Payment Completion

try {
    // Submit the payment
    const result = await element.submit();

    if (result.status === 'succeeded') {
        // Payment successful
        window.location.href = '/success';
    } else if (result.status === 'requires_action') {
        // 3D Secure or additional authentication required
        console.log('Additional authentication in progress...');
    }
} catch (error) {
    console.error(error.message);
}

Complete Payment Example

async function setupPayment() {
    // Initialize Acclaim
    const acclaim = new Acclaim({
        publishableKey: 'pk_test_your_api_key',
    });

    // Create and mount element
    const element = await acclaim.createElement(paymentRequest.session_identifier);
    await element.mount('#payment-container');

    // Handle the submission of the form the Payment Element is embedded within
    const theForm = document.getElementById('payment-form');
    theForm.addEventListener('submit', async (e) => {
        e.preventDefault();

        // Hide any previous error messages
        hideError();

        const submitButton = document.querySelector('#submit-button');
        submitButton.disabled = true;
        submitButton.textContent = 'Processing...';

        try {
            const result = await element.submit();

            if (result.status === 'succeeded') {
                window.location.href = '/success';
            } else {
                throw new Error(result.error?.message || 'Payment failed');
            }
        } catch (error) {
            showError(error.message);
            submitButton.disabled = false;
            submitButton.textContent = 'Pay Now';
        }

        return false;
    });
}

function showError(message) {
    const errorElement = document.querySelector('#error-message');
    errorElement.textContent = message;
    errorElement.style.display = 'block';
}

function hideError() {
    const errorElement = document.querySelector('#error-message');
    errorElement.style.display = 'none';
}

Tokenization (Saving Payment Methods)

Creating a Tokenization Request

See the Tokenization Requests documentation for more information on how to create a tokenization request.

Creating and Mounting Elements

// Create payment element
const element = await acclaim.createElement(tokenizationRequest.session_identifier, {
    theme: 'clean',       // 'clean', 'material', 'minimal'
    locale: 'en',          // Language code
    appearance: {
        primaryColor: '#007bff',
        borderRadius: '8px',
        fontFamily: 'Inter, sans-serif'
    }
});

// Mount to DOM
await element.mount('#save-card-container');

Handling Tokenization

try {
    // Tokenize the payment method
    const result = await tokenizationRequest.submit();

    if (result.status === 'succeeded') {
        // Payment successful
        window.location.href = '/success';
    } else if (result.status === 'requires_action') {
        // 3D Secure or additional authentication required
        console.log('Additional authentication in progress...');
    }
} catch (error) {
    console.error(error.message);
}

3D Secure Authentication

Acclaim automatically handles 3D Secure authentication when required. The process is transparent to your integration.

Manual 3DS Handling

// If you need manual control over 3DS
try {
    const result = await paymentRequest.submit();
    
    if (result.status === 'requires_action') {
        // Handle 3DS authentication
        const authResult = await acclaim.handle3DSecure();
        
        if (authResult.status === 'succeeded') {
            // Authentication successful
            console.log('Payment completed after 3DS');
        }
    }
} catch (error) {
    console.error('3DS authentication failed:', error);
}

Digital Wallets

Apple Pay

Apple Pay is automatically detected on supported devices and browsers. No additional setup required.

Requirements:

Safari browser
macOS with Touch ID or iPhone/iPad with Face ID/Touch ID
Valid Apple Pay merchant certificate (handled by Acclaim)

Google Pay

Google Pay is automatically detected when the Google Pay API is available.

Requirements:

Supported browser (Chrome, Edge, etc.)
Valid Google Pay merchant configuration

PayPal

In order to use the PayPal payment method, you must supply a return_url and cancel_url in your payment request.

Event Handling

Element Events

element.on('ready', () => {
    console.log('Element is ready');
});

element.on('change', (state) => {
    console.log('Element state changed:', state);
    // Update submit button based on validation
    document.querySelector('#submit-btn').disabled = !state.complete;
});

element.on('success', (result) => {
    console.log('Payment element completed:', result);
});

element.on('error', (error) => {
    console.error('Element error:', error);
});

Available Events

Event	Description	Payload
`ready`	Element is mounted and ready	-
`change`	Form validation state changed	`{ complete, empty, invalid }`
`success`	Payment element completed successfully	`{ id, ... }`
`error`	An error occurred	`{ code, message, ... }`

Error Handling

Common Error Types

element.on('error', (error) => {
    switch (error.code) {
        case 'validation_error':
            // Invalid card number, expired card, etc.
            showFieldError(error.field, error.message);
            break;
            
        case 'card_declined':
            // Card was declined by issuer
            showError('Your card was declined. Please try a different payment method.');
            break;
            
        case 'network_error':
            // Network connectivity issues
            showError('Network error. Please check your connection and try again.');
            break;
            
        case 'api_error':
            // Server-side error
            showError('Something went wrong. Please try again.');
            break;
            
        default:
            showError(error.message);
    }
});

Error Object Structure

{
    code: 'validation_error',
    message: 'Your card number is invalid.',
    details: [
        {
            message: 'Your card number is invalid.',
            field: 'cardNumber',
            code: 'invalid_number'
        }
    ]
}

Styling and Themes

Built-in Themes

// Default theme
const element = await acclaim.createElement(sessionId, {
    theme: 'clean'
});

// Material theme
const element = await acclaim.createElement(sessionId, {
    theme: 'material'
});

// Minimal theme
const element = await acclaim.createElement(sessionId, {
    theme: 'minimal'
});

Custom Styling

const element = await acclaim.createElement(sessionId, {
    appearance: {
        // Colors
        primaryColor: '#6366f1',
        backgroundColor: '#ffffff',
        textColor: '#1f2937',
        placeholderColor: '#9ca3af',
        borderColor: '#d1d5db',
        focusColor: '#3b82f6',
        errorColor: '#ef4444',
        
        // Typography
        fontFamily: 'Inter, -apple-system, sans-serif',
        fontSize: '16px',
        fontWeight: '400',
        
        // Layout
        borderRadius: '8px',
        borderWidth: '1px',
        padding: '12px 16px',
        
        // States
        ':hover': {
            borderColor: '#9ca3af'
        },
        ':focus': {
            borderColor: '#3b82f6',
            boxShadow: '0 0 0 3px rgba(59, 130, 246, 0.1)'
        },
        '.invalid': {
            borderColor: '#ef4444'
        }
    }
});

Testing

Test Cards

Use these test card numbers in sandbox mode:

Card Type	Number	CVC	Expiry
Visa	`4242424242424242`	Any 3 digits	Any future date
Visa (debit)	`4000056655665556`	Any 3 digits	Any future date
Mastercard	`5555555555554444`	Any 3 digits	Any future date
American Express	`378282246310005`	Any 4 digits	Any future date
Declined	`4000000000000002`	Any 3 digits	Any future date
3D Secure	`4000000000003220`	Any 3 digits	Any future date

Test Environment

const acclaim = new Acclaim({
    publishableKey: 'pk_test_your_test_key',
});

Webhook Testing

Use tools like ngrok to test webhooks locally:

# Install ngrok
npm install -g ngrok

# Expose local server
ngrok http 3000

# Use the HTTPS URL for webhook endpoint

API Reference

Acclaim Constructor

new Acclaim(options)

Options:

publishableKey (string, required): Your Acclaim publishable API key

Methods

`createPaymentElement(sessionId, container)`

Creates a payment element for the given request.

Returns: Promise<PaymentElement>

PaymentElement Methods

`mount(container)`

Mount the element to a DOM container.

Parameters:

container (string|Element): CSS selector or DOM element

Returns: Promise<PaymentElement>

`unmount()`

Remove the element from the DOM.

`on(event, callback)`

Listen for element events.

Parameters:

event (string): Event name
callback (function): Event handler

`update(options)`

Update element appearance or configuration.

Parameters:

options (object): New options to apply

`submit()`

Confirm and process the payment or tokenization.

Returns: Promise<PaymentResult>

`handle3DSecure(options)`

Manually handle 3D Secure authentication.

Returns: Promise<AuthenticationResult>