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

During the early stages of an ecommerce transaction, customers land on your storefront, review products and build a cart. Digital River is typically not involved in these early pre-checkout interactions. Once the customer initiates checkout, you start interacting with Prebuilt 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.
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": "ヤマダ タロ"
}
}
]
}
}'
{
"id": "eb3b9cc3-d068-4300-9488-c88c0341b5db"
...
}
Add the following link on your checkout page.
<script src="https://checkout.digitalriverws.com/v1/DigitalRiverCheckout.js"></script>
const drCheckout = new DigitalRiverCheckout('YOUR_PUBLIC_API_KEY');
Build a configuration object and then pass it and the checkout session identifier to
createModal()
.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);
});
Customers then proceed through the stages of a checkout. Customers are always required to provide their name, phone number, email address, billing address, and payment method. Depending on how you configure the checkout-session, they may also be prompted to specify a shipping address, shipping option and/or tax identifier.
In checkouts that contain physical products, the modal first prompts the user for shipping information and then uses this same data to populate billing information. Later, during the payment stage, the customer does however have the option to provide different billing information.
.png?alt=media&token=55479848-d3ea-488b-b305-ae102bef53dc)
In checkouts that only contain digital products, the modal doesn’t ask for shipping details. Instead, it simply prompts the user for billing information.
.png?alt=media&token=d70e8ea3-edb3-4b4e-b9ba-4a68c6111b44)
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..png?alt=media&token=05118a36-a07e-4bf7-b341-bc58ba07f0c5)
If you send
options.addresses[]
in the create checkout-session request, then the modal has the capability to present these saved addresses to the customer. If the customer uses the radio button control to select one of them, its values are populated in the address collection form.
When customers click the continue checkout button,
onAddressComplete
triggers an event that contains an address
. This object contains the billing
and shipping
information submitted by the customer.{
“billing”: {
“address”: {
“line1”: “10380 Bren Rd W”,
“city”: “Minnetonka”,Z
“postalCode”: “55129”,
“state”: “MN”,
“country”: “US”
},
“name”: “Jane Smith”,
“phone”: “5555555555”,
“email”: “[email protected]”,
“saveForLater”: false
},
“shipping”: {
“address”: {
“line1”: “10380 Bren Rd W”,
“city”: “Minnetonka”,
“postalCode”: “55129”,
“state”: “MN”,
“country”: “US”
},
“name”: “Jane Smith”,
“phone”: “5555555555”,
“email”: “[email protected]”,
“saveForLater”: true
}
}
In transactions that contain physical products, the modal prompts the user to make a shipping choice. For each of the checkout-session's
shippingMethods
customers are shown its description
and amount
..png?alt=media&token=15332979-b10b-4456-9c62-36528f1537e3)
When customers click the continue checkout button,
onDeliveryComplete
triggers an event that returns a shippingMethod
. This object contains the shipping options selected by the customer, along with a calculated taxAmount
.{
“amount”: 15,
“description”: “Next Day Air”,
“serviceLevel”: “ND”,
“taxAmount”: 1.11
}
In guest checkouts, customers can enter a tax identifier but are not given the option to save the value.
.png?alt=media&token=c0d45c9e-498c-41f0-9bd6-ff4450ecb2e5)
Registered customers with applicable, saved tax identifiers can either select one of the values presented to them or enter a new one.
.png?alt=media&token=a1f42c3c-cdac-41a7-b5f0-84e4d5e73ec5)
Registered customers with 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.
.png?alt=media&token=a44bfb03-02c8-42c9-a228-b7ae8f6b1ca9)
In countries that require tax identifiers, customers must enter a value before proceeding to the payment stage.
In the payment collection stage, the modal only displays payment methods that are appropriate to the transaction. Depending on your setup, the modal might also display saved payment methods and custom consents.
When you pass a
customerId
in the create checkout session request, then we retrieve and display any transaction-applicable payment sources[]
that are saved to the referenced customer. Guest checkout
Registered checkout


For each of these payment methods, the modal also presents users with the terms of sale and privacy policy of the designated selling entity.
If you configure your own consents in Dashboard, then they are appended to Digital River's disclosures. Customers must accept all these terms and disclosures before placing the order.
Digital River only disclosures
Combined disclosures
If you have no customized consents in Dashboard, then the modal only displays Digital River's disclosures.

If you add consents in Dashboard, then the modal displays Digital River's disclosures, along with yours as well.

Once customers provide payment, agree to the terms, and successfully submit the order,
onCheckoutComplete
triggers an event that returns an order
.Depending on how you configure the order confirmation stage, you can retrieve relevant data from the object (such as
id
) and display it to customers on a customized page.The following is an example of the default order confirmation window.

{
"id": "dacc88d7-3f88-469b-9764-35a15681e6c9",
"type": "checkout_session.order.created",
"data": {
"object": {
"id": "245558830336",
"checkoutId": "b02686da-decf-4122-b922-d7dc39ed8a08",
"checkoutSessionId": "158214a9-0a91-41bf-86eb-0aa9b7c713cc",
"createdTime": "2022-11-08T20:39:17Z",
"currency": "KRW",
"email": "[email protected]",
"shipTo": {
"address": {
"line1": "123 Elm St",
"city": "Plainsville",
"postalCode": "55404",
"state": "MN",
"country": "US"
},
"name": "John Doe",
"phone": "6124327861",
"email": "[email protected]",
"saveForLater": false
},
"shipFrom": {
"address": {
"country": "KR"
}
},
"billTo": {
"address": {
"line1": "123 Elm St",
"city": "Plainsville",
"postalCode": "55404",
"state": "MN",
"country": "US"
},
"name": "John Doe",
"phone": "6124327861",
"email": "[email protected]",
"saveForLater": false
},
"totalAmount": 139000.0,
"subtotal": 139000.0,
"totalFees": 0.0,
"totalTax": 0.0,
"totalImporterTax": 0.0,
"totalDuty": 0.0,
"totalDiscount": 0.0,
"totalShipping": 7000.0,
"items": [
{
"id": "174292610336",
"sku": {
"id": "sku-phy-thor-gb",
"name": "Thor's Ankleboot",
"eccn": "EAR99",
"taxCode": "531029.200",
"image": "https://drapi.io/img/prod/shoes_men_ankleboot.png",
"physical": true
},
"amount": 132000.0,
"quantity": 1,
"tax": {
"rate": 0.0,
"amount": 0.0
},
"importerTax": {
"amount": 0.0
},
"duties": {
"amount": 0.0
},
"availableToRefundAmount": 0.0,
"fees": {
"amount": 0.0,
"taxAmount": 0.0
}
}
],
"shippingChoice": {
"amount": 7000.0,
"description": "Standard Shipping",
"serviceLevel": "SG",
"taxAmount": 0.0
},
"updatedTime": "2022-11-08T20:39:17Z",
"locale": "en_US",
"customerType": "individual",
"sellingEntity": {
"id": "DR_INC-ENTITY",
"name": "Digital River Inc."
},
"payment": {
"charges": [
{
"id": "241c56c8-82bc-434f-a761-7bfba9c515de",
"createdTime": "2022-11-08T20:39:19Z",
"currency": "KRW",
"amount": 139000.0,
"state": "capturable",
"captured": false,
"refunded": false,
"sourceId": "2d7caab1-4607-4d8a-93b7-1df132b097aa",
"type": "customer_initiated"
}
],
"sources": [
{
"id": "2d7caab1-4607-4d8a-93b7-1df132b097aa",
"createdTime": "2022-11-08T20:39:14Z",
"type": "creditCard",
"currency": "KRW",
"amount": 139000.0,
"reusable": false,
"state": "consumed",
"owner": {
"firstName": "John",
"lastName": "Doe",
"email": "[email protected]",
"address": {
"line1": "123 Elm St",
"city": "Plainsville",
"postalCode": "55404",
"state": "MN",
"country": "US"
}
},
"paymentSessionId": "478274eb-2e61-4016-8665-fc9171c7e470",
"clientSecret": "2d7caab1-4607-4d8a-93b7-1df132b097aa_ecdd5072-3360-487b-81a1-73557bab12be",
"creditCard": {
"brand": "MasterCard",
"expirationMonth": 12,
"expirationYear": 2023,
"lastFourDigits": "0008",
"fundingSource": "credit"
}
}
],
"session": {
"id": "478274eb-2e61-4016-8665-fc9171c7e470",
"amountContributed": 139000.0,
"amountRemainingToBeContributed": 0.0,
"state": "complete",
"clientSecret": "478274eb-2e61-4016-8665-fc9171c7e470_078fe948-c882-4b99-bc28-d5d15223e9bf"
}
},
"state": "accepted",
"stateTransitions": {
"accepted": "2022-11-08T20:39:20Z"
},
"fraudState": "passed",
"fraudStateTransitions": {
"passed": "2022-11-08T20:39:20Z"
},
"taxInclusive": false,
"consents": {
"termsOfService": true,
"eula": true,
"termsOfSale": true
},
"pricingFormat": {
"currencyNumberFormat": "#,###.##",
"symbol": "₩",
"decimalPlaces": 0,
"currencySymbolBeforePrice": true,
"useCurrencySymbolSpace": false
},
"liveMode": false
}
},
"liveMode": false,
"createdTime": "2022-11-08T20:39:21.54565Z",
"digitalriverVersion": "2021-03-23"
}
This event occurs when a customer makes payment, completes checkout and an order is created in Digital River’s system. The event allows you to:
We don’t recommend that you use
checkout_session.order.created
to trigger order fulfillment. Instead, listen for the order.accepted
event and use it to drive downstream fulfillment processes.If
shipTo.saveForLater
and/or billTo.saveForLater
are true
in the checkout_session.order.created
event’s data.object
, 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 address to the customer 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
},
...
}
If you enable the local pricing service, then
pricingFormat
is returned in onCheckoutComplete
and checkout_session.order.created
. 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 displayed in notifications you send to customers 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
: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": "#,###.##"

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": "#.###,##"

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": "#,##,###.##"

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": "#'###.##"

The graphic
symbol
that should be used to denote the price's currency.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 | ![]() |
The
currencySymbolBeforePrice
indicates whether symbol
should be placed before or after a price's numeric amount.currencySymbolBeforePrice value | Target output in UX |
---|---|
true | ![]() |
false | ![]() |
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 | ![]() |
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 event variables 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.
Last modified 2d ago