Gift Cards

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 on the PurseHeadlessCheckoutMethod object.

Create Gift Card Form

Follow these steps to integrate gift card functionality:

1. Collect required information for the selected gift card provider.
2. 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);
    }
});

Information

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";
    }
});

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.