Performing actions

Gain a better understanding of how to perform customized actions in a Prebuilt Checkout

In Prebuilt Checkout, various callback functions can be assigned to properties in its configuration object. Some of these functions accept an optional actions parameter, which allows you to:

• Display custom messages in the order summary section

• Customize the thank you page

• Reject invalid address inputs

Some callbacks in the checkout button configuration object also accept actions. For details, refer to Performing actions on the checkout button.

Display custom order summary messages

You can use orderSummary to render specific messages in the Prebuilt Checkout window.

orderSummary

The orderSummary property in actions allows you to specify whether you want a customized message to be displayed in the middle and/or the bottom of this section in Prebuilt Checkout.

You might find this useful if you'd like to, as an example, inform customers that the order summary amounts aren't final until they've selected a shipping option, provided applicable tax identification numbers, and applied the payment.

middle

This property allows you to access the middle of the window's orderSummary section.

bottom

This property allows you to access the bottom of the window's orderSummary section.

addCustomMessage(message, showInfoIcon)

This function displays a customized message in the middle or bottom of orderSummary. It accepts an optional string representing the message you want displayed and an optional boolean, which determines whether Digital River displays an information icon next to your message.

The default value of showInfoIcon is true.

deleteCustomMessage()

This function deletes any customized messages that exists in the middle or bottom of orderSummary.

Add and delete custom message

When onInit executes, the following procedure loads your message in the middle of the order summary section.

config.onInit = (checkoutSession, actions) => {
     actions.orderSummary.middle.addCustomMessage('A message in the middle');  
};
...
config.onAddressComplete = (address, actions) => {
     actions.orderSummary.middle.deleteCustomMessage();
     actions.orderSummary.bottom.addCustomMessage('A new message at the bottom');
};

After users successfully submit their address information and onAddressComplete executes, the middle message is deleted, and a different message is added to the bottom.

Add custom message without icon

When onInit executes, the following procedure loads your message, without an information icon, in the middle of the order summary section.

config.onInit = (checkoutSession, actions) => {
     actions.orderSummary.middle.addCustomMessage('A message in the middle', false);  
};

Customize the order confirmation

You can use thankYouPage to customize the order confirmation stage.

thankYouPage

In actions, the thankYouPage property, which defines the order confirmation stage, exposes replaceDefaultMessage().

replaceDefaultMessage(message, showCheckCircleIcon)

If you omit options.thankYouPage, then you can use replaceDefaultMessage() to modify the default order confirmation.

This function accepts a string, which represents the message you want displayed.

If you'd like the order's identifier injected into this message, add {{orderId}} to the string. When the template renders, Digital River dynamically replaces this placeholder with the order's id in our system or, if you passed upstreamId in the create checkout-session request, that value.

The function also accepts an optional boolean that determines whether Digital River displays a circle check icon (a visual cue that the purchase was successful) before your customized message.

The default value of showCheckCircleIcon is true.

Invoke replaceDefaultMessage() inside onInit and make sure to pass checkoutSession to this callback function.

Custom message

When onInit executes, the following procedure loads your replacement message in thankYouPage.

config.onInit = (checkoutSession, actions) => {
     actions.thankYouPage.replaceDefaultMessage('<p>A customized thank you message. The order number is #{{orderId}}.</p>');  
};

Custom message without icon

When onInit executes, the following procedure loads your replacement message without a check circle icon in thankYouPage.

config.onInit = (checkoutSession, actions) => {
     actions.thankYouPage.replaceDefaultMessage('<p>A customized thank you message without a circle check icon. The order number is #{{orderId}}.</p>', false);  
};

Reject address inputs

The reject() function, exposed by actions, allows you to refuse shipping and billing inputs that you deem invalid.

reject()

If invoked in onAddressComplete, then reject() (1) blocks customers from proceeding to the checkout's next stage, and (2) displays an error message.

It accepts an optional string representing the error message you'd like displayed. If you don't define this parameter, Digital River displays a default message.

Custom error message

config.onAddressComplete = (address, actions) => {
    ...
    return actions.reject('Your customized error message');
};

Default error message

config.onAddressComplete = (address, actions) => {
    ...
    return actions.reject();
};

You can use reject() to screen out specific address categories. For example, with a regular expression and reject(), you can prevent customers from shipping products to P.O. boxes.

Event handler

config.onAddressComplete = (address, actions) => {
    if (address.address.shipping === null) {
        console.log("This is a checkout that only contains digital products. No shipping validation needed");
    }
    else {
        let line1 = address.address.shipping.address.line1;
        let line2 = address.address.shipping.address.line2;
        let combinedLines;
        if (line2 !== undefined) {
            combinedLines = line1 + line2;
        }
        else {
            combinedLines = line1;
        }
        const regexPostOfficeBox = /\b[P|p]*(OST|ost)*\.*\s*[O|o|0]*(ffice|FFICE)*\.*\s*[B|b][O|o|0][X|x]\b/;
        let isPostOfficeBox = regexPostOfficeBox.test(combinedLines);
        if (isPostOfficeBox) {
            return actions.reject('We cannot ship to a post office box.\nPlease provide a different shipping address.');
        }
    }
};

Prebuilt Checkout