Links

Configuring the modal

Learn how to configure the Prebuilt Checkout modal
You can optionally pass a configuration object to the create Prebuilt Checkout modal method. This object allows you to:
const config = {
options: options,
onReady: () => {},
onAddressComplete: (address) => {},
onDeliveryComplete: (shippingMethod) => {},
onPaymentCancel: () => {},
onCheckoutComplete: (order) => {},
onError: () => {},
onClose: () => {}
};

Defining the checkout experience

In the configuration object, options controls 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: 'it',
thankYouPage: 'https://www.mysite.com/order-confirmation-page',
shipToCountries: ['AT', 'BE', 'DE', 'ES', 'FR', 'IT'],
billToCountries: ['DE', 'ES', 'FR', 'IT']
};

Stylize the modal

Set style.modal and style.textField 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 customized locale, set language 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, you can configure the order confirmation stage.
  • Custom page: To redirect customers to your own 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 from the request. To view an example of this default window, refer to the Order confirmation stage section.
  • 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 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.

Responding to front-end events

The modal's configuration object allows you to define how you want to handle the following front-end events:
const config = {
....
onReady: () => {},
onAddressComplete: (address, actions) => {},
onDeliveryComplete: (shippingMethod) => {},
onPaymentCancel: () => {},
onCheckoutComplete: (order) => {},
onError: () => {},
onClose: () => {}
};

onReady

When the checkout-session is created, and the modal is loaded and ready for customer interaction, onReady is called.
....
onReady: () => {},
...

onAddressComplete

When customers submit their shipping and/or billing information, and the checkout-session's shipTo and/or billTo is successfully updated, onAddressComplete is called.
The function accepts an optional address and actions.
...
onAddressComplete: (address, actions) => {},
...

address

If you pass address, then onAddressComplete returns an address that 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
}
}
}

actions

The actions parameter allows you to reject shipping and billing inputs that you deem to be invalid. It exposes reject(), which (1) blocks customers from proceeding to the next step in the checkout and (2) displays an error message in the modal.
The function accepts an optional string that gets passed back to the customer as an error message. If you don't specify a value, then the default message is displayed.
Custom error message
Default error message
config.onAddressComplete = (address, actions) => {
...
return actions.reject('Your customized error message');
};
config.onAddressComplete = (address, actions) => {
...
return actions.reject();
};
This function can be especially useful if you'd like to screen out specific address categories. For example, by using a regular expression and reject(), you can prevent customers from shipping products to P.O. boxes.
Event handler
UX
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.');
}
}
};

onDeliveryComplete

When customers submit their shipping method choice, and the checkout-session's shippingChoice is successfully updated, onDeliveryComplete is called.
The function accepts an optional shippingMethod.
....
onDeliveryComplete: (shippingMethod) => {},
....

shippingMethod

If you pass shippingMethod, then onDeliveryComplete returns a shippingMethod that contains the customer’s selection.
{
"amount": 5,
"description": "standard",
"serviceLevel": "SG",
"taxAmount": 0.37
}

onCheckoutComplete

When customers provide payment and submit the order, and Digital River adds the sources[] to the checkout-session and then creates the order, onCheckoutComplete is called.
The function accepts an optional order.
....
onCheckoutComplete: (order) => {
console.log('[onCheckoutComplete callback]', order);
},
....

order

If you pass order, 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

When customers close the modal, onClose is called.
....
onClose: () => {}

onError

When an error occurs during the checkout experience, onError is called.
The function accepts an optional error.
....
onError: (error) => {
console.log('[onError callback]', error);
console.log(error.errors[0].message);
}
...

error

If you pass error, 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."
}
]
}