Prebuilt Checkout

Drop-in Checkout is a configurable checkout experience that allows you to connect an upstream commerce system with Digital River's payment processing, fraud detection, tax exemption, and disclosure services.
The Drop-in Checkout solution reduces the complexity of integrating with the Digital River APIs and the DigitalRiver.js library, thereby shortening your time to deployment.
Once customers build a cart and initiate checkout, a Drop-in Checkout integration needs to:
​Define a checkout-session request​
​Create a checkout-session​
Use the checkout-session identifier to create a checkout modal window​
​Handle the checkout session order created event​
Building a cart
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 Drop-in 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 Defining a checkout-session 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 Drop-in Checkout modal.
Creating a Drop-in Checkout modal
Add the following Digital River checkout library link to your checkout pages.
<script src="https://checkout.digitalriverws.com/v1/DigitalRiverCheckout.js"></script>
Use your public API key to create a Digital River checkout object.
const drCheckout = new DigitalRiverCheckout('YOUR_PUBLIC_API_KEY');
Respond to checkout button click events by building a configuration object and then passing it and the checkout session identifier to the createModal() method.
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.
Drop-in Checkout modal window
After createModal() is invoked, the Drop-in Checkout modal window opens and the onReady event occurs.
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.
Name and address stage
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 details.
In checkouts that only contain digital products, the modal doesn’t ask for shipping details. Instead, it simply prompts the user for billing information.
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.
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
    }
}
Shipping choice stage
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.
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
}
Tax identifiers stage
In applicable checkouts, the modal prompts the customer for a tax identifier.
In guest checkouts, customers can enter a tax identifier but are not given the option to save the value.
​Registered customers with applicable, saved tax identifiers can either select one of the values presented to them or enter a new one.
​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.
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. 
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 use Dashboard to provide Digital River your company's unique disclosures, then they are displayed too. Customers must accept all these terms before placing the order.  
For more details, refer to Determining what disclosures customers accepted.
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
​
​
Order confirmation stage
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.
Handling the checkout session order created event
Prior to deployment, configure a webhook to listen for the checkout_session.order.created event.
{
    "id": "1ebfd13c-4ef6-443c-b58a-cb119f1c24fd",
    "type": "checkout_session.order.created",
    "data": {
        "object": {
            "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.0,
            "totalFees": 0.0,
            "totalTax": 0.74,
            "totalImporterTax": 0.0,
            "totalDuty": 0.0,
            "totalDiscount": 0.0,
            "totalShipping": 5.0,
            "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.0,
                    "quantity": 1,
                    "tax": {
                        "rate": 0.07375,
                        "amount": 0.37
                    },
                    "importerTax": {
                        "amount": 0.0
                    },
                    "duties": {
                        "amount": 0.0
                    },
                    "availableToRefundAmount": 0.0,
                    "fees": {
                        "amount": 0.0,
                        "taxAmount": 0.0
                    }
                }
            ],
            "shippingChoice": {
                "amount": 5.0,
                "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.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
        }
    },
    "liveMode": false,
    "createdTime": "2022-07-11T19:22:53.494589Z",
    "digitalriverVersion": "2021-02-23"
}
This event occurs when a customer successfully completes checkout and an order is created in Digital River’s system. Handle the event by first determining whether customers requested that their shipping and billing information be saved for later, and then, if necessary, update the customer's record in your system.
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.
For more information, refer to Events early in the order lifecycle on the Processing orders page.
Save for later
If shipTo.saveForLater and/or billTo.saveForLater are true in the checkout_session.order.created event’s data.object, then customers opted to save their shipping and/or billing information for use in future transactions. You can use this as a flag to trigger a method that updates the customer’s saved addresses 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
            },
             ...
}
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 event variables are true, it signifies that customers were presented with that specific disclosure in the checkout modal's payment stage and they actively accepted it. 
For details on how to append your company's disclosures to Digital River's disclosures, refer to Create a Drop-in Checkout configuration in the Dashboard documentation.