Managing Payment Methods

Primary vs. Secondary Payment Methods

The SDK supports multiple payment sources. You can distinguish between primary methods (credit cards, wallet...) and secondary ones (used to cover remaining balances, like giftcards).

Use the checkout.paymentMethods variable to access all payment methods.

Primary methods: Used for initial payment (only one can be selected).
Secondary methods: Supplementary payments (e.g. gift cards).

You can explicitly mark a method as the primary one:

selectedMethod.setAsPrimarySource()

By default, the last selected primary method is used for the main payment.

Handle Digital Wallets

When implementing a Pay button, it should trigger the payment submission as described in the How to Build Guide. If using a digital wallet such as Google Pay, Apple Pay, or PayPal, the wallet button itself serves as the payment initiator.

From a user experience (UX) perspective, ensure that all available payment methods are clearly displayed, allowing users to easily choose their preferred option before interacting with the pay button. This prevents confusion and ensures a seamless checkout flow.

Best Practices

Clearly label wallet buttons
Display all available methods before showing the pay button
Provide visual feedback when a method is selected

Handle Gift Cards (Secondary Methods)

To support gift cards (e.g., Illicado, Easy2play), use the getSecondaryToken method from the SDK.

Check if method is a secondary method by using the isSecondary field.

Create Gift Card Form

Follow these steps to integrate gift card functionality:

Collect required information for the selected gift card provider.
Build a form with fields for the gift card details and amount to be charged.

<form id="gift-card-form">
    <input type="text" id="pan" placeholder="Card Number"/>
    <input type="text" id="cvv" placeholder="CVV"/>
    <button type="submit">Add</button>
</form>

<div id="token-info">
    <p>Balance: <span id="balance"></span></p>
    <input type="number" id="amount" placeholder="Amount"/>
</div>

Logic to Register and Use Token

After retrieving the token, apply it to the payment flow and allow users to assign an amount.

document.getElementById("gift-card-form").addEventListener("submit", async (event) => {
    event.preventDefault();

    // let's find a gift card payment method
    const methods = checkout.paymentMethods.value
    const method = methods.find((method) => method.partner === "illicado");

    if (!method) {
        console.error("Gift card payment method not found");
        return;
    }

    const pan = document.getElementById("pan").value;
    const cvv = document.getElementById("cvv").value;

    try {
        const token = await method.getSecondaryToken(pan, cvv);
        document.getElementById("balance").textContent = token.balance;

        document.getElementById("amount").addEventListener("blur", async () => {
            // take the amount from the gift card
            await token.take(document.getElementById("amount").value);
        });
    } catch (error) {
        console.error("Failed to retrieve gift card token:", error);
    }
});

info

Make sure to handle errors gracefully and provide feedback to users.

Special Cases

Optional CVV

Some partners (like Ogloba or Maxxing loyalty card) do not require CVV for transactions. In such cases, you can skip the CVV field in the form. Call the requiresCVV function of the PaymentMethod to determine if it's required. We strongly recommend to call the function when the PAN changes because the display logic can depend on the PAN value ( ie. Buybox).

<input type="text" id="pan" placeholder="Card Number"/>

panInput.addEventListener('change', async () => {
    const method = checkout.paymentMethods.value.find((method) => method.partner === "illicado");
    if (method && method.requiresCVV(panInput.value)) {
        // Show CVV field
        document.getElementById("cvv").style.display = "block";
    } else {
        // Hide CVV field
        document.getElementById("cvv").style.display = "none";
    }
});

Custom validation rules

You can also use the method.validatePan and method.validateCVV functions to check the card details against your own validation rules. This should be rarely needed, as most validation is handled by the payment method itself.

const method = checkout.paymentMethods.value.find((method) => method.partner === "illicado");

method.validatePan((pan) => {
    // Custom validation logic for PAN
    return pan.length === 16; // Example: Check if PAN is 16 digits
});

method.validateCVV((cvv) => {
    // Custom validation logic for CVV
    return cvv.length === 3; // Example: Check if CVV is 3 digits
});

Save and Reuse Gift Cards

When using a gift card for the first time, it can be saved for future transactions with token.register(). You should always check if registration is allowed using the token.canBeRegistered field.

To assign a name to a token, use the token.edit({ name: "My Gift Card" }) method.

You can always opt out of saving a gift card by using the token.register(false) method.

Registration state can be accessed using the token.registration reactive variable.

token.registration.subscribe((registration) => {
    if (registration.registered) {
        console.log(`Gift card will be registered with name ${registration.name}`);
    } else {
        console.log("Gift card will not be registered");
    }
});

Registration Availability

Ask your account manager to allow registration for your gift card payment method.

Remove the gift card from the payment session

To remove a gift card from the payment session, use the token.removeFromSplit() method.

// let's find a token
const token = checkout.paymentTokens.value[0];
token.removeFromSplit();

Multi-Card Support

Unlike other payment methods, multiple gift cards can be used in a single transaction.

Handle Saved Payment Methods

Save a Payment Method

To save a payment method, use the method.register() method. It takes an optional name parameter to assign a name to the token.

<div id="root">
    <div id="form"></div>
    <label for="save-token">Save this payment method
        <input type="checkbox" id="save-token"/>
    </label>
    <label for="name">Name
        <input type="text" id="name"/>
    </label>
    <button id="pay-button" disabled>Pay</button>
</div>

const method = checkout.paymentMethods.value.find((method) => method.method === "creditcard");
const saveTokenCheckbox = document.getElementById("save-token");
const nameInput = document.getElementById("name");

saveTokenCheckbox.addEventListener('change', (e) => {
    if (e.target.checked) {
        const name = nameInput.value || "My Card";
        method.register(true, {name});
    } else {
        method.register(false);
    }
});

You can subscribe to the registration state using the method.registration reactive variable.

method.registration.subscribe((registration) => {
    if (registration.registered) {
        console.log(`Payment method will be registered with name ${registration.name}`);
    } else {
        console.log("Payment method will not be registered");
    }
});

Display Saved Payment Methods

Users can select a saved payment method using the checkout.paymentTokens reactive variable. Some tokens may require CVV entry, which is handled by the PaymentElement.

<div id="root">
    <div id="form"></div>
    <div id="tokens"></div>
    <button id="pay-button" disabled>Pay</button>
</div>

function displayTokens(tokens) {
    const ul = document.createElement("ul");
    tokens.forEach((token) => {
        const li = document.createElement("li");
        li.textContent = `${token.partner} ${token.method}`;
        li.addEventListener("click", () => {
            const tokenForm = document.getElementById("form");
            const cvvInput = token.getPaymentElement();
            cvvInput.appendTo(tokenForm);
        });
        ul.appendChild(li);
    });
    document.getElementById("tokens").appendChild(ul);
}

checkout.paymentTokens.subscribe(displayTokens);

Edit a Token

Users can rename a saved token using token.edit(). This requires a WalletSession.

const token = checkout.paymentTokens.value[0];

if (!token.name) {
    token.edit({name: "My Card"});
}

Delete a Token

To remove a saved token, use token.delete(). This requires a WalletSession.

const token = checkout.paymentTokens.value[0];
token.delete();

Refresh Required

Refresh the PaymentSession after editing or deleting a token to reflect changes.

Update the Client Session

When cart details change, update the client session with checkout.setSession().

async function updateSession(newSession) {
    return checkout.setSession(newSession);
}

Set a Wallet Session

To manage saved payment methods, create a WalletSession using checkout.setWalletSession().

async function setWalletSession(walletSession) {
    return checkout.setWalletSession(walletSession);
}

Primary vs. Secondary Payment Methods​

Handle Digital Wallets​

Best Practices​

Handle Gift Cards (Secondary Methods)​

Create Gift Card Form​

Logic to Register and Use Token​

Special Cases​

Optional CVV​

Custom validation rules​

Save and Reuse Gift Cards​

Remove the gift card from the payment session​

Handle Saved Payment Methods​

Save a Payment Method​

Display Saved Payment Methods​

Edit a Token​

Delete a Token​

Update the Client Session​

Set a Wallet Session​