Building checkouts
Learn the basics of how to sequence the checkout process as well as define, create, update, and use checkouts
Last updated
Learn the basics of how to sequence the checkout process as well as define, create, update, and use checkouts
Last updated
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:
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.
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.
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.
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.
Once the payment source is successfully created or authenticated, you must apply it to the checkout.
For more information on payments, refer to:
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 creditAmount
parameter is only available in versions 2020-09-30
, 2020-12-17
, and 2021-02-23
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.
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
.
This data is only returned in versions 2021-03-23
and higher.
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 .