Checkouts, payment sources, and orders

Learn more about the standards related to processing checkouts, payment sources, and orders.

This section's checklist items and standards cover how to process MOR/SOR-compliant checkouts, subscriptions, payment sources, and orders.

Integration checklist

Click any checklist item for information on meeting the checkouts, payment sources, and orders-related integration standards.

Checkouts

• In POST/checkouts requests, does your integration provide us with the required product data?

• In POST/checkouts requests, does your integration provide us the required compliance product data?

• If you're sending productDetails in creating checkout requests, does your integration pass your system's unique product identifier as the object's id?

• If you're sending productDetails in creating checkout requests, does your integration reference the associated SKU group by specifying a skuGroupId?

• Do you use the taxInclusive flag to indicate whether the total cost of an order's items should be treated as tax-inclusive or exclusive?

• Does your integration provide the customer's public IP address?

• Do you use your commerce platform's unique order identifier (UUID) as the upstream identifier?

• For orders that contain physical products, do you specify shipTo and shipFrom values?

• After Digital River responds to a create or update checkout request, does your integration use the data provided by Digital River to update the commerce system's product and shipping tax data and then ensure that the values in both systems match?

Checkouts with subscriptions

• During subscription acquisitions, do you set the charge type to customer-initiated?

• When auto-renewing a subscription, do you set the charge type to merchant-initiated?

• Do you send subscription information for every subscription product or service included in a transaction?

• After the customer accepts the terms of an auto-renewing subscription, do you pass them to Digital River?

• Does your subscription management system generate a subscription identifier during the acquisition process?

• Do you specify a subscription's renewal method?

• During the renewal process, do you send the same billing agreement identifier generated during the subscription's acquisition?

• If a customer pays for a subscription with Klarna, do you provide the start and end time?

Payment sources

• Do you use Drop-in payments to display available payment methods and create a payment source?
• Do you provide customers the option to save payment information for future use?
• During transaction flows, if customers elect to save payment information for future purchases, do you save the source to their account?
• Does the onSuccess event fired by Drop-in payments trigger a final step in your checkout process that allows the customer to review all order and tax totals before making the purchase?

Payment sources with subscriptions

• When customers acquire an auto-renewing subscription, do Drop-in payments only display payment methods supporting reusability?
• Do you configure Drop-in payments to display and acquire the customer's acceptance of the combined subscription and payment storage terms?
• Do you save ready-for-storage payment sources to a customer's account?

Orders

• After a customer places an order on the storefront, do you pass the checkout identifier to a POST/orders request?
• Do you use the POST/orders response to update the storefront's UI with an order success or order failed message?
• Do you use the POST/orders response to set the order status in your upstream commerce platform?
• Do you capture the order's identifier?
• Do you capture the order's payment status?
• Do you capture the order's fraud status?
• Do you listen for and handle the order accepted event?
• Do you listen for and handle order failed events?

Orders with subscriptions

• Do you persist in the billing agreement identifier generated during the acquisition process for auto-renewing subscriptions?

Integration standards

The checkout, payment source, and order standards that apply to your integration depend on which of the above checklists you're using.

Provide required product data

When sending product data in create checkout requests each items[] must include a SKU identifier or a productDetails object. Each line item in the request must also have a defined price or aggregate price and a quantity.

Provide required compliance product data

When associating SKU groups with upstream product data in create checkout requests each items[] must include productDetails and within that object, you must specify a skuGroupId.

Reference product identifier in product details

If you're sending productDetails in create checkout requests, your integration should pass your system's unique product identifier as the object's id.

For more information, refer to the sending product data in checkouts section on the Describing line items page.

Reference required SKU group in product details

If you're sending productDetails in create checkout requests, your integration must reference the product's associated SKU group. You do this by specifying a skuGroupId in the productDetails object.

For more information, refer to the sending product data in checkouts section on the Describing line items page.

Indicate whether taxes are included in the retail price

When building a checkout, use the taxInclusive flag to indicate whether the price of items in an order should be treated as tax-inclusive or exclusive.

Provide the customer's public IP address

When building a checkout, provide the IP address of the customer's browser used to place the order.

Ensure the specified upstream identifier matches your order identifier

For tracking purposes, specify an upstream identifier during the checkout process that matches the identifier of the corresponding order in your commerce platform.

Supply required shipping address information

Orders that contain physical products must provide ship from and ship to address information.

Synchronize checkout data

Each time you create or update a checkout, use the response from the Checkouts API to update price, fee, and tax information in the upstream commerce platform. These updates should be performed for the entire transaction and each line item. This ensures that the values in your system stay in sync with those in our system.

Additionally, you should display these response values in your interface so customers can review tax and product totals during the checkout process.

Set charge type to customer-initiated in subscription acquisitions

Since the customer actively participates in a subscription acquisition, you should set chargeType to customer_initiated.

Set charge type to merchant initiated in subscription auto-renewals

During a subscription's autorenewal, the customer is not an active participant. As a result, when building a checkout to process an autorenewal, you should set chargeType to merchant_initiated.

Send subscription information

Any transaction that includes a recurring product or service must provide information that describes that subscription. So, when building a checkout, provide these details in the subscriptionInfo hash table.

Send the subscription's terms

For auto-renewing subscriptions, you must display the subscription's terms and acquire the customer's active acceptance of them. So, before converting a checkout to an order, pass these agreed-upon terms in the checkout's terms parameter. This ensures that they are recorded in the billing agreement.

Generate a subscription identifier

During the acquisition process, you can optionally generate a unique subscription identifier and assign it to subscriptionId.

Specify a subscription's renewal method

For every recurring product or service, you must use the autoRenewal parameter to tell us whether the subscription is automatically or manually renewed.

Send the billing agreement identifier in renewals

During the renewal process, send the billingAgreementId generated during the subscription's acquisition.

Provide a start and end time for Klarna-funded subscriptions

When acquiring or renewing a subscription with the Klarna payment method, you must provide a start and end time.

Use Drop-in to display available payment methods and create a source

Drop-in payments are our all-in-one solution for handling payments and ensuring compliance. We recommend you use this solution as a quick and easy way to start accepting payments.

During the checkout experience, you can use the configurable Drop-in object to present available payment methods and safely and securely capture a customer's payment details. The payment source returned in the onSuccess event can then be attached to the checkout before the customer arrives on your order review page.

Provide option to save payment information for future use

During checkout flows, we recommend you allow customers to save their payment information for future transactions. When building your payment workflows for one-off and subscription purchases, you can configure Drop-in payments to present the save payment option to customers.

Save ready-for-storage payment sources to the customer's account

In the onSuccess event, if readyForStorage returns true or mandate is populated, then the customer agrees to save that transaction's payment information for future use. Your integration should attach the payment source to the customer's record.

Respond to on success event and display the order review page

Whenever Drop-in payments successfully create a payment source, we send you the onSuccess event. Once you receive this event, redirect the customer to the order review page. The customer can review the order's details before deciding whether to purchase.

Display reusable payment sources

When a customer purchases an auto-renewing subscription, the payment methods that Drop-in payments display must support recurring transactions. To ensure that Drop-in only displays reusable payment methods, set autoRenewal to true in a POST/checkouts or POST/checkouts/{id} request. You then use Drop-in's configurable options to set showTermsOfSaleDisclosure to true.

Acquire customer's acceptance of subscription and payment storage terms

When acquiring an auto-renewing subscription, customers must agree to save the transaction's payment source to their account so that it can be applied to renewals. So, you must configure Drop-in payments to display the combined subscription save payment agreement terms and then acquire the customer's active acceptance.

You do this by first setting autoRenewal to true in a POST/checkouts or POST/checkouts/{id} request. You then use Drop-in's configurable options to set showTermsOfSaleDisclosure to true.

Save ready for storage source to customer's account

When the onSuccess event returns a source that is readyForStorage, you should save the source to the customer's account. This operation flips its reusable value to true. As a result, the source can be used in merchant-initiated subscription auto-renewals.

Create an order with the checkout identifier

After you display the review order page to the customer and the customer actively accepts Digital River's disclosure terms and then submits the order on the storefront, you should convert the checkout to an order. Digital River creates an order based on the data in a Checkout. Providing checkoutId in the payload of POST/orders acts primarily as a call to authorize payment and trigger a fraud review.

Notify the customer of the order status

When a customer uses a synchronous payment method such as a credit card to pay for a transaction, the POST /orders request almost always immediately returns an accepted or failed order. When the order succeeds, direct the customer to the "Thank you" page. If the order fails, use the error's message to inform the customer of the issue through the user interface.

Capture the order's identifier

When the POST /orders response returns a 201 Created status code, retrieve the order's id from the payload and use that value to set the corresponding attribute in the upstream commerce platform's order.

Align order states

Use the POST /orders response to set the status of the upstream commerce platform's order.

POST/orders response	Due to...	Ready to fulfill?
409 Conflict	a payment authorization failure	No
409 Conflict	a fraud review failure	No
201 Created	a pending payment	No
201 Created	an in-process secondary fraud review	No
201 Created	an accepted order	Yes

Capture the order's payment state

When the POST /orders response returns a 201 Created status code, retrieve charges[].state from the payload and use that value to set the corresponding attribute in the upstream commerce platform's order.

For 409 Conflict errors generated by a payment authorization failure set the commerce platform's order payment status to failed.

Capture the order's fraud state

When the POST /orders response returns a 201 Created status code, retrieve fraudState from the payload and use that value to set the corresponding attribute in the upstream commerce platform's order.

For 409 Conflict errors generated by a fraud review failure set the commerce platform's order fraud status to blocked.

Listen for and handle the order accepted event

We send the order.accepted event when Digital River successfully authorizes payment and completes its fraud review. This event indicates that the order is ready to be fulfilled. Upon receipt, retrieve state, fraudState, and charges[].state from the payload and use these values to update the corresponding attributes in the upstream commerce platform's order.

Listen for and handle order failed events

An asynchronous payment authorization failure triggers an order.charge.failed event. When Digital River asynchronously detects an anomaly during its fraud review or the customer is determined to be on the Denied Persons List, we send an order.blocked event.

Upon receipt of either event, retrieve state, fraudState, and charges[].state from the payload and use these values to update the corresponding attributes in the upstream commerce platform's order.

Persist the billing agreement identifier

For each subscription product or service you create, store the billingAgreementId that Digital River generates so that it can be sent in the renewal request.

API interfaces

Documentation	Direct API	PHP SDK
Checkouts	Checkouts	Checkouts
Sources	Sources	Sources
Orders	Orders	Orders
DigitalRiver.js
DigitalRiver.js Drop-in
Events: order.accepted, order.review_opened, order.pending_review, order.pending_payment, order.blocked, order.charge.failed, order.complete