Hosted Fields — Brand Management

When using getHostedFields(), the SDK exposes reactive properties to detect the card brand as the user types. This is especially important for co-branded cards (e.g., VISA/Cartes Bancaires) where the cardholder must select which network to use.

Prerequisites

This recipe assumes you already have hostedFields rendered. See the Hosted Fields recipe first.

You can manage brands in two ways:

Option 1 — Automatic brand selector

You can use the brandSelector field to automatically detect and display the brand of the card being entered.

import * as Purse from "https://cdn.purse-sandbox.com/headless-checkout/latest/purse.esm.js";

// Initialize the checkout with your session data
const checkout = await Purse.createHeadlessCheckout("YOUR_CLIENT_SESSION");

// Subscribe to available payment methods
checkout.paymentMethods.subscribe((methods) => {
    const creditCard = methods.find(m => m.method === "creditcard");

    if (creditCard) {
        const hostedFields = creditCard.getHostedFields({
            fields: {
                brandSelector: { target: "brand-selector" },
                cardNumber: { target: "card-number", placeholder: "1234 5678 9012 3456" },
                holderName: { target: "cardholder-name", placeholder: "John Doe" },
                expDate: { target: "expiry-date", placeholder: "MM/YY" },
                cvv: { target: "cvv", placeholder: "123" }
            }
        });
        hostedFields.render();
    }
});

Option 2 — Manual brand management (headless)

In a headless integration, you can manually manage and display the card brand based on the events received from the Hosted Fields.

1. Subscribe to the hostedFields.supportedBrands reactive property to get the list of supported brands.
2. Subscribe to the hostedFields.detectedBrand reactive property to get the detected brand.
3. Set the detected brand as the selected brand using setSelectedBrand().

info

Some jurisdictions require merchants to display the detected brand to the user. You must handle co-branded cards (e.g., VISA/Cartes Bancaires) by offering the user a choice of brands.

import * as Purse from "https://cdn.purse-sandbox.com/headless-checkout/latest/purse.esm.js";

const checkout = await Purse.createHeadlessCheckout("YOUR_CLIENT_SESSION");

checkout.paymentMethods.subscribe((methods) => {
    const creditCard = methods.find(m => m.method === "creditcard");

    if (creditCard) {
        const hostedFields = creditCard.getHostedFields({
            fields: {
                cardNumber: { target: "card-number", placeholder: "1234 5678 9012 3456" },
                holderName: { target: "cardholder-name", placeholder: "John Doe" },
                expDate: { target: "expiry-date", placeholder: "MM/YY" },
                cvv: { target: "cvv", placeholder: "123" }
            }
        });

        hostedFields.render();

        // Subscribe to supported brands
        hostedFields.supportedBrands.subscribe((brands) => {
            console.log("Available brands:", brands);
            // Update your UI to display brand icons
        });

        // Subscribe to detected brand
        hostedFields.detectedBrands.subscribe((brands) => {
            console.log("Detected brands:", brands);
            if (brands && brands.length > 0) {
                try {
                    hostedFields.setSelectedBrand(brands[0]);
                } catch (err) {
                    if (err.code === "NotSupportedBrandError") {
                        console.error("Brand not supported:", brands[0]);
                    }
                }
            }
        });

        // Manually set a brand (e.g., when user clicks on a brand icon)
        const selectBrand = (brandName) => {
            try {
                hostedFields.setSelectedBrand(brandName);
            } catch (err) {
                if (err.code === "NotSupportedBrandError") {
                    console.error("Brand not supported:", brandName);
                }
            }
        };

        // Example: selectBrand("VISA");
    }
});