Links
Comment on page

Configuring the modal

Gain a better understanding of the functionality that exists within the Prebuilt Checkout modal's configuration object
The createModal() function, which is exposed by DigitalRiverCheckout, accepts an optional configuration object that allows you to define:
const config = {
options: options,
paymentMethod: paymentMethod,
onInit: (checkoutSession, actions) => {},
onReady: () => {},
onAddressComplete: (address, actions) => {},
onDeliveryComplete: (shippingMethod) => {},
onPaymentCancel: () => {},
onCheckoutComplete: (order) => {},
onError: () => {},
onClose: () => {}
};

Defining the checkout experience

In options, you can control the overall appearance and behavior of the Prebuilt Checkout modal. Specifically, you can use options to:
const options = {
style: {
modal: {
logo: 'https://www.mysite.com/logo.png',
themeColor: {
primary: '#00a7e1',
highlight: '#b6e8fb',
background: {
header: '#b6e8fb',
mainContent: '#fff',
orderSummary: '#e4edf7',
footer: '#001c33'
},
text: {
link: '#003058',
footerLink: '#0befc5',
sectionHeading: '#083bf1',
button: '#ffc439',
textButton: '#0befc5'
}
},
borderRadius: '3px',
fontFamily: 'Arial, Helvetica, sans-serif',
fontStyle: 'italic',
fontVariant: 'normal',
letterSpacing: '3px'
},
textField: {
base: {
color: '#00a7e1',
fontFamily: 'Arial, Helvetica, sans-serif',
fontSize: '20px',
fontStyle: 'italic',
fontVariant: 'normal',
letterSpacing: '3px'
},
borderRadius: '4px'
}
},
language: 'en-gb',
thankYouPage: 'https://www.mysite.com/order-confirmation-page',
shipToCountries: ['AT', 'BE', 'DE', 'ES', 'FR', 'IT'],
billToCountries: ['DE', 'ES', 'FR', 'IT']
};

Set display mode

In options, the displayMode, whose value can either be standard (default) or fullPage, controls the size of the checkout modal.
A standard value results in a modal whose dimensions are less than those of the browser window while fullPage expands the modal to the edges of the browser window.

Stylize the modal

Set style.modal and style.textField in options to alter the modal's default logo, theme, borders, text fields, and fonts.

Localize the experience

By default, Digital River localizes the Prebuilt Checkout modal 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.
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 modal: If you want the modal 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.
Configurations options
Modal
const configObj = {
"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 modal 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.
Property
Description
Accepted 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.
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 createModal() function's 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 the modal initializes.
...
onInit = (checkoutSession, actions) => {},
...

onReady

The onReady method executes when the checkout-session is created and the modal 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": "[email protected]",
"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": "[email protected]",
"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": "[email protected]",
"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": "[email protected]",
"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": "[email protected]",
"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": "[email protected]",
"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 the modal.
If passed, checkoutCompleted returns a boolean that indicates whether the modal is closed before the checkout process is completed. If true, customers closed the modal in the order confirmation stage. If false, the modal 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."
}
]
}