Create a test accountSign in to DashboardSystem status
Search
⌃K
Links

Prebuilt Checkout

Learn how to build a Drop-in Checkout integration
Prebuilt Checkout is a configurable checkout experience that allows you to connect an upstream commerce system with Digital River's local pricing, logistics, subscriptions, payment, fraud detection, tax exemption, and disclosure services.
The Prebuilt Checkout solution reduces the complexity of integrating with the Digital River APIs and our front-end libraries, thereby shortening your time to deployment.
Once customers build a cart and initiate checkout, a Prebuilt Checkout integration needs to:

Building a cart

During the early stages of an ecommerce transaction, customers land on your storefront, review products and build a cart. Unless you engage our local pricing service, Digital River is typically not involved in these early pre-checkout interactions. However, once customers initiate checkout, you'll need to start interacting with Prebuilt Checkout.

Initiating checkout

Add a click event listener to each checkout button on your site. Handle the event by defining a checkout-session request, passing that request data to your back-end server, and then securely sending a create checkout-session request.
Digital River returns a unique checkout-session identifier that you must pass, along with an optional configuration object, to the create modal method on your front-end.

Configuring a checkout-session

For details, refer to the Checkout-sessions page.

Creating a checkout-session

To create a checkout-session, send your secret API key and request payload in a POST /drop-in/checkout-sessions.
curl --location --request POST 'https://api.digitalriver.com/drop-in/checkout-sessions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <secret API key>' \
...
--data-raw '{
"currency": "USD",
"customerType": "individual",
"taxInclusive": false,
"items": [
{
"skuId": "b535d75a-a6ee-4f63-be4d-c2e2537efec7",
"quantity": 1,
"price": 5
}
],
"shipFrom": {
"address": {
"line1": "10380 Bren Rd W",
"line2": "",
"city": "Minnetonka",
"postalCode": "55129",
"state": "MN",
"country": "US"
}
},
"options": {
"shippingMethods": [
{
"amount": 5,
"description": "standard",
"serviceLevel": "SG"
},
{
"amount": 15,
"description": "next day",
"serviceLevel": "ND"
}
],
"addresses": [
{
"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": "ヤマダ タロ"
}
},
{
"address": {
"line1": "62 Trinity Crescent",
"line2": "",
"city": "WHITCHURCH",
"postalCode": "CF4 9ZB",
"country": "GB"
},
"name": "Anna Brawner",
"phone": "07854319925",
"email": "[email protected]",
"organization": "Digital River",
"additionalAddressInfo": {
"neighborhood": "Centro",
"division": "営業部",
"phoneticName": "ヤマダ タロ"
}
}
]
}
}'

The checkout-session identifier

A 201 Created response to your create checkout-session request contains a unique id.
{
"id": "eb3b9cc3-d068-4300-9488-c88c0341b5db"
...
}
Use this checkout-session identifier to create a Prebuilt Checkout modal.

Creating a Prebuilt Checkout modal

Make sure you include DigitalRiverCheckout.js by adding the following script to your checkout page.
<script src="https://checkout.digitalriverws.com/v1/DigitalRiverCheckout.js"></script>
const drCheckout = new DigitalRiverCheckout('YOUR_PUBLIC_API_KEY');
document.getElementById('YOUR_CHECKOUT_BUTTON_ID').addEventListener('click', async (event) => {
// An example asynchronous function that creates the checkout session
const checkoutSessionId = await createCheckoutSession();
// Creates and opens the modal
drCheckout.createModal(checkoutSessionId, config);
});

Configuring the checkout modal

For details, refer to the Configuring the modal page.

Prebuilt Checkout modal window

After createModal() is invoked, the checkout modal window opens and onReady executes.
Depending on how the checkout-session is configured, the modal then takes customers through various stages:

Name and address stage

In this stage, customers are always required to provide their name, phone number, email and billing address.
Other required inputs, and available options, depend on whether the checkout involves:
Once customers successfully submit the required information, onAddressComplete executes.

Digital and physical products

If any items[] in the checkout-session represent physical products, the modal prompts customers for shipping information. Once validated, Digital River uses it to populate the checkout-session's billTo.
Customers are given the option to input different billing information during the payment stage.
In checkouts that only contain digital products, the modal doesn’t ask for shipping details. Instead, it simply prompts customers for billing information.
Physical products
Digital only products

Registered customers

If you send customerId in the create checkout-session request, customers are given the option to save their shipping and billing information for use in future checkouts. Additionally, if you pass options.addresses[], the modal presents these saved addresses for convenience purposes.
Save address option
Saved addresses

Business to business transactions

If the checkout-session's customerType is business, then customers must provide their company's name when entering both shipping and billing information.
Shipping information
Billing information
If you activate the auto collect customer type feature, then customers are shown a checkbox that asks them whether they’d like to make the purchase on behalf of a business.
If items[] contains physical goods, then this toggle is displayed in the shipping information form. Otherwise, when items[] are all digital, customers are presented with this option while supplying their billing information.

Shipping choice stage

In transactions that contain physical products, the modal next prompts the user to make a shipping choice. For each options.shippingMethods[] in the checkout-session, customers are always shown its description and amount.
Once customers input their shipping choice, onDeliveryComplete is called.

Tax identifiers stage

In applicable checkouts, the modal prompts the customer for a tax identification number.
In guest checkouts, customers can enter a tax identifier but are not given the option to save the value to their account.
​Registered customers with applicable, saved tax identifiers can either select one of the values presented to them or enter a new one.
Registered customers who have no stored, transaction-applicable tax identifiers can save a new value for use in future checkouts. If they select this option, Digital River saves the tax identifier to the customer’s record.
In countries that require tax identifiers, customers must enter a value before proceeding to the payment stage.

Payment stage

In the payment collection stage, the modal only displays payment methods that are appropriate to the transaction. Depending on how you configure the checkout-session and on your Dashboard settings, the modal can also:
Once customers provide payment, agree to the terms, and successfully submit the order, onCheckoutComplete is called.

Saved payment methods

If you pass a customerId in the create checkout session request, we retrieve and display any transaction-applicable payment sources[] that are saved to the referenced customer.

Save a payment method for future purchases

The modal can ask customers whether they'd like to save a payment method for future purchases.
To activate this feature, you must pass customerId in the create checkout session request.
If the resource you reference doesn't exist in your account, then Digital River creates a new customer and assigns it the identifier you passed.
If the payment method selected by customers supports reusability, then the modal asks whether they'd like to save it for future purchases. If customers opt to do so, then, after Digital River creates the source, we save it to that customer.

Custom consents

For each displayed payment method, the modal presents users with the terms of sale and privacy policy of the designated selling entity.
If you save your own consents in Dashboard, then they are appended to Digital River's disclosures. Customers must accept all these terms and disclosures before they are allowed to complete the purchase.
Digital River only disclosures
Combined disclosures
If you don't save customized consents in Dashboard, then the modal only displays Digital River's disclosures.
If you save consents in Dashboard, then the modal displays Digital River's disclosures, along with yours as well.

Order confirmation stage

There are a variety of ways to configure the order confirmation stage. The following is an example of the default option.

Handling the checkout session order created event

Prior to deployment, configure a webhook to listen for the event with a type of checkout_session.order.created.
This event occurs when a customer makes payment, completes checkout and an order is created in Digital River’s system. Its data.object allows you to:
We don’t recommend that you use checkout_session.order.created to trigger order fulfillment. Instead, listen for order.accepted and use it to trigger downstream fulfillment processes.
For details, refer to Handling accepted orders on the Processing orders page.

Save for later

If shipTo.saveForLater and/or billTo.saveForLater are true in the data.object of checkout_session.order.created, then customers requested that their shipping and/or billing information be saved for use in future transactions. You can use this flag to trigger a method that saves the customer's address in your system.
{
"id": "7312d117-4201-4a27-80e3-9e72f7ba2609",
"type": "checkout_session.order.created",
"data": {
"object": {
"id": "213614540336",
"checkoutId": "5dd0a16c-35e0-4451-a8a9-1ac8dc57008f",
"checkoutSessionId": "738d1e74-7efc-488f-9f4b-0f4d18351912",
...
"shipTo": {
...
"saveForLater": true
},
"billTo": {
...
"saveForLater": false
},
...
}

Pricing format

checkout_session.order.created
{
"id": "764ddbdd-0f7e-448d-b044-196f67dd1781",
"type": "checkout_session.order.created",
"data": {
"object": {
...
"pricingFormat": {
"currencyNumberFormat": "#,###.##",
"symbol": "¥",
"decimalPlaces": 0,
"currencySymbolBeforePrice": true,
"useCurrencySymbolSpace": false
},
...
}
},
...
}
This object contains the rules that Digital River used to format prices on your storefront and in the checkout modal. To maintain a consistent format, you can apply these same rules to the prices in your customer notifications and on pages in your site where customers view and manage their orders.
If you don't want to build your own formatter, many server-side languages have pre-built functions that roughly approximate those used by Digital River. Depending on your application, you might find some of the following pages useful:
The following objects are nested in pricingFormat:

currencyNumberFormat

You can use currencyNumberFormat to determine how to display the integer part and fractional part of a price.
Its value indicates whether the character that groups digits in the integer part should be a comma (,), a point (.), an apostrophe ('), a whitespace( ), or some other character. It also dictates the correct spacing of this character.
Additionally, you can use currencyNumberFormat to determine whether the character that separates the price's integer part from its fractional part should be a point or a comma.
Example 1
Example 2
Example 3
Example 4
In the following example, currencyNumberFormat indicates that the digits in the integer part should be grouped by a comma that's placed every third digit to the left of a point, which acts as the separator between the price's integer and fractional parts.
"currencyNumberFormat": "#,###.##"

Target output in UX

​
​
In the following example, currencyNumberFormat indicates that the digits in the integer part should be grouped by a point that's placed every third digit to the left of a comma, which acts as the separator between the price's integer and fractional parts.
"currencyNumberFormat": "#.###,##"

Target output in UX

​
​
In the following example, currencyNumberFormat indicates that the digits in the integer part should first be grouped by a comma that's placed every third digit to the left of a point, which acts as the separator between the price's integer and fractional parts.
After that, digits in the integer part should follow a two-digit grouping pattern.
"currencyNumberFormat": "#,##,###.##"

Target output in UX

​
​
In the following example, currencyNumberFormat indicates that the digits in the integer part should be grouped by an apostrophe that's placed every third digit to the left of a point, which acts as the separator between the price's integer and fractional parts.
"currencyNumberFormat": "#'###.##"

Target output in UX

​
​

symbol

The graphic symbol that should be used to denote the price's currency.
Example 1
Example 2
The following is the symbol for Swiss Francs:
"symbol": "CHF"

Target output in UX

​
​
The following is the symbol for Jordanian Dinars:
"symbol": "د.ا"

Target output in UX

​
​

decimalPlaces

This stipulates the number of digits that should be displayed to the right of the character (whether it's a point or comma) that divides a price's integer part from its fractional part.
If decimalPlaces is 0 and currencyNumberFormat indicates that a character should be placed between the integer and fractional parts, then that character shouldn't be displayed.
{
...
"pricingFormat": {
"currencyNumberFormat": "#,###.##",
...
"decimalPlaces": 0,
...
},
...
}
decimalPlaces value
Target output in UX
0
​
​
2
​
​
3
​
​

currencySymbolBeforePrice

The currencySymbolBeforePrice indicates whether symbol should be placed before or after a price's numeric amount.
currencySymbolBeforePrice value
Target output in UX
true
​
​
false
​
​
​

useCurrencySymbolSpace

The useCurrencySymbolSpace indicates whether or not to insert a whitespace between symbol and the price's numeric amount.
useCurrencySymbolSpace value
Target output in UX
true
​
​
false
​
​

Determining what disclosures customers accepted

The data.object of checkout_session.order.created and the order in onCheckoutComplete both contain consents.
checkout_session.order.created
onCheckoutComplete
{
"id": "1ebfd13c-4ef6-443c-b58a-cb119f1c24fd",
"type": "checkout_session.order.created",
"data": {
"object": {
"id": "1038474530082",
...
"consents": {
"termsOfService": true,
"eula": true,
"termsOfSale": true
},
...
}
},
...
}
{
"id": "1038474530082",
...,
"consents": {
"termsOfService": true,
"eula": true,
"termsOfSale": true
},
"liveMode": false
}
In this object, the termsOfSale boolean references Digital River's terms of sale. The eula and termsOfService reference your company's unique end user license agreement and service terms, respectively.
When any of these attributes are true, it signifies that customers were presented with that specific disclosure in the checkout payment stage and they actively accepted it.
For details on how to append your company's disclosures to Digital River's disclosures, refer to Prebuilt Checkout configurations in the Dashboard documentation.
Previous
e-Invoicing
Next
Offering local pricing
Last modified 17d ago