Process flow

Understand the high-level sequences and interactions in the Digital River API.

The following sequence diagrams depict the interaction between the customer, your commerce platform, the Digital River integration layer, and Digital River.

These diagrams are meant to outline Digital River's core capabilities, focusing specifically on:

  • Important states of the order life cycle

  • The sequence of major events in the Digital River API

  • The data you must provide Digital River to utilize our authorized reseller of record business model

  • How checkouts, orders, events, fulfillments, and post-order processing works

The full sequence diagram, contained within a single file, can be found here.

SKU creation

Prior to building a checkout and processing an order, you'll need to create your SKUs by providing, at a minimum, the product or service name, tax code, country of origin, and Export Control Classification Number. As the reseller of record, Digital River requests this data in order to adhere to local regulations and tax laws.

Pre-checkout

Digital River is typically not involved in the initial pre-checkout interactions between the customer and your commerce platform. During this stage, customers land on your storefront, build a cart, initiate a checkout, and confirm the cart's details. Your commerce platform can present them with the option of checking out as either a guest or registered customer.

Building a checkout

During the checkout process, Digital River creates a Customer and a Checkout and then returns the transaction's tax details and assigned selling entity to your commerce platform. The commerce platform should update the user interface with this tax information and use the selling entity to display compliance disclosures.

Creating a source and order

When the storefront customer proceeds to payment entry, the commerce platform renders the Drop-in component with the save payment agreement option. Storefront customers submit their payment details and Drop-in uses that information to create a payment source and return its identifier to the commerce platform.

If the storefront customer elected to save the payment source for future purchases, and the source is ready for storage, you should attach the source to the customer and then apply the source to the checkout. Otherwise, simply apply the source to the checkout to create a one-time charge.

Once payment is applied, use the response from the Checkouts API to update the commerce platform with the final tax information and assigned selling entity. The commerce platform can then provide the storefront customer an order summary and the necessary compliance information.

At this point, the storefront customer typically confirms the details and places the order. The commerce platform then submits an event which triggers a create order request through the Orders API. This POST/orders acts primarily as a fraud review and payment authorization call.

The immediate response returns either a 409 Conflict or 201 Created status code. In the event of an error, update the commerce platform's status and render the appropriate message to the storefront customer. If created, retrieve identifier and state data from the response and use those values to update the status of the commerce platform's order.

For immediately accepted orders, move the commerce platform's order into a ready to fulfill state and direct the storefront customer to the "Thank You" page.

For orders that are immediately returned as pending payment authorization or in fraud review, listen for asynchronous, order-related webhook events sent by Digital River.

Once an order is successfully screened for fraud or the customer completes the delayed payment steps, Digital River sends the order accepted and ready to fulfill event. When an order asynchronously fails due to fraud anomalies or because the payment window closes without funds, we send an order blocked or charged failed event, respectively.

When you receive one of these events, retrieve the order's state from its payload, and, depending on the value, move the commerce platform's order into an accepted, blocked, or payment failed state.

Fulfilling an order

Once an order moves into an accepted, ready to fulfill state, the client can initiate fulfillment. As products are fulfilled or cancelled, the commerce platform updates the status of those line items and emits an order status change event. This triggers a POST/fulfillments that must include a fulfilled quantity, a cancelled quantity, or both. Depending on the data in the request, Digital River initiates a funds capture and/or authorization reversal.