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 or take the approach.
If you're using , first and then handle the and/or .
If you're using , then Digital River handles creation. You should, however, to listen for with a of , and .
However, no matter which integration option you select, make sure you're set up to process:
.
For a list of important that most integrations should subscribe to, refer to .
With , once the and 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 .
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.
These events notify you of:
Do not display the failureCode
to end customers. Doing so potentially aids malicious and fraudulent actors.
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 , after you submit a (assuming all upstream requirements have been met), the response will contain a or 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.
For more details on processing responses with a 409 Conflict
status code, refer to the page.
A 201 Created
status code indicates an state
is , , or .
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 .
If an state
is in_review
, this indicates that Digital River is conducting a secondary fraud review. For more information, refer to .
If an state
is accepted
, then the transaction has successfully passed fraud review and the is authorized. For more information, refer to .
Whether you're using , , or , you'll need to to listen for some key that occur early in an .
and
.
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 , 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.
For more information, refer to .
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.
For more information, refer to .
When all of an order's are authorized, and no irregularities are detected during the , Digital River creates an event. Respond to this event by moving the commerce platform's order into a ready to fulfill state.
Unless you , your integration should wait until it receives order.accepted
before initiating . Doing so reduces the risk of fraud and the frequency of .
In the of the 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 .
When an moves to cancelled
, Digital River creates an whose is and whose contains that .
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 . This is because an 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 , , and other (s) of that have a of receiver
.
For example, after an with a 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 .
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
.
For more details, refer to .
The following provides information on handling , , , orders.
If an state
is pending_payment
, then the on the is not yet authorized, and the goods should not be fulfilled.
To handle this state
change event, determine the value of the order's .
If it's redirect
, refer to .
If it's show_payment_instructions
, refer to .
that are in_review
should not be fulfilled. After an order transitions out of this , Digital River creates either or . 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.
Depending on whether the order is or accepted, you should redirect customers to an order confirmation page and/or send them an .
At this point, can be initiated.
Upon receiving the with a of , we recommend that you: