Configuring Prebuilt Checkout

Gain a better understanding of the functionality that exists within the Prebuilt Checkout modal's configuration object

The createModal() and embed() functions, which are exposed by DigitalRiverCheckout, accept an optional configuration object that allows you to define:

const config = {
    containerElementId: "PBC",
    options: options,
    paymentMethod: paymentMethod,
    onInit: (checkoutSession, actions) => {},
    onReady: () => {},
    onAddressComplete: (address, actions) => {},
    onDeliveryComplete: (shippingMethod) => {},
    onPaymentCancel: () => {},
    onCheckoutComplete: (order) => {},
    onError: () => {},
    onClose: () => {}
};

Designating a container for an Inline Frame

If you implement embed() and want Digital River to add the iframe which displays a Prebuilt Checkout to a specific HTML element, then assign that element's identifier to containerElementId.

<body>
    <div id="PBC"></div>
</body>

const config = {
    containerElementId: "PBC",
    ...
};

Defining the checkout experience

In options, you can control the appearance and behavior of a Prebuilt Checkout. Specifically, you can use options to:

Set display mode

In options, the displayMode, whose value can either be standard (default) or fullPage, controls the size of the checkout window.

const options = {
  ...
  displayMode: 'fullPage',
  ...
};

A standard value results in a window whose dimensions are less than those of the browser window while fullPage expands the window to the edges of the browser window.

Stylize the modal

Set style.experience in options to alter the checkout window's logo, theme, borders, text fields, and fonts. For details, refer to Defining experience.

Localize the experience

By default, Digital River localizes the Prebuilt Checkout window based on the customer’s browser settings. But if you want to control the language of the experience, set language in options.

If you do define options.language, then Digital River assigns the same value to language in the checkout-session.

const options = {
  ...
  language: 'en-gb',
  ...
};

For a list of accepted values, refer to Supported languages.

Customize order confirmation

By setting thankYouPage in options, you can configure the order confirmation stage.

  • Custom page: To redirect customers to your own fully customized order confirmation page, pass the appropriate web address.

const options = {
    ...
    thankYouPage: 'https://www.mysite.com/order-confirmation-page'
};

  • Default window: To display Digital River's default order confirmation, omit thankYouPage. You can customize this default confirmation by calling replaceDefaultMessage(), which is exposed by actions.thankYouPage.

  • Close window: If you want the Prebuilt Checkout window to immediately close after customers place an order, set thankYouPage to none.

Restrict shipping and billing countries

By setting shipToCountries and/or billToCountries in options, you can restrict the values displayed in the drop-down menus that customers use to select a country in the name and address collection stage.

const options = {
    ...
    shipToCountries: ['AT', 'BE', 'DE', 'ES', 'FR', 'IT'],
    billToCountries: ['DE', 'ES', 'FR', 'IT']
};

The values you pass must be formatted as two-letter Alpha-2 country codes as described in the ISO 3166 international standard.

Modify the text of the country drop-down menu's label

By adding labelText.country.* in options, you can modify the text of the country drop-down menu's label in both the shipping and billing information collection stage.

If a country.* matches language, then Digital River updates the label's text.

const config = {
  "options": {
    "labelText": {
      "country": {
        "en-us": "An American custom label",
        "en-gb": "A British custom label",
        "zh-tw": "寄送地",
        "zh-hk": "寄送地",
        "zh": "寄送地"
      }
    }, 
    "language": "en-gb"
  }
};

Define the payment experience

In Prebuilt Checkout's configuration object, you can use paymentMethod to control the appearance and behavior of the payment collection stage. Specifically, paymentMethod allows you to style:

You can also use paymentMethod to:

Drop-in payments also uses the paymentMethod object; the only difference is that it's named paymentMethodConfiguration.

const paymentMethod = {
    "style": {
        "base": {
            "color": "#495057",
            "height": "35px",
            "fontSize": "1rem",
            "fontFamily": "apple-system,BlinkMacSystemFont,Segoe UI,Roboto,Helvetica Neue,Arial,sans-serif",
            ":hover": {
                "color": "#137bee",
            },
            "::placeholder": {
                "color": "#999"
            },
            ":-webkit-autofill": {
                "color": "purple"
            },
            ":focus": {
                "color": "blue"
            }
        },
        "invalid": {
            "color": "#dc3545",
            ":-webkit-autofill": {
                "color": "#dc3545"
            }
        },
        "complete": {
            "color": "#28a745",
            ":hover": {
                "color": "#28a745",
            },
            ":-webkit-autofill": {
                "color": "#28a745"
            }
        },
        "empty": {
            "color": "#000000"
        }
    },
    "creditCard": {
        "cardNumberPlaceholderText": "Credit Card Number",
        "cardExpirationPlaceholderText": "MM/YY",
        "cardCvvPlaceholderText": "CVV",
        "style": styles,
        "mask": true
    },
    "onlineBanking": {
        "style": styles,
        "placeholderText": "Select a Bank",
    },
    "googlePay": {
        "style": {
            "buttonType": "plain",
            "buttonColor": "dark",
            "buttonLanguage": "en"
        }
    },
    "applePay": {
        "style": {
            "buttonType": "plain",
            "buttonColor": "dark",
            "buttonLanguage": "en"
        }
    },
    "payPal": {
        "style": {
            "label": "checkout",
            "size": "responsive",
            "color": "gold",
            "shape": "pill",
            "fundingicons": "false",
            "tagline": "false"
        },
    },
    "msts": { 
        "enrollmentUrl": "https://acmeUS.b2b.credit/en-US/apply?client_reference_id=Acme-123456&ecommerce_url=www.acme-returnURL.com", 
    },
    "enabledPaymentMethods": ["creditCard", "payPal"],
    "disabledPaymentMethods": ["klarna"]
}

Style the overall payment experience

To capture secure payment details, Prebuilt Checkout wraps elements, which have a predetermined style. But you can customize their look and feel by defining style.

For details, refer to Styling an element container.

Style credit cards

To configure how credit cards are displayed, define one or more of the nested objects in creditCard.

  • style: For details, refer to Styling an element container.

  • mask: A boolean that determines whether card numbers and security codes get masked after they've been entered by users.

  • cardNumberPlaceholderText: The placeholder that is shown in the card number field.

  • cardExpirationPlaceholderText: The placeholder that is shown in the card expiration date field.

  • cardCvvPlacholderText: The placeholder that is shown in the card security code field.

The values you assign to cardNumberPlaceholderText, cardExpirationPlaceholderText, and cardCvvPlacholderText are not localized.

Style Google Pay

For details on googlePay.style, refer to Google Pay element styles and customization.

Style Apple Pay

For details on applePay.style, refer to Apple Pay styles and customization.

Style PayPal

All the properties of payPay.style, which styles the PayPal button, are optional.

PropertyDescriptionAccepted values

label

Customizes the button's label.

paypal (default), pay, checkout, and buynow

color

Sets the color of the button.

gold (default), silver, black, white and blue

shape

Determines the shape of the button.

pill (default) and rect

fundingicons

A boolean that determines whether icons, which as a visual cue of the stored payment methods, display below the button.

true or false (default)

tagline

A boolean that determines whether a PayPal slogan displays beneath the button.

For this feature to work, fundingicons must be false.

true or false (default)

Style online banking

To configure the appearance of the online banking payment method, define one or more of the nested objects in onlineBanking.

Link to TreviPay enrollment form

Use msts.enrollmentUrl to add a link to the TreviPay enrollment URL.

Enable and disable payment methods

To display and hide specific payment methods, provide a list of enabledPaymentMethods and disabledPaymentMethods.

For details on how to format these values, refer to Source types.

If you don't populate either of these arrays, then, by default, Prebuilt Checkout displays all transaction-applicable payment methods. If enabledPaymentMethods contains a value that doesn't meet this precondition, then it's not presented as an option to customers.

Responding to front-end events

In the Prebuilt Checkout configuration object, you can define methods and assign them to its onInit, onReady, onAddressComplete, onDeliveryComplete, onCheckoutComplete, onClose, and onError properties.

As events occur during the checkout process, these methods are executed.

const config = {
    ....
    onInit: (checkoutSession, actions) => {},
    onReady: () => {},
    onAddressComplete: (address, actions) => {},
    onDeliveryComplete: (shippingMethod) => {},
    onPaymentCancel: () => {},
    onCheckoutComplete: (order) => {},
    onError: () => {},
    onClose: () => {}
};

onInit

The onInit method, which accepts checkoutSession and actions, executes when Prebuilt Checkout initializes.

...
onInit = (checkoutSession, actions) => {},
...

onReady

The onReady method executes when the checkout-session is created and Prebuilt Checkout is loaded and ready for customer interaction.

....
onReady: () => {},
...

onAddressComplete

The onAddressComplete method, which accepts an optional address and actions, executes when customers successfully submit their shipping and/or billing information and the checkout-session's shipTo and/or billTo is updated.

...
onAddressComplete: (address, actions) => {},
...

If passed, then onAddressComplete returns address, which contains the customer’s billing and shipping data.

{
    "address": {
        "billing": {
            "address": {
                "line1": "10380 Bren Rd W",
                "line2": "line 2",
                "city": "Minnetonka",
                "postalCode": "55129",
                "state": "MN",
                "country": "US"
            },
            "name": "John Smith",
            "phone": "952-111-1111",
            "email": "jsmith@digitalriver.com",
            "organization": "Digital River",
            "additionalAddressInfo": {
                "neighborhood": "Centro",
                "division": "営業部",
                "phoneticName": "ヤマダ タロ"
            },
            "saveForLater": false
        },
        "shipping": {
            "address": {
                "line1": "10380 Bren Rd W",
                "line2": "line 2",
                "city": "Minnetonka",
                "postalCode": "55129",
                "state": "MN",
                "country": "US"
            },
            "name": "John Smith",
            "phone": "952-111-1111",
            "email": "jsmith@digitalriver.com",
            "organization": "Digital River",
            "additionalAddressInfo": {
                "neighborhood": "Centro",
                "division": "営業部",
                "phoneticName": "ヤマダ タロ"
            },
            "saveForLater": false
        }
    }
}

onDeliveryComplete

The onDeliveryComplete method, which optionally accepts shippingMethod, executes when customers submit their shipping method choice, and the checkout-session's shippingChoice is successfully updated.

    ....
    onDeliveryComplete: (shippingMethod) => {},
    ....

If passed, then onDeliveryComplete returns a shippingMethod that contains the customer’s selection, along with its calculated taxAmount.

{
    "amount": 5,
    "description": "standard",
    "serviceLevel": "SG",
    "taxAmount": 0.37
}

onCheckoutComplete

The onCheckoutComplete method, which optionally accepts order, executes when customers provide payment and submit the order, and Digital River adds sources[] to the checkout-session and creates the order.

    ....
    onCheckoutComplete: (order) => {
        console.log('[onCheckoutComplete callback]', order);
    },
    ....

If passed, then onCheckoutComplete returns the order.

{
    "id": "1038474530082",
    "checkoutId": "978785ba-07fc-4acd-9eaa-960ab512766c",
    "checkoutSessionId": "41dc1898-81fa-43af-a128-480320a443f9",
    "createdTime": "2022-07-11T19:22:46Z",
    "currency": "USD",
    "email": "jsmith@digitalriver.com",
    "shipTo": {
        "address": {
            "line1": "10380 Bren Rd W",
            "line2": "line 2",
            "city": "Minnetonka",
            "postalCode": "55129",
            "state": "MN",
            "country": "US"
        },
        "name": "John Smith",
        "phone": "952-111-1111",
        "email": "jsmith@digitalriver.com",
        "organization": "Digital River",
        "additionalAddressInfo": {
            "neighborhood": "Centro",
            "division": "営業部",
            "phoneticName": "ヤマダ タロ"
        },
        "saveForLater": false
    },
    "shipFrom": {
        "address": {
            "line1": "10380 Bren Rd W",
            "city": "Minnetonka",
            "postalCode": "55129",
            "state": "MN",
            "country": "US"
        }
    },
    "billTo": {
        "address": {
            "line1": "10380 Bren Rd W",
            "line2": "line 2",
            "city": "Minnetonka",
            "postalCode": "55129",
            "state": "MN",
            "country": "US"
        },
        "name": "John Smith",
        "phone": "952-111-1111",
        "email": "jsmith@digitalriver.com",
        "organization": "Digital River",
        "additionalAddressInfo": {
            "neighborhood": "Centro",
            "division": "営業部",
            "phoneticName": "ヤマダ タロ"
        },
        "saveForLater": false
    },
    "totalAmount": 10.74,
    "subtotal": 10,
    "totalFees": 0,
    "totalTax": 0.74,
    "totalImporterTax": 0,
    "totalDuty": 0,
    "totalDiscount": 0,
    "totalShipping": 5,
    "items": [
        {
            "id": "50418820082",
            "sku": {
                "id": "b646aeaa-efe1-4fe4-a88f-73212b40381c",
                "name": "Widget",
                "eccn": "EAR99",
                "taxCode": "4323.310_A",
                "physical": true,
                "metadata": {
                    "customAttribute1": "some value"
                }
            },
            "amount": 5,
            "quantity": 1,
            "tax": {
                "rate": 0.07375,
                "amount": 0.37
            },
            "importerTax": {
                "amount": 0
            },
            "duties": {
                "amount": 0
            },
            "availableToRefundAmount": 0,
            "fees": {
                "amount": 0,
                "taxAmount": 0
            }
        }
    ],
    "shippingChoice": {
        "amount": 5,
        "description": "standard",
        "serviceLevel": "SG",
        "taxAmount": 0.37
    },
    "updatedTime": "2022-07-11T19:22:46Z",
    "locale": "en_US",
    "customerType": "individual",
    "sellingEntity": {
        "id": "C5_INC-ENTITY",
        "name": "DR globalTech Inc."
    },
    "payment": {
        "charges": [
            {
                "id": "c40a8740-fd56-41df-8ca3-0ebd12fcf9e7",
                "createdTime": "2022-07-11T19:22:49Z",
                "currency": "USD",
                "amount": 10.74,
                "state": "capturable",
                "captured": false,
                "refunded": false,
                "sourceId": "ab6078ef-deeb-4728-9217-ec81f0b70af6",
                "type": "customer_initiated"
            }
        ],
        "sources": [
            {
                "id": "ab6078ef-deeb-4728-9217-ec81f0b70af6",
                "type": "creditCard",
                "amount": 10.74,
                "owner": {
                    "firstName": "John",
                    "lastName": "Smith",
                    "email": "jsmith@digitalriver.com",
                    "address": {
                        "line1": "10380 Bren Rd W",
                        "line2": "line 2",
                        "city": "Minnetonka",
                        "postalCode": "55129",
                        "state": "MN",
                        "country": "US"
                    },
                    "organization": "Digital River",
                    "additionalAddressInfo": {
                        "neighborhood": "Centro",
                        "phoneticFirstName": "ヤマダ",
                        "phoneticLastName": "タロ",
                        "division": "営業部"
                    }
                },
                "creditCard": {
                    "brand": "Visa",
                    "expirationMonth": 12,
                    "expirationYear": 2023,
                    "lastFourDigits": "1111"
                }
            }
        ],
        "session": {
            "id": "98fbc79d-d649-4f6b-8e55-45bda0f542b9",
            "amountContributed": 10.74,
            "amountRemainingToBeContributed": 0,
            "state": "complete",
            "clientSecret": "98fbc79d-d649-4f6b-8e55-45bda0f542b9_652d201c-799e-4d35-928b-3ccc3ccf4635"
        }
    },
    "state": "accepted",
    "stateTransitions": {
        "accepted": "2022-07-11T19:22:51Z"
    },
    "fraudState": "passed",
    "fraudStateTransitions": {
        "passed": "2022-07-11T19:22:51Z"
    },
    "taxInclusive": false,
    "consents": {
        "termsOfService": true,
        "eula": true,
        "termsOfSale": true
    },
    "liveMode": false
}

onClose

The onClose method, which optionally accepts checkoutCompleted, executes when customers close Prebuilt Checkout.

If passed, checkoutCompleted returns a boolean that indicates whether it closed before the checkout process is completed. If true, customers closed the window in the order confirmation stage. If false, it was closed in an earlier stage.

    ....
    onClose: (checkoutCompleted) => {}

onError

The onError method, which optionally accepts error, executes when a problem occurs during the checkout process.

    ....
    onError: (error) => {
          console.log('[onError callback]', error);
          console.log(error.errors[0].message);
        }
    ...

If passed, then onError returns an error that contains a type and an array of errors[], each element of which provides more details on the triggering event.

{
    "type": "bad_request",
    "errors": [
        {
            "code": "invalid_parameter",
            "parameter": "address.postalCode",
            "message": "A required address parameter, postal code, is invalid."
        }
    ]
}
PreviousDigitalRiverCheckout objectNextPerforming actions

Last updated