Implementing a Prebuilt Checkout

Gain a basic understanding of how to add a Prebuilt Checkout to your site

Prebuilt Checkout is a customizable checkout experience that connects an upstream commerce system with Digital River's local pricing, logistics, subscriptions, payment, fraud detection, tax exemption, and disclosure services.

The Prebuilt Checkout solution simplifies integrating with the Digital River APIs and our front-end libraries, thereby shortening the 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. Digital River is typically not involved in these early pre-checkout interactions unless you engage our local pricing service. However, once customers initiate checkout, you must 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 create checkout window 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.

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>

Use your public API key to create a DigitalRiverCheckout object.

Next, you'll most likely want to build a configuration object.

Then, depending on whether you'd like Prebuilt Checkout to display in a modal or an iframe, pass that object and the checkout session identifier to either createModal() or embed(), respectively.

document.getElementById('YOUR_CHECKOUT_BUTTON_ID').addEventListener('click', async (event) => {
  
   //Invokes a client defined function that creates a checkout session
   const checkoutSessionId = await createCheckoutSession();
  
   // Creates a Prebuilt Checkout and displays it in a modal window
   drCheckout.createModal(checkoutSessionId, config);
});

document.getElementById('YOUR_CHECKOUT_BUTTON_ID').addEventListener('click', async (event) => {
  
   //Invokes a client defined function that creates a checkout session
   const checkoutSessionId = await createCheckoutSession();
  
   // Creates a Prebuilt Checkout and displays it in an iframe
   drCheckout.embed(checkoutSessionId, config);
});

After createModal() or embed() is invoked, the checkout window opens and onReady executes.

Depending on how the checkout-session is configured, the experience takes customers through various stages:

Name and address stage

Customers must always provide their name, phone number, email, and billing address at this stage.

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, customers are prompted for shipping information. Once validated, Digital River uses it to populate the checkout-session's shipTo and billTo.

Customers are given the option to input different billing information during the payment stage.

The experience doesn’t ask for shipping details in checkouts containing digital products. Instead, it simply prompts customers for billing information.

Registered customers

If you send customerId in the create checkout-session request, customers can save their shipping and billing information for future checkouts. If you pass options.addresses[], customers are presented with these saved addresses for convenience.

Business-to-business transactions

If the checkout-session's customerType is business, then customers must provide their company's name when entering shipping and billing information.

If you activate the auto collect customer type feature, customers are shown a checkbox asking them whether they’d like to purchase on behalf of a business.

If items[] contains physical goods, and 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

The experience prompts the user to choose shipping in transactions containing physical products. For each options.shippingMethods[] in the checkout-session, customers are always shown its description and amount.

Once customers input their shipping choice, onDeliveryComplete executes.

Tax identifiers stage

The experience prompts the customer for their tax identification number for applicable checkouts.

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, customers are only shown payment methods that are appropriate to the transaction. Depending on how you configure the checkout-session and on your Digital River Dashboard settings, the experience can also:

Once customers provide payment, agree to the terms, and successfully submit the order, onCheckout Complete 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

Prebuilt Checkout can ask customers whether they'd like to save a payment method for future purchases.

You must pass customerId in the create checkout session request to activate this feature.

If the resource you reference doesn't exist in your account, Digital River creates a new customer and assigns it the identifier you passed.

If the payment method customers select supports reusability, they are asked whether they'd like to save it for future purchases. If they opt to do so, we save it for that customer after Digital River creates the source.

Custom consents

Prebuilt Checkout presents users with the designated selling entity's terms of sale and privacy policy for each displayed payment method.

If you save your own consents in the Dashboard, they are appended to Digital River's disclosures. Customers must accept all these terms and disclosures before completing the purchase.

To determine what disclosures customers accepted, you can configure a webhook to listen for the event with a type of checkout_session.order.created.