LogoLogo
System Status
  • Digital River API
  • Getting started
  • Using our services
    • Local pricing
    • Item classification
    • Subscriptions
    • e-Invoicing
  • Integration options
    • Low-code checkouts
      • Implementing a Prebuilt Checkout
      • Implementing a Components checkout
      • Offering local pricing
      • Using a shipping endpoint
      • Processing subscription acquisitions
      • Adding custom fields
      • Offering store credit
      • Displaying policies and getting consent
      • Collecting e-invoice information
      • Handling completed checkout-sessions
    • Direct integrations
      • Standard flow
      • Building checkouts
        • Checking out guest and registered customers
        • Describing line items
          • Setting the price of an item
          • Managing items with shared SKU identifiers
        • Providing address information
        • Handling shipping choice
        • Tax identifiers
        • Applying a discount
        • Setting the customer type
        • Providing the IP address
        • Selecting a currency
        • Initiating a charge
        • Setting the purchase location
        • Configuring taxes
        • Accessing regulatory fee information
        • Localizing invoices and credit memos
        • Providing an upstream identifier
        • Applying store credit
        • Handling e-invoicing requirements
        • Landed cost
        • Tax calculation inputs
        • Selling entities
        • Payment sessions
        • Applying store credit (legacy)
        • Country specs
      • Building payment workflows
        • Handling redirect payment methods
        • Handling delayed payment methods
      • Subscription acquisitions
        • Handling subscription acquisitions
        • Handling external subscription acquisitions
        • Subscription information
      • Digital River coordinated fulfillments
        • Checking inventory levels
        • Using shipping quotes
        • Reserving inventory items
        • Managing a fulfillment order
        • Cancelling a fulfillment order
    • Connectors
  • Order management
    • Processing orders
    • Handling a rejected order
    • Accessing invoices and credit memos
    • Fulfilling goods and services
    • Capturing and cancelling charges
    • Payment reauthorizations
    • Handling reversals
      • Return basics
        • Digital River coordinated returns
        • Third party coordinated returns
      • Refund basics
        • Issuing refunds
        • Refunding asynchronous payment methods
      • Disputes and chargebacks
    • Customer notifications
    • Responding to events
      • Events
        • Key event types
        • All event types
      • Webhooks
        • Creating a webhook
        • Digital River API safelist
        • Digital River signature
      • Expanding events
      • Preventing webhooks from getting disabled
    • Distributor model
  • Subscription Management
    • Managing a subscription
    • Managing an external subscription
  • Payments
    • Payment solutions
      • Drop-in payments
        • How Drop-in payments work
        • Drop-in payments integration guide
      • DigitalRiver.js with Elements
        • Elements integration guide
        • Configuring payment methods
          • Configuring Afterpay
          • Configuring Alipay+ (cross-border)
          • Configuring Alipay (domestic)
          • Configuring Amazon Pay
          • Configuring Apple Pay
          • Configuring Bancontact
          • Configuring BNP Paribas
          • Configuring BLIK
          • Configuring CCAvenue
          • Configuring Clearpay
          • Configuring Credit Cards
          • Configuring FPX Online Banking
          • Configuring Google Pay
          • Configuring iDEAL
          • Configuring Klarna
          • Configuring Konbini
          • Configuring Online Banking (IBP)
          • Configuring Online Banking (Korea Bank Transfer)
          • Configuring PayCo
          • Configuring PayPal
          • Configuring SEPA Direct Debit
          • Configuring Trustly
          • Configuring Wire Transfer
          • Common payment sources
          • Common payment objects
    • Supported payment methods
      • Afterpay
      • Alipay (domestic)
      • Alipay+ (cross-border)
      • Amazon Pay
      • Apple Pay
      • Bancontact
      • BNP Paribas
      • BLIK
      • CCAvenue
      • Clearpay
      • Credit Cards
      • FPX Online Banking
      • Google Pay
      • iDEAL
      • Klarna
      • Konbini
      • Korea Bank Transfer (Online Banking)
      • Online Banking (IBP)
      • Pay with Installments France
      • PayCo
      • PayPal
      • PayPal Billing Agreement
      • PayPal Credit
      • PayPal Pay in 3
      • PayPal Pay in 4
      • PayPal RatenZahlung (Installment Payment)
      • SEPA Direct Debit
      • Trustly
      • Wire Transfer
    • Source basics
      • Managing sources
      • Handling credit card sources
      • Retrieving sources
    • Authorization declines
    • PSD2 and SCA
      • How to ensure SCA compliance
    • Payment testing scenarios
  • Product management
    • Product basics
    • Managing SKUs
    • Using product details
    • Grouping SKUs
    • SKU-inventory item pairs
    • Managing inventory items
    • Regulatory fees
      • What are regulatory fees?
        • Fees terminology
        • Regulatory fee management
        • European regulatory fees
        • Compliance obligations
        • WEEE directive requirements
        • Copyright directive requirements
        • Compliance challenges
      • Managing regulatory fees
  • Customer management
    • Customer basics
    • Creating and updating customers
    • Setting up tax exemptions
    • Recording a customer's request to be forgotten
  • Financial reporting
    • Financials basics
    • Sales transactions
      • Returning a list of sales transactions
      • Getting a sales transaction by ID
    • Sales summaries
      • Returning a list of sales summaries
      • Getting a sales summary by ID
    • Payouts
      • Returning a list of payouts
      • Getting a payout by ID
      • Get a list of transactions included in payout by ID
  • Developer resources
    • Digital River API reference
    • DigitalRiver.js reference
      • Including DigitalRiver.js
      • Initializing DigitalRiver.js
      • DigitalRiver object
      • Elements
        • Amazon Pay element
        • Apple Pay elements
        • Google Pay elements
        • IBAN element
        • iDEAL element
        • Konbini elements
        • Compliance element
        • Offline Refund elements
        • Online Banking elements
        • Tax Identifier element
        • Invoice attribute element
        • Delayed Payment Instructions element
        • PayPal elements
      • Guidelines for capturing payment details
      • Security
      • Digital River payment objects
      • Error types, codes, and objects
    • DigitalRiverCheckout.js reference
      • Including DigitalRiverCheckout.js
      • Initializing DigitalRiverCheckout.js
        • DigitalRiverCheckout configuration object
      • DigitalRiverCheckout object
        • Configuring Prebuilt Checkout
          • Performing actions
          • Defining experience
        • Components
          • Configuring components
          • Address component
          • Shipping component
          • Tax identifier component
          • Invoice component
          • Wallet component
          • Payment component
          • Compliance component
          • Order summary component
          • Thank you component
        • Rendering a checkout button
          • Performing actions on the checkout button
        • Determining the checkout's status
      • Accessing country and currency
    • DynamicPricing.js reference
    • Postman collection
  • administration
    • Sign in
    • Digital River Dashboard
      • Digital River Dashboard quick start guide
      • Key features
      • Reset your password
      • Test and production environments
      • Account
        • Adding an account
        • Switching accounts
        • Account access
      • Profile settings
        • Viewing your personal information
        • Changing your password
        • Updating your phone number
        • Enabling multi-factor authentication
      • Finance
        • Payouts
          • Viewing your payout details
          • Filtering your payouts
          • Exporting your payouts
        • Sales summaries
          • Viewing your sales summaries details
          • Filtering your sales summaries
          • Exporting your sales summaries
          • Exporting your sales summary details
        • Transactions
          • Viewing your transaction details
          • Filtering your transactions
          • Exporting your transactions
      • Order management
        • Orders
          • Searching for orders
          • Filtering your orders
          • Viewing the order details
          • Cancelling items
          • Fulfilling items
          • Downloading an invoice
          • Downloading a credit memo
          • Creating shipping labels
          • Recording a customer's request to be forgotten
          • Viewing returns and refunds
          • Creating a return
          • Accepting a return
          • Creating a refund
          • Viewing the order's timeline
        • Checkouts
          • Searching for checkouts
          • Filtering your checkouts
          • Viewing the checkout details
        • Prebuilt Checkout links
          • Generate Prebuilt Checkout links
          • View and work with Prebuilt Checkout link details
          • Add a customer during Prebuilt Checkout
          • Add a product during Prebuilt Checkout
      • Customers
        • Viewing customer details
        • Searching for customers
        • Filtering your customers
        • Editing account information
        • Adding a customer
        • Tax IDs and certificates
          • Adding a tax certificate
          • Adding a tax ID
          • Deleting a tax ID
        • Metadata
          • Adding metadata
          • Editing metadata
        • Manage subscriptions from the Customer Details page
        • Disabling a customer
        • Recording a customer's request to be forgotten
        • Deleting a customer
      • Catalog
        • SKUs
          • Viewing the SKU details
          • Searching for SKUs
          • Filtering your SKUs
          • Adding a SKU
          • Editing a SKU
          • Deleting a SKU
          • Adding a fee to a SKU
          • Editing a fee
          • Deleting a fee
          • Viewing product tariff codes
        • Managing customer subscriptions from Digital River Dashboard
      • Developers
        • API keys
          • Updating your API version
          • Getting your API keys
          • Changing the API version for your key
          • Creating a restricted key
          • Editing a restricted key
          • Deleting a restricted key
          • Rotating keys
        • Webhooks
          • Creating a webhook
          • Editing a webhook
          • Deleting a webhook
          • Rotating a webhook's secret
        • API logs
          • Filtering the API log
          • Viewing the API log details
        • Event logs
          • Filtering the events log
          • Viewing the event details
      • Settings
        • Users and roles
          • Roles
          • Searching for a user by name or email
          • Filtering your users and roles
          • Adding a user
          • Editing a user
          • Deleting a user
        • Prebuilt Checkout
        • Payment methods
          • Viewing your payment methods
          • Viewing payment method details
            • Enabling currencies
            • Managing countries
          • Enabling or disabling a payment method
  • General Resources
    • eCompass
    • eCompass documentation
    • Release notes
      • 2024
      • 2023
      • 2022
      • 2021
      • 2020
      • 2019
    • Standards and certifications
      • Certification process
      • Compliance requirements
      • Documentation requirements
      • Integration checklists
        • Admin portal
        • Products and SKUs
        • Customers and tax exemptions
        • Checkouts, payment sources, and orders
        • Disclosures, compliance statements, and emails
        • Fulfillments and cancellations
        • Customer portal
        • Order refund synchronization
        • Reversals
        • Error handling
      • Test and use cases
    • Commerce infrastructure
    • Versioning
    • Glossary
Powered by GitBook
On this page
  • Sequencing the checkout process
  • Initiating the checkout process
  • Sending the create checkout request
  • Displaying compliance disclosures
  • Handling guest and registered customers
  • Handling shipping quotes
  • Collecting payment
  • Applying payment
  • Submitting the order
  • Defining a checkout
  • Creating and updating the checkout
  • Using the checkout
  • Checkout identifier
  • Item information
  • Payment session
  1. Integration options
  2. Direct integrations

Building checkouts

Learn the basics of how to sequence the checkout process as well as define, create, update, and use checkouts

PreviousStandard flowNextChecking out guest and registered customers

Last updated 2 months ago

Your site's checkout experience should contain pages for customers to provide their shipping address, billing address, and payment information. Your site should also have an order review and submission page. Once customers place the order, we recommend you direct them to an order confirmation page.

On this page, you’ll find information on how to:

Sequencing the checkout process

During the initial stages of an eCommerce transaction, customers land on your storefront, review products, build a cart, confirm the cart's details, and initiate checkout. Digital River is typically not involved during these early pre-checkout interactions.

As a result, this section doesn't provide guidance on how to structure these early transaction stages. Instead, it focuses on how to initiate the checkout process. Then, for shopping carts containing , it explains how to sequence the create and update requests and the create and authenticate requests that you send to Digital River.

Initiating the checkout process

Once customers start adding items to their cart, we recommend you activate a proceed to checkout button. We recommend a similar button on your review cart page. Each button’s click event handler should direct customers to your initial checkout page.

Sending the create checkout request

Once customers click the proceed to checkout button, we recommend using your checkout pages to obtain their shipping and billing addresses. Once customers enter new address information or confirm saved information, retrieve and save that data.

You can then use this saved address data, along with product data in the customer's cart, to define , and and then submit the .

Since you can’t with additional items[] or modify the quantity of existing items[], this sequence reduces the probability that customers will add products to their cart after you submit the create checkout request.

Displaying compliance disclosures

Handling guest and registered customers

Handling shipping quotes

Collecting payment

Both methods also require the customer’s billing address. Unless the customer indicates otherwise, you can use the address you collected earlier in the checkout process.

Applying payment

Once the payment source is successfully created or authenticated, you must apply it to the checkout.

For more information on payments, refer to:

Submitting the order

Defining a checkout

Parameter
Request type availability
Documentation

customerId

Both

sourceId

Both

currency

Both

creditAmount*

Both

email

Both

locale

Both

browserIp

Both

shipFrom

Both

shipTo

Both

billTo

Both

shippingChoice

Both

discount

Create

items☨

Both

shippingDiscount

Create

taxInclusive

Create

chargeType

Both

taxIdentifiers

Both

customerType

Create

purchaseLocation

Both

upstreamId

Both

*The creditAmountparameter is only available in versions 2020-09-30, 2020-12-17, and 2021-02-23

Creating and updating the checkout

curl --location --request POST 'https://api.digitalriver.com/checkouts' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API_key>' \
...
--data-raw '{
    "currency": "USD",
    "customerId": 529861350336,
    "taxInclusive": false,
    "email": "anyemail@digitalriver.com",
    "shipTo": {
        "address": {
            "line1": "10380 Bren Road W",
            "city": "Minnetonka",
            "postalCode": "55343",
            "state": "MN",
            "country": "US"
        },
        "name": "John Doe"
    },
    "shipFrom": {
        "address": {
            "country": "US"
        }
    },
    "shippingChoice": {
        "amount": 5,
        "description": "standard",
        "serviceLevel": "SG"
    },
    "items": [
        {
            "skuId": "6b04ac06-0858-456c-90aa-235772dea9e2",
            "quantity": 2,
            "price": 10
        }
    ]
}'

Using the checkout

Each time you submit a POST/checkouts or POST/checkouts/{id} request, use the data in the response to update the data in the upstream commerce platform. This ensures that the values in your system stay in sync with ours.

{
    ...
    "totalAmount": 48.4,
    "subtotal": 45.0,
    "totalFees": 0.0,
    "totalTax": 3.4,
    "totalImporterTax": 0.0,
    "totalDuty": 0.0,
    "totalDiscount": 0.0,
    "totalShipping": 5.0,
    "items": [
        {
            "id": "4e0afb3e-39d1-4b94-a775-cdce3f521fa1",
            "skuId": "0ce492d2-e616-47ac-ad63-6df027577c12",
            "amount": 20.0,
            "quantity": 2,
            "tax": {
                "rate": 0.07525,
                "amount": 1.51
            },
            "importerTax": {
                "amount": 0.0
            },
            "duties": {
                "amount": 0.0
            },
            "fees": {
                "amount": 0.0,
                "taxAmount": 0.0
            }
        },
        ...
}

Checkout identifier

{
    "id": "f2cd50e5-355d-42d3-8bb7-0c14d8b777e4",
    ...
}

Item information

{
    "id": "ec03be84-d684-48a1-b4f4-4dbc05313c93",
    ...
    "items": [
        {
            "id": "50e69e0a-8e36-4ef9-84a0-45eea7535247",
            "skuId": "3a4ad0c5-1640-471e-a6b7-232454474659",
            "amount": 20.0,
            "quantity": 2,
            ...
        }
    ],
    ...
}
{
    "id": "227256090336",
    ...
    "items": [
        {
            "id": "153193900336",
            "skuId": "3a4ad0c5-1640-471e-a6b7-232454474659",
            "amount": 20.0,
            "quantity": 2,
            ...
        }
    ],
    ...
    "checkoutId": "ec03be84-d684-48a1-b4f4-4dbc05313c93"
}

Payment session

Payment session identifier

In versions 2021-02-23 and lower, you find this identifier in the paymentSessionId attribute. In versions 2021-03-23 and higher, it's contained in payment.session.id.

Payment session information

This data is only returned in versions 2021-03-23 and higher.

{
    "id": "f2cd50e5-355d-42d3-8bb7-0c14d8b777e4",
    "createdTime": "2021-03-23T17:34:17Z",
    "customerId": "530359580336",
    "currency": "USD",
    "email": "anyemail@digitalriver.com",
    "shipTo": {
        "address": {
            "line1": "10380 Bren Road W",
            "city": "Minnetonka",
            "postalCode": "55343",
            "state": "MN",
            "country": "US"
        },
        "name": "John Doe"
    },
    "shipFrom": {
        "address": {
            "country": "US"
        }
    },
    "totalAmount": 26.89,
    "subtotal": 25.0,
    "totalFees": 0.0,
    "totalTax": 1.89,
    "totalImporterTax": 0.0,
    "totalDuty": 0.0,
    "totalDiscount": 0.0,
    "totalShipping": 5.0,
    "items": [
        {
            "id": "c9f8d629-e01d-4c89-8c0a-0a0715a07d52",
            "skuId": "6b04ac06-0858-456c-90aa-235772dea9e2",
            "amount": 20.0,
            "quantity": 2,
            "tax": {
                "rate": 0.07525,
                "amount": 1.51
            },
            "importerTax": {
                "amount": 0.0
            },
            "duties": {
                "amount": 0.0
            },
            "subscriptionInfo": {
                "terms": "These are the terms",
                "autoRenewal": false,
                "freeTrial": false
            },
            "fees": {
                "amount": 0.0,
                "taxAmount": 0.0
            }
        }
    ],
    "shippingChoice": {
        "amount": 5.0,
        "description": "standard",
        "serviceLevel": "SG",
        "taxAmount": 0.38
    },
    "updatedTime": "2021-03-23T17:34:17Z",
    "locale": "en_US",
    "customerType": "individual",
    "sellingEntity": {
        "id": "C5_INC-ENTITY",
        "name": "DR globalTech Inc."
    },
    "liveMode": false,
    "payment": {
        "sources": [
            {
                "id": "bea8171b-d2bc-44e4-8d7f-1700e65b09ab",
                "type": "creditCard",
                "amount": 16.89,
                "owner": {
                    "firstName": "William",
                    "lastName": "Brown",
                    "email": "null@digitalriver.com",
                    "address": {
                        "line1": "10380 Bren Rd W",
                        "city": "Minnetonka",
                        "postalCode": "55343",
                        "state": "MN",
                        "country": "US"
                    }
                },
                "creditCard": {
                    "brand": "Visa",
                    "expirationMonth": 7,
                    "expirationYear": 2027,
                    "lastFourDigits": "1111"
                }
            },
            {
                "id": "38818373-7db9-41d9-8895-5667fea13a0b",
                "type": "customerCredit",
                "amount": 10.0,
                "customerCredit": {}
            }
        ],
        "session": {
            "id": "89bd1d59-1ba0-439f-af96-29230421725c",
            "amountContributed": 26.89,
            "amountRemainingToBeContributed": 0.0,
            "state": "requires_confirmation",
            "clientSecret": "89bd1d59-1ba0-439f-af96-29230421725c_5ca86d31-3b21-4d50-b730-9f992b260226"
        }
    }
}

It also provides Digital River with the data we need to generate a that you can display to the customer.

For more information, refer to on the page.

You must display disclosures on all of your checkout pages, typically in the footer. You can use the to do this.

Each time you access the , determine whether sellingEntity.id, language, and shipTo.address.country or billTo.address.country exist, and, if they do, use them to define compliance.entity, compliance.language, and compliance.country, respectively, in and then pass that data to the or method.

This ensures customers are shown localized disclosures relevant to their shopping country and the transaction's designated .

If your integration only allows , you must prompt customers to sign in or create an account at some point during the checkout process. When customers create an account, use the to in Digital River’s system.

In registered checkouts, you can use the same API to and retrieve previously saved shipping information. To expedite the checkout process, you may present this saved shipping address to the customer as an available option.

If you allow , collect and send us the customer's email address. For more information, refer to on the page.

If the shopping cart contains , once you have the customer's ship-to information, you’ll typically request a shipping quote from your logistics partner. In most cases, your partner replies with an array of quotes, each containing an eligible shipping method, the shipping method's cost, and one or more ship-from addresses.

For , refer to the page.

You should present these quotes to customers and, once they make a selection, send an a that contains and . We can then use this information to generate a more precise .

A checkout's shipFrom can be set at the or the .

At this stage of the checkout process, you'll need to collect payment information from the customer and use it to or a .

However, before you can do that, the payment methods presented to the customer must apply to the transaction. With , you accomplish this by and passing it to the method. If you use , you'll need to configure and invoke .

In , you can use this same method to filter the customer's saved sources by transaction applicability before presenting them to the customer. If the customer selects a saved source from this filtered list, you'll need to use . This method first determines whether strong customer authentication () is required and then, if it is, opens a modal window that takes customers through the authentication process.

In both and checkouts, if customer's decide to provide new payment information, both of our require a identifier. You can .

If customers request that a newly created source be saved to their account, wait until the source is . Then verify that it supports storage (supportsStorage) and is ready for storage (). After that, you can before .

If the source is not scheduled for storage, once it's chargeable or , you can .

The guide

The guide

The page

The page

After you , activate a place order button on your order review page. to handle this button’s click event.

For more information, refer to the page.

The following lists some of the key parameters to use when defining checkouts. The table also indicates whether these parameters are available in and , and provides links to additional information on how to use these features. For comprehensive specifications, refer to the reference docs.

and

☨ In a request, you're .

To create a checkout, submit a request. Once you've created the object, and you want to update it, retrieve its , and then pass it as a path parameter in a .

The following request creates a that contains and meets all of our .

The response contains , tax, , and information at both the checkout and line item levels. During the checkout process, display this information to customers in your UI.

Make sure you save the checkout's and because they're required when submitting downstream requests. Additionally, the checkout contains that you use to create payment sources and determine when to submit an order request.

Every checkout contains a unique identifier. You can use this identifier to , , , and the checkout. You can also use the identifier to and then if the customer wants to apply a different payment method.

When you're ready to , pass this identifier in the body of a .

Once you create a , Digital River assigns each of its items[] an id. During the checkout process, if you want to you must send these identifiers in requests.

Depending on how you , each items[] also contains either the or the object you sent in the request.

The id of an items[] in a is not the same as the id of the corresponding in the associated .

contain a unique and other .

You can use the checkout's identifier to , , , and .

The payment.session contains an amountContributed, amountRemainingToBeContributed, and a state. You can use these values to .

compliance element
selling entity
Drop-in payments integration
DigitalRiver.js quick start
Building your payment workflows
Managing sources
Processing orders
price
landed cost
fee
unique identifier
unique line item identifiers
payment session details
Processing guest and registered checkouts
Managing sources
Selecting a currency
Applying a store credit
Designating a locale
Providing the IP address
Specifying a shipping choice
Describing items
Configuring taxes
Initiating a charge
Tax identifiers
Setting the customer type
Setting the purchase location
Providing the upstream identifier
tax estimate
physical products
items[]
Sequence the checkout process
Define checkouts
Submit create and update checkout requests
Use checkouts
create checkout request
physical products
Providing address information
Providing address information
Using shipping quotes
shippingChoice
tax calculation
Drop-in payments
DigitalRiver.js with elements
SCA
payment session
Customers API
payment session
retrieve this session identifier from the checkout
verify that the checkout’s payment session state is valid
unique identifier
payment session identifier
payment session information
physical products
the element's configuration object
create
update
attach the source to the checkout
pending_funds
create
authenticate
primary source creation methods
save the source to the customer
attaching the source to the checkout
chargeable
attach a source to the checkout
detach the payment source
create payment sources
determine when to create an order
Digital River coordinated fulfillments
guest
registered
registered checkouts
guest checkouts
registered checkouts
registered checkout
Checkout level discount
Shipping discount
readyForStorage
building a configuration object
createDropIn()
restricted to modifying certain line item attributes
modify items
send product data in checkouts
checkout
create a record for them
get a customer
source
POST /checkouts
POST /checkouts/{id}
Checkouts API
POST/checkouts/{id}
update
retrieve
search for
delete
checkout
POST /checkouts/{id}
Checkouts
checkout's
checkout
source
update a checkout
POST /checkouts
POST /checkouts
POST /orders
POST /checkouts/{id}
checkout
order
POST /checkouts/{id}
retrieveAvailablePaymentMethods()
authenticateSource()
request to update checkout
authenticate saved payment sources
retrieve available payment methods
skuId
productDetails
shipTo
billTo
sequencing address information in checkouts
address requirements
shipFrom
checkout-level
line item-level
address requirements
Required email address information
Specifying ship from at the checkout-level
Specifying ship from at the item-level
Ship to address
Bill to address
Convert the checkout to an order
convert the checkout to an order
items[]
validate tax identifiers