Processing orders
Learn the basics of processing an order
Last updated
Learn the basics of processing an order
Last updated
Once customers are done checking out, how an is created depends on whether you implement a Low-code checkout or take the Direct integrations approach.
If you're using Direct Integrations, first convert the checkout to an order and then handle the immediate response and/or key events early in an order's lifecycle.
If you're using Prebuilt Checkout, then Digital River handles creation. You should, however, configure a webhook(s) to listen for with a type
of checkout_session.order.created
, order.accepted
and order.cancelled
.
However, no matter which integration option you select, make sure you're set up to process:
For a list of important webhook events that most integrations should subscribe to, refer to Key event types.
With Direct Integrations, once the address and payment requirements are met and customers have reviewed and submitted their orders, you should pass checkoutId
in the body of a .
This request primarily authorizes payment. Once submitted, your integration should be set up to process the immediate response and respond to key events.
You can submit a POST /orders
that payload contains checkoutId
plus additional parameters (provided they adhere to the request's data contract). But, when processing the request, Digital River ignores this additional data. So, if you'd like to , you must do so before submitting a POST /orders
.
If you submit a POST /orders
that contains the checkout's identifier, an updated email
, and also adds an upstreamId
that identifies the order in your system; then the response contains a 201 Created
status code. However, email
is not updated and upstreamId
is not populated.
POST /orders
responseWhen handling this immediate response, you need to capture specific data from its payload and use it to update the status of your commerce system. This ensures that downstream fulfillment operations are correctly handled.
Use this error information to update the upstream order's overall status, payment status, and fraud status.
You can also use the error's message
to inform end customers of the problem. Do not, however, share code
. Doing so may aid parties attempting to carry out fraudulent or malicious activities.
For more details on processing responses with a 409 Conflict
status code, refer to the Handling rejected orders page.
These events notify you of:
accepted orders and
Do not display the failureCode
to end customers. Doing so potentially aids malicious and fraudulent actors.
For more information, refer to handling pending payment orders.
For more information, refer to handling in review orders.
Unless you synchronously receive an order in an accepted
state, your integration should wait until it receives order.accepted
before initiating fulfillment operations. Doing so reduces the risk of fraud and the frequency of disputes and chargebacks.
In the data.object
of the expanded version of order.accepted
, you can use physical
in each items[].productDetails
to determine whether that product is classified as physical or digital. If physical
is true
, then the product needs to be shipped to the customer. As a result, you should pass its details in a ship request to your fulfillment service. Otherwise, if false
, then the product is a digital item and should be delivered to the customer via email or some other digital channel.
For more information, refer to handling accepted orders.
For more details, refer to Handling cancelled orders.
The following provides information on handling pending payment, in review, accepted, cancelled orders.
To handle this state
change event, determine the value of the order's payment.session.nextAction.action
.
If it's redirect
, refer to Handling redirect payment methods.
If it's show_payment_instructions
, refer to Handling delayed payment methods.
Depending on whether the order is synchronously or asynchronously accepted, you should redirect customers to an order confirmation page and/or send them an order confirmation notification.
At this point, fulfillment operations can be initiated.
order.cancelled
eventUpdate the master order record in your system
Notify customers (typically by email) that their order has been successfully cancelled and no payment was collected. In the email, we suggest you provide:
The order number
The order cancellation date (you can retrieve this information from the order's stateTransitions.cancelled
attribute)
An itemization of the cancelled goods
The payment method used by the customer
The total amount cancelled
The customer’s billing address
Your contact information
If you attempt to pass a checkoutId
in a POST /orders
request, and that Checkout has already been consumed by a different POST /orders
request, you'll get back a response with a 404 Not Found
status:
For example, the following email
address is johndoe@digitalriver.com
.
If you're using Direct Integrations, after you submit a POST /orders
(assuming all upstream requirements have been met), the response will contain a 409 Conflict
or 201 Created
status code.
A 409 Conflict
status code indicates that Digital River did not create an , either due to a payment authorization failure or suspected fraud. The error's code
and message
contain more specific information about what triggered the failure.
A 201 Created
status code indicates an state
is pending_payment
, in_review
, or accepted
.
From the response's payload, retrieve the id
, state
, fraudState
, and charges[].state
. Use these values to update the corresponding attributes in the upstream commerce platform's order.
If an state
is pending_payment
, the fraud review process has been successfully completed but the is not yet authorized. For more details, refer to handling pending payment orders.
If an state
is in_review
, this indicates that Digital River is conducting a secondary fraud review. For more information, refer to handling in review orders.
If an state
is accepted
, then the transaction has successfully passed fraud review and the is authorized. For more information, refer to handling accepted orders.
Whether you're using Drop-in Checkout, Low-code components, or Direct integrations, you'll need to configure webhooks to listen for some key events that occur early in an .
Each time you're notified of one of these events, retrieve the state
, fraudState
, and charges[].state
(if available) from its payload and use this data to update the corresponding attributes in the upstream commerce system's order.
An asynchronous failure triggers an order.charge.failed
event.
If you receive this event, you can iterate over the payment.charges[]
and inspect them for a . The failureMessage
, however, is not always available. But when it is, you can use it to provide customers with more specific payment failure information.
When Digital River detects an anomaly during its or we determine that the customer is on the Denied Persons List, we create an order.blocked
event. The payload of this event consists of an whose is blocked
. The order's is also blocked
. Since these are both terminal states, you should inform end customers that the transaction has failed.
An order.pending_payment
event indicates that Digital River detected no fraudulent activity during its . However, don't use this event as a trigger to initiate fulfillment operations. This is because the payment.charges[]
are not yet fully authorized.
An order.review_opened
event indicates that Digital River is conducting a secondary fraud review and has moved the state
to . Since the fraud review process is not yet complete, don't use this event as a trigger to initiate fulfillment operations.
When all of an order's are authorized, and no irregularities are detected during the , Digital River creates an order.accepted
event. Respond to this event by moving the commerce platform's order into a ready to fulfill state.
When an moves to cancelled
, Digital River creates an whose type
is order.cancelled
and whose data.object
contains that order.
If you decide to build your integration so that customers can submit line-item level cancellation requests (as opposed to the more standard full-order cancellations), then you can’t always use order.cancelled
to trigger notifications that inform customers their request was successfully processed. This is because an order's state
doesn't move to cancelled
until the of all of its is also cancelled
.
You should also be aware that order.cancelled
is often created when customers fail to transfer payment by a designated date and time. This applies to wire transfers, Konibini, and other type
(s) of that have a flow
of receiver
.
For example, after an with a primary source type
of wireTransfer
is created, that order's typically becomes pending_payment
. As a result, customers are provided instructions on how to authorize payment. For details, refer to Handling pending payments.
If these instructions aren't followed (i.e., the funds aren't pushed within the allotted time), then the expires, no is created, and Digital River creates order.cancelled
.
If an state
is pending_payment
, then the on the primary payment sources[]
is not yet authorized, and the goods should not be fulfilled.
that are in_review
should not be fulfilled. After an order transitions out of this , Digital River creates either order.accepted
or order.blocked
. So, ensure your integration is set up to handle both events.
When an becomes accepted
, move the order in your system into a ready to fulfill state.
Upon receiving the with a type
of order.cancelled
, we recommend that you: