# Building checkouts 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: * [Sequence the checkout process](#sequencing-the-checkout-process) * [Define checkouts](#defining-a-checkout) * [Submit create and update checkout requests](#creating-and-updating-the-checkout) * [Use checkouts](#using-the-checkout-response) ## 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 [physical products](https://docs.digitalriver.com/digital-river-api/product-management/creating-and-updating-skus#how-products-are-specified-as-physical-or-digital), it explains how to sequence the create and update [checkout ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts)requests and the create and authenticate [source ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/sources)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 [`items[]`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/describing-the-items), [`shipTo`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/providing-address-information#ship-to-address) and [`billTo`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/providing-address-information#bill-to-address) and then submit the [create checkout request](#sequencing-the-checkout-process). Since you can’t [update a checkout](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts#checkouts-id-1) 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. It also provides Digital River with the data we need to generate a [tax estimate](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/tax-calculations#tax-estimation-and-computation-workflow) that you can display to the customer. {% hint style="info" %} For more information, refer to [sequencing address information in checkouts](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/providing-address-information#sequencing-address-information-in-checkout-workflows) on the [Providing address information](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/providing-address-information) page. {% endhint %} ### Displaying compliance disclosures You must display disclosures on all of your checkout pages, typically in the footer. You can use the [compliance element](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/elements/compliance-elements) to do this. ![](https://334437993-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LqH4RJfLVLuHPXuJyTZ%2Fuploads%2FWKqXSqB2jnuvEyDT2TeM%2Fdisclosures.png?alt=media\&token=45e4e30d-35c4-4ac3-ad46-b4962e806b0a) Each time you access the [checkout](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts), 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 [the element's configuration object](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/elements/compliance-elements#compliance-element-configuration-object) and then pass that data to the [create](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/elements/compliance-elements#creating-a-compliance-element) or [update](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/elements/compliance-elements#compliance.update) method. This ensures customers are shown localized disclosures relevant to their shopping country and the transaction's designated [selling entity](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/selling-entities). ### Handling guest and registered customers If your integration only allows [registered checkouts](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/using-the-checkout-identifier#registered-checkouts-or-invoices), 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 [Customers API](#sequencing-checkout-requests) to [create a record for them](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/customers#customers) in Digital River’s system. In registered checkouts, you can use the same API to [get a customer](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/customers#customers-id) 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 [guest checkouts](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/using-the-checkout-identifier#guest-checkouts-or-invoices), collect and send us the customer's email address. For more information, refer to [address requirements](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/providing-address-information#address-requirements-and-validations) on the [Providing address information](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/providing-address-information) page. ### Handling shipping quotes If the shopping cart contains [physical products](https://docs.digitalriver.com/digital-river-api/product-management/creating-and-updating-skus#how-products-are-specified-as-physical-or-digital), 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 [Digital River coordinated fulfillments](https://docs.digitalriver.com/digital-river-api/order-management/fulfillments#digital-river-coordinated-fulfillments), refer to the [Using shipping quotes](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/handling-digital-river-coordinated-fulfillments/using-shipping-quotes) page. You should present these quotes to customers and, once they make a selection, send an a [request to update checkout](https://app.gitbook.com/s/ScJM6Hp95yBCPfU1nBSB/checkouts#checkouts-id-1) that contains [`shippingChoice`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/shipping-choice) and [`shipFrom`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/providing-address-information#ship-from-address). We can then use this information to generate a more precise [tax calculation](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/tax-calculations#tax-estimation-and-computation-workflow). {% hint style="info" %} A checkout's `shipFrom` can be set at the [checkout-level](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/providing-address-information#specifying-ship-from-at-the-checkout-level) or the [line item-level](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/providing-address-information#specifying-ship-from-at-the-item-level). {% endhint %} ### Collecting payment At this stage of the checkout process, you'll need to collect payment information from the customer and use it to [create](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/using-the-source-identifier#creating-payment-sources) or [authenticate](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/using-the-source-identifier#authenticating-sources) a [source](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/sources). However, before you can do that, the payment methods presented to the customer must apply to the transaction. With [Drop-in payments](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in), you accomplish this by [building a configuration object](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide#step-5-configure-hydrate) and passing it to the [`createDropIn()`](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide#step-6-allow-the-shopper-to-interact-with-hydrate) method. If you use [DigitalRiver.js with elements](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/digitalriver.js/quick-start), you'll need to configure and invoke [`retrieveAvailablePaymentMethods()`](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/digitalriver-object#retrieving-available-payment-methods). In [registered checkouts](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/using-the-checkout-identifier#registered-checkouts-or-invoices), 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 [`authenticateSource()`](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/digitalriver-object#authenticating-sources). This method first determines whether strong customer authentication ([SCA](https://docs.digitalriver.com/digital-river-api/payments/psd2-and-sca)) is required and then, if it is, opens a modal window that takes customers through the authentication process. In both [guest](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/using-the-checkout-identifier#guest-checkouts-or-invoices) and [registered](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/using-the-checkout-identifier#registered-checkouts-or-invoices) checkouts, if customer's decide to provide new payment information, both of our [primary source creation methods](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/using-the-source-identifier#creating-payment-sources) require a [payment session](#payment-session) identifier. You can [retrieve this session identifier from the checkout](#payment-session). 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. If customers request that a newly created source be saved to their account, wait until the source is [`chargeable`](https://docs.digitalriver.com/digital-river-api/payments/payment-sources#source-state). Then verify that it supports storage (`supportsStorage`) and is ready for storage ([`readyForStorage`](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide#onsuccess)). After that, you can [save the source to the customer](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/using-the-source-identifier#attaching-sources-to-customers) before [attaching the source to the checkout](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/using-the-source-identifier#attaching-sources-to-checkouts). If the source is not scheduled for storage, once it's `chargeable` or [`pending_funds`](https://docs.digitalriver.com/digital-river-api/payments/payment-sources#source-state), you can [attach the source to the checkout](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/using-the-source-identifier#attaching-sources-to-checkouts). For more information on payments, refer to: * The [Drop-in payments integration ](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide)guide * The [DigitalRiver.js quick start ](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/digitalriver.js/quick-start)guide * The [Building your payment workflows](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/building-you-workflows) page * The [Managing sources](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/using-the-source-identifier) page ### Submitting the order After you [verify that the checkout’s payment session state is valid](#payment-session), activate a place order button on your order review page. [Convert the checkout to an order](https://docs.digitalriver.com/digital-river-api/order-management/creating-and-updating-an-order#creating-an-order-with-the-checkout-identifier) to handle this button’s click event. For more information, refer to the [Processing orders](https://docs.digitalriver.com/digital-river-api/order-management/creating-and-updating-an-order) page. ## Defining a checkout The following lists some of the key parameters to use when defining checkouts. The table also indicates whether these parameters are available in [`POST /checkouts`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts#checkouts-1) and [`POST /checkouts/{id}`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts#checkouts-id-1), and provides links to additional information on how to use these features. For comprehensive specifications, refer to the [Checkouts API](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts) reference docs. | Parameter | Request type availability | Documentation | | ------------------ | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `customerId` | Both | [Processing guest and registered checkouts](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/using-the-checkout-identifier) | | `sourceId` | Both | [Managing sources](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/using-the-source-identifier) | | `currency` | Both | [Selecting a currency](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/selecting-a-currency) | | `creditAmount`\* | Both | [Applying a store credit](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/applying-a-store-credit) | | `email` | Both | [Required email address information](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/providing-address-information#email-address-requirements) | | `locale` | Both | [Designating a locale](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/designating-a-locale) | | `browserIp` | Both | [Providing the IP address](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/providing-the-ip-address) | | `shipFrom` | Both | [Specifying ship from at the checkout-level](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/providing-address-information#specifying-ship-from-at-the-checkout-level) and [Specifying ship from at the item-level](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/providing-address-information#specifying-ship-from-at-the-item-level) | | `shipTo` | Both | [Ship to address](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/providing-address-information#ship-to-address) | | `billTo` | Both | [Bill to address](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/providing-address-information#bill-to-address) | | `shippingChoice` | Both | [Specifying a shipping choice](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/shipping-choice) | | `discount` | Create | [Checkout level discount](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/applying-a-discount#checkout-level-or-invoice-level-discount) | | `items`☨ | Both | [Describing items](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/describing-the-items) | | `shippingDiscount` | Create | [Shipping discount](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/applying-a-discount#shipping-discount) | | `taxInclusive` | Create | [Configuring taxes](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/configuring-taxes) | | `chargeType` | Both | [Initiating a charge](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/initiating-a-charge) | | `taxIdentifiers` | Both | [Tax identifiers](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/tax-identifiers) | | `customerType` | Create | [Setting the customer type](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/setting-the-customer-type) | | `purchaseLocation` | Both | [Setting the purchase location](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/setting-the-purchase-location) | | `upstreamId` | Both | [Providing the upstream identifier](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/providing-an-upstream-identifier) | \*The `creditAmount`parameter is only available in versions `2020-09-30`, `2020-12-17`, and `2021-02-23` ☨ In a [`POST/checkouts/{id}`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts#checkouts-id-1) request, you're [restricted to modifying certain line item attributes](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/describing-the-items#updating-items). ## Creating and updating the checkout To create a checkout, submit a [`POST /checkouts`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts#checkouts-1) request. Once you've created the object, and you want to update it, retrieve its [unique identifier](#checkout-identifier), and then pass it as a path parameter in a [`POST /checkouts/{id}`](https://app.gitbook.com/s/ScJM6Hp95yBCPfU1nBSB/checkouts#checkouts-id-1). The following [`POST /checkouts`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts#checkouts-1) request creates a [registered checkout](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/using-the-checkout-identifier#registered-checkouts-or-invoices) that contains [physical products](https://docs.digitalriver.com/digital-river-api/product-management/creating-and-updating-skus#how-products-are-specified-as-physical-or-digital) and meets all of our [address requirements](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/providing-address-information#address-requirements-and-validations). {% tabs %} {% tab title="POST/checkouts request" %} ``` curl --location --request POST 'https://api.digitalriver.com/checkouts' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ' \ ... --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 } ] }' ``` {% endtab %} {% endtabs %} ## 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. The response contains [price](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/describing-the-items/price-of-an-item), tax, [landed cost](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/landed-costs), and [fee](https://docs.digitalriver.com/digital-river-api/product-management/regulatory-fees) information at both the checkout and line item levels. During the checkout process, display this information to customers in your UI. {% tabs %} {% tab title="Checkout" %} ```javascript { ... "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 } }, ... } ``` {% endtab %} {% endtabs %} Make sure you save the checkout's [unique identifier](#checkout-identifier) and [unique line item identifiers](#item-information) because they're required when submitting downstream requests. Additionally, the checkout contains [payment session details](#payment-session) that you use to create payment sources and determine when to submit an order request. ### Checkout identifier Every checkout contains a unique identifier. You can use this identifier to [update](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts#checkouts-id-1), [retrieve](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts#checkouts-id), [search for](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts#checkouts), and [delete ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts#checkouts-id-2)the checkout. You can also use the identifier to [attach a source to the checkout](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/using-the-source-identifier#attaching-sources-to-checkouts) and then [detach the payment source](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/using-the-source-identifier#detaching-sources-from-checkouts) if the customer wants to apply a different payment method. When you're ready to [convert the checkout to an order](https://docs.digitalriver.com/digital-river-api/order-management/creating-and-updating-an-order#creating-an-order-with-the-checkout-identifier), pass this identifier in the body of a [`POST /orders`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders#orders-1). {% tabs %} {% tab title="Checkout" %} ```javascript { "id": "f2cd50e5-355d-42d3-8bb7-0c14d8b777e4", ... } ``` {% endtab %} {% endtabs %} ### Item information Once you create a [checkout](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts), Digital River assigns each of its `items[]` an `id`. During the checkout process, if you want to [modify items](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/describing-the-items#updating-items) you must send these identifiers in [`POST /checkouts/{id}`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts#checkouts-id-1) requests. Depending on how you [send product data in checkouts](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/describing-the-items#sending-product-data), each `items[]` also contains either the [`skuId`](https://docs.digitalriver.com/digital-river-api/product-management/skus#product-details) or the [`productDetails`](https://docs.digitalriver.com/digital-river-api/product-management/skus#product-details) object you sent in the [`POST /checkouts/{id}`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts#checkouts-id-1) request. {% hint style="info" %} The `id` of an `items[]` in a [checkout ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts)is not the same as the `id` of the corresponding [`items[]`](https://docs.digitalriver.com/digital-river-api/order-management/creating-and-updating-an-order#line-items) in the associated [order](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders). {% endhint %} {% tabs %} {% tab title="Checkout" %} ```javascript { "id": "ec03be84-d684-48a1-b4f4-4dbc05313c93", ... "items": [ { "id": "50e69e0a-8e36-4ef9-84a0-45eea7535247", "skuId": "3a4ad0c5-1640-471e-a6b7-232454474659", "amount": 20.0, "quantity": 2, ... } ], ... } ``` {% endtab %} {% tab title="Order" %} ```javascript { "id": "227256090336", ... "items": [ { "id": "153193900336", "skuId": "3a4ad0c5-1640-471e-a6b7-232454474659", "amount": 20.0, "quantity": 2, ... } ], ... "checkoutId": "ec03be84-d684-48a1-b4f4-4dbc05313c93" } ``` {% endtab %} {% endtabs %} ### Payment session [Checkouts ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts)contain a unique [payment session identifier](#payment-session-identifier) and other [payment session information](#payment-session-information). #### Payment session identifier You can use the checkout's [payment session](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/payment-sessions) identifier to [create payment sources](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/using-the-source-identifier#creating-payment-sources), [authenticate saved payment sources](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/digitalriver-object#authenticating-sources), [retrieve available payment methods](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/digitalriver-object#retrieving-available-payment-methods), and [validate tax identifiers](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/tax-identifiers#validating-tax-identifiers). {% hint style="warning" %} 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`. {% endhint %} #### Payment session information The [checkout's ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts)`payment.session` contains an `amountContributed`, `amountRemainingToBeContributed`, and a `state`. You can use these values to [determine when to create an order](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/payment-sessions#how-to-determine-when-to-create-an-order). {% hint style="warning" %} This data is only returned in versions `2021-03-23` and higher. {% endhint %} {% tabs %} {% tab title="Checkout" %} ```javascript { "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" } } } ``` {% endtab %} {% endtabs %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.