Links

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,
onInit: (checkoutSession, actions) => {},
onReady: () => {},
onAddressComplete: (address, actions) => {},
onDeliveryComplete: (shippingMethod) => {},
onPaymentCancel: () => {},
onCheckoutComplete: (order) => {},
onError: () => {},
onClose: () => {}
};

Defining the checkout experience

In options you can control the appearance and behavior of the 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 modal

By default, Digital River localizes the modal based on the customer’s browser settings. But if you want a checkout experience with a specific locale, set language in options to one of the following values:
Code value
Language/Locale
ar
Arabic
cs
Czech
da
Danish
de
German
el
Greek
en-gb
English UK
en
English
en-us
English USA
es
Spanish
es-419
Spanish - Latin America
fi
Finnish
fr-ca
French Canadian
fr
French
hu
Hungarian
it
Italian
ja
Japanese
ko
Korean
nl
Dutch
no
Norwegian
pl
Polish
pt-br
Portuguese Brazil
pt
Portuguese
ru
Russian
sk
Slovak
sv
Swedish
th
Thai
tr
Turkish
zh
Chinese
zh-hk
Chinese (Traditional, Hong Kong S.A.R.)
zh-tw
Chinese (Traditional, Taiwan)

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"
}
};

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."
}
]
}