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 getApi method.

useStorefront(async ({ eventBus, getApi }) => {
    eventBus.on('basket.initialized', async () => {
        const basketPaymentsApi = await getApi('basketPaymentsApi');=
    });
});

This API is not automatically initialized. Unless you initialize it by hand or use a proper event like in the example above, you won't be able to fetch the API. Read more in the Retrieving basket APIs section

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 ({ eventBus, getApi }) => {
    eventBus.on('basket.initialized', async () => {
        const basketPaymentsApi = await getApi('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 ({ eventBus, getApi }) => {
    eventBus.on('basket.initialized', async () => {
        const basketPaymentsApi = await getApi('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 ({ eventBus, getApi }) => {
    eventBus.on('basket.initialized', async () => {
        const basketPaymentsApi = await getApi('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 ({ eventBus, getApi }) => {
    eventBus.on('basket.initialized', async () => {
        const basketPaymentsApi = await getApi('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 ({ eventBus, getApi }) => {
    eventBus.on('basket.initialized', async () => {
        const basketPaymentsApi = await getApi('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