Basket Payments API¶

Feature name: basket

Api name: basketPaymentsApi

API used to perform actions related to payments in a basket like getting available payment options, adding payment info or validating the payment section.

classDiagram
direction LR
    class select["select$"]
    class selectAvailable["selectAvailable$"]
    class selectSelectedPayment["selectSelectedPayment$"]
    class selectActivePaymentCost["selectActivePaymentCost$"]
    class selectSectionValidation["selectSectionValidation$"]

    BasketPaymentsAPI --> get
    BasketPaymentsAPI --> select
    BasketPaymentsAPI --> getAvailable
    BasketPaymentsAPI --> selectAvailable
    BasketPaymentsAPI --> setPayment
    BasketPaymentsAPI --> setPaymentData
    BasketPaymentsAPI --> getSelectedPayment
    BasketPaymentsAPI --> selectSelectedPayment
    BasketPaymentsAPI --> getActivePaymentCost
    BasketPaymentsAPI --> selectActivePaymentCost
    BasketPaymentsAPI --> getPaymentChannelStrategy
    BasketPaymentsAPI --> addPaymentChannelStrategy
    BasketPaymentsAPI --> addPaymentInfo
    BasketPaymentsAPI --> getPaymentInfo
    BasketPaymentsAPI --> getSectionValidation
    BasketPaymentsAPI --> selectSectionValidation

    class BasketPaymentsAPI {
        get() BasketPayment[]
        select() Observable~BasketPayment[]~
        getAvailable() BasketPayment[]
        selectAvailable() Observable~BasketPayment[]~
        setPayment(payment: BasketPayment) Promise~void~
        setPaymentData(payment: BasketPayment, paymentData: Record~string, unknown~) Promise~void~
        getSelectedPayment() BasketPayment|undefined
        selectSelectedPayment() Observable~BasketPayment|undefined~
        getActivePaymentCost() FullPrice|undefined
        selectActivePaymentCost() Observable~FullPrice|undefined~
        getPaymentChannelStrategy(channelKey?: string) IPaymentChannel
        addPaymentChannelStrategy(channelKey: string, paymentChannel: IStrategy~void, IPaymentChannel~) void
        addPaymentInfo(payment: BasketPayment, template: HTMLTemplateElement|string) void
        getPaymentInfo(payment: BasketPayment) HTMLTemplateElement|undefined
        getSectionValidation() TSectionValidation
        selectSectionValidation() Observable~TSectionValidation~
    }

    link get "methods/get/"
    link select "methods/select/"
    link getAvailable "methods/get-available/"
    link selectAvailable "methods/select-available/"
    link setPayment "methods/set-payment/"
    link setPaymentData "methods/set-payment-data/"
    link getSelectedPayment "methods/get-selected-payment/"
    link selectSelectedPayment "methods/select-selected-payment/"
    link getActivePaymentCost "methods/get-active-payment-cost/"
    link selectActivePaymentCost "methods/select-active-payment-cost/"
    link getPaymentChannelStrategy "methods/get-payment-channel-strategy/"
    link addPaymentChannelStrategy "methods/add-payment-channel-strategy/"
    link addPaymentInfo "methods/add-payment-info/"
    link getPaymentInfo "methods/get-payment-info/"
    link getSectionValidation "methods/get-section-validation/"
    link selectSectionValidation "methods/select-section-validation/"

Get API¶

To get the Basket Payments API use its name basketPaymentsApi with the getApiSync method.

useStorefront(async (storefront) => {
    const basketPaymentsApi = storefront.getApiSync('basketPaymentsApi');
});

This API is not automatically initialized. Unless you initialize it by hand, you won't be able to fetch the API. To do it you can use the registerDynamic method from the Feature System API. Here is an example on how to do it:

useStorefront(async (storefront) => {
    const featureSystemApi = this.getApiSync('FeatureSystemApi');
    await featureSystemApi.registerDynamic('basket');

    const basketPaymentsApi = storefront.getApiSync('basketPaymentsApi');
});

Methods¶

get - Retrieve all basket payment options.
select$ - Select basket payment options.
getAvailable - Retrieve available payment options.
selectAvailable$ - Observe available payment options.
setPayment - Set the selected payment option for the basket.
setPaymentData - Set additional data for a specific payment option.
getSelectedPayment - Retrieve the currently selected payment option.
selectSelectedPayment$ - Observe changes to the selected payment option.
getActivePaymentCost - Get the cost associated with the active payment option.
selectActivePaymentCost$ - Observe changes to the active payment cost.
getPaymentChannelStrategy - Retrieve the payment channel strategy for a given channel key.
addPaymentChannelStrategy - Add a new payment channel strategy.
addPaymentInfo - Add payment information using a specified template.
getPaymentInfo - Retrieve the payment information template for a specific payment option.
getSectionValidation - Validate the payment section of the basket.
selectSectionValidation$ - Observe the validation state of the payment section.

Event Bus events¶

This API listens to the following events with the Event Bus:

invalidSection.payment

Additionally, methods of this API listen to the following events:

Example¶

In this example, we use the basketPaymentsApi to retrieve the currently selected payment option.

useStorefront(async (storefront) => {
    let basketPaymentsApi = storefront.getApiSync('basketPaymentsApi');

    if (!basketPaymentsApi) {
        const featureSystemApi = this.getApiSync('FeatureSystemApi');
        await featureSystemApi.registerDynamic('basket');

        basketPaymentsApi = storefront.getApiSync('basketPaymentsApi');
    }

    const selectedPayment = basketPaymentsApi.getSelectedPayment();

    if (selectedPayment) {
        console.log('Selected payment option:', selectedPayment);
    } else {
        console.log('No payment option has been selected.');
    }
});

Example¶

In this example, we subscribe to the selectAvailable$ observable to monitor available payment options.

useStorefront(async (storefront) => {
    let basketPaymentsApi = storefront.getApiSync('basketPaymentsApi');

    if (!basketPaymentsApi) {
        const featureSystemApi = this.getApiSync('FeatureSystemApi');
        await featureSystemApi.registerDynamic('basket');

        basketPaymentsApi = storefront.getApiSync('basketPaymentsApi');
    }

    const availablePaymentOptions$ = basketPaymentsApi.selectAvailable$();

    availablePaymentOptions$.subscribe((availablePaymentOptions) => {
        console.log('Updated available payment options:', availablePaymentOptions);
    });
});

Example¶

In this example, we use the basketPaymentsApi to validate the payment section of the basket's shipping configuration.

useStorefront(async (storefront) => {
    let basketPaymentsApi = storefront.getApiSync('basketPaymentsApi');

    if (!basketPaymentsApi) {
        const featureSystemApi = this.getApiSync('FeatureSystemApi');
        await featureSystemApi.registerDynamic('basket');

        basketPaymentsApi = storefront.getApiSync('basketPaymentsApi');
    }

    const validationResults = basketPaymentsApi.getSectionValidation();

    console.log('Payment section validation:', validationResults);
});

Example¶

In this example, we use the basketPaymentsApi to retrieve the payment channel strategy for a given channel key.

useStorefront(async (storefront) => {
    let basketPaymentsApi = storefront.getApiSync('basketPaymentsApi');

    if (!basketPaymentsApi) {
        const featureSystemApi = this.getApiSync('FeatureSystemApi');
        await featureSystemApi.registerDynamic('basket');

        basketPaymentsApi = storefront.getApiSync('basketPaymentsApi');
    }

    const channelKey = 'paypal';
    const paymentChannelStrategy = basketPaymentsApi.getPaymentChannelStrategy(channelKey);

    console.log(`Payment channel strategy for ${channelKey}:`, paymentChannelStrategy);
});

Example¶

In this example, we use the basketPaymentsApi to set a selected payment option for the basket shipping.

For this example let's assume we have a list of shippings with elements that have an id attribute representing the id of a specific payment option. To achieve that you can use the getAvailable method and render elements based on the data it returns.

Let's assume such HTML structure:

    <div class="shipping-details">
        <div data-shipping-option id="1">
            Shipping details 1
        </div>
        <div data-shipping-option id="2">
            Shipping details 2
        </div>
        <div data-shipping-option id="3">
            Shipping details 3
        </div>
    </div>

We can select elements using the querySelectorAll method and attach an event listener to each of them which sets a new payment option like this:

useStorefront(async (storefront) => {
    let basketPaymentsApi = storefront.getApiSync('basketPaymentsApi');

    if (!basketPaymentsApi) {
        const featureSystemApi = this.getApiSync('FeatureSystemApi');
        await featureSystemApi.registerDynamic('basket');

        basketPaymentsApi = storefront.getApiSync('basketPaymentsApi');
    }

    const $shippingOptionsArray = [...document.querySelectorAll('div[data-shipping-option]')];

    $shippingOptionsArray.forEach(($shippingOption) => {
        $shippingOption.addEventListener('click', async function(ev) {
            const $target = ev.target;

            const availablePaymentOptions = basketPaymentsApi.getAvailable();

            const selectedPaymentOption = availablePaymentOptions.find(({ id }) => id === $target.id);

            try {
                await basketPaymentsApi.setPayment(selectedPaymentOption);
                console.log('Payment option set successfully.');
            } catch (error) {
                console.error('Error setting payment option:', error);
            }
        });
    });
});

APIs reference¶

Feature System API