# Processing orders
Once customers are done checking out, how an [order ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders)is created depends on whether you implement a [Low-code checkout](https://docs.digitalriver.com/digital-river-api/integration-options/low-code-checkouts) or take the [Direct integrations](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts) approach.
If you're using [Direct Integrations](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts), first [convert the checkout to an order](#creating-an-order-with-the-checkout-identifier) and then handle the[ immediate response](#processing-the-post-orders-response) and/or [key events early in an order's lifecycle](#listening-for-and-handling-order-related-webhook-events).
If you're using [Prebuilt Checkout](https://docs.digitalriver.com/digital-river-api/integration-options/low-code-checkouts/drop-in-checkout), then Digital River handles [order](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders) creation. You should, however, [configure a webhook(s)](https://docs.digitalriver.com/digital-river-api/administration/dashboard/developers/webhooks) to listen for [events ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/events)with a [`type`](https://docs.digitalriver.com/digital-river-api/events-and-webhooks-1/events-1#event-types) of [`checkout_session.order.created`](https://docs.digitalriver.com/digital-river-api/events-and-webhooks-1/events-1/event-types#checkout_session.order.created), [`order.accepted`](https://docs.digitalriver.com/digital-river-api/events-and-webhooks-1/events-1/event-types#order.accepted) and [`order.cancelled`](https://docs.digitalriver.com/digital-river-api/events-and-webhooks-1/events-1/event-types#order.cancelled).
However, no matter which integration option you select, make sure you're set up to process:
* [Events early in an order's lifecycle](#listening-for-and-handling-order-related-webhook-events).
* [Fulfillment-related events](https://docs.digitalriver.com/digital-river-api/informing-digital-river-of-a-fulfillment#using-fulfillment-related-events)
{% hint style="success" %}
For a list of important [webhook events](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/events-1) that most integrations should subscribe to, refer to [Key event types](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/events-1/event-types).
{% endhint %}
## Converting a checkout to an order
With [Direct Integrations](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts), once the [checkout's](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts) [address](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/providing-address-information#address-requirements-and-validations) and [payment](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/payment-sessions#how-to-determine-when-to-create-an-order) requirements are met and customers have reviewed and submitted their orders, you should pass `checkoutId` in the body of a [`POST /orders`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders#orders-1).
{% tabs %}
{% tab title="POST /orders" %}
```javascript
curl --location --request POST 'https://api.digitalriver.com/orders' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ' \
--data-raw '{
"checkoutId": "177452470336"
}'
```
{% endtab %}
{% endtabs %}
This request primarily authorizes payment. Once submitted, your integration should be set up to process the immediate response and [respond to key events](#listening-for-and-handling-order-related-webhook-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 [update the checkout](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts#checkouts-id-1), you must do so before submitting a `POST /orders`.
For example, the following [checkout's ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts)`email` address is `johndoe@digitalriver.com`.
{% tabs %}
{% tab title="Checkout" %}
```javascript
{
"id": "856adaff-0176-4bdb-91cb-7304dfd1e7a9",
...
"email": "johndoe@digitalriver.com",
...
}
```
{% endtab %}
{% endtabs %}
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.
{% tabs %}
{% tab title="POST/orders" %}
```
curl --location --request POST 'https://api.digitalriver.com/orders' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ' \
...
--data-raw '{
"checkoutId": "856adaff-0176-4bdb-91cb-7304dfd1e7a9",
"email": "janedoe@digitalriver.com",
"upstreamId": "1J9F17710A6"
}'
```
{% endtab %}
{% tab title="Order" %}
```javascript
{
"id": "189917880336",
...
"email": "johndoe@digitalriver.com",
...
"checkoutId": "856adaff-0176-4bdb-91cb-7304dfd1e7a9"
}
```
{% endtab %}
{% endtabs %}
## Handling the `POST /orders` response
If you're using [Direct Integrations](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts), after you submit a [`POST /orders`](#creating-an-order-with-the-checkout-identifier) (assuming all upstream [checkout ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts)requirements have been met), the response will contain a [`409 Conflict`](#409-conflict) or [`201 Created`](#201-created) status code.
When 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.
### 409 Conflict
A `409 Conflict` status code indicates that Digital River did not create an [order](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders), 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.
{% code title="Error" %}
```javascript
{
"type": "conflict",
"errors": [
{
"code": "failed-request",
"message": "Failed to charge source."
}
]
}
```
{% endcode %}
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](https://docs.digitalriver.com/digital-river-api/order-management/resubmitting-an-order) page.
### 201 Created
A `201 Created` status code indicates an [order's ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders)`state` is [`pending_payment`](#pending-payment), [`in_review`](#in-review), or [`accepted`](#accepted).
From the response's payload, retrieve the [order's ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders)`id`, `state`, `fraudState`, and `charges[].state`. Use these values to update the corresponding attributes in the upstream commerce platform's order.
#### Pending payment
If an [order's ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders)`state` is `pending_payment`, the fraud review process has been successfully completed but the [payment charge](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/charges/charge-basics) is not yet authorized. For more details, refer to [handling pending payment orders](#handling-pending-payment-orders).
#### In review
If an [order's ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders)`state` is `in_review`, this indicates that Digital River is conducting a secondary fraud review. For more information, refer to [handling in review orders](#handling-in-review-orders).
#### Accepted
If an [order's ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders)`state` is `accepted`, then the transaction has successfully passed fraud review and the [payment charge](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/charges/charge-basics) is authorized. For more information, refer to [handling accepted orders](#handling-accepted-orders).
## Events early in an order's lifecycle
Whether you're using [Drop-in Checkout](https://docs.digitalriver.com/digital-river-api/integration-options/low-code-checkouts/drop-in-checkout), [Low-code components](https://docs.digitalriver.com/digital-river-api/integration-options/low-code-checkouts/implementing-a-components-checkout), or [Direct integrations](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts), you'll need to [configure webhooks](https://docs.digitalriver.com/digital-river-api/administration/dashboard/developers/webhooks/creating-a-webhook) to listen for some key [events](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/events-1) that occur early in an [order's lifecycle](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders/order-basics#the-order-lifecycle).
These events notify you of:
* [charge authorization failures](#the-payment-failure-event)
* [fraud blocks](#the-fraud-review-failure-event)
* [pending charge authorizations](#the-pending-payment-event)
* [ongoing fraud reviews](#the-fraud-review-failure-event-1)
* [accepted orders](#listening-for-the-order-accepted-event) and
* [cancelled orders](#the-order-cancelled-event).
Each time you're notified of one of these events, retrieve the [order's ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders)`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.
### The charge authorization failure event
An asynchronous [charge authorization](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/charges/charge-basics#how-a-charge-is-created) failure triggers an `order.charge.failed` event.
If you receive this event, you can iterate over the [order's ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders)`payment.charges[]` and inspect them for a [failure code or message](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/charges/charge-basics#handling-failures). The `failureMessage`, however, is not always available. But when it is, you can use it to provide customers with more specific payment failure information.
{% hint style="danger" %}
Do not display the `failureCode` to end customers. Doing so potentially aids malicious and fraudulent actors.
{% endhint %}
### The fraud block event
When Digital River detects an anomaly during its [fraud review](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders/order-basics#fraud-review) or we determine that the customer is on the [Denied Persons List](https://www.bis.doc.gov/index.php/policy-guidance/lists-of-parties-of-concern/denied-persons-list), we create an `order.blocked` event. The payload of this event consists of an [order](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders) whose [`state`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders/order-basics#order-states-and-events) is `blocked`. The order's [`fraudState`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders/order-basics#fraud-review) is also `blocked`. Since these are both terminal states, you should inform end customers that the transaction has failed.
### The pending charge authorization event
An `order.pending_payment` event indicates that Digital River detected no fraudulent activity during its [fraud review](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders/order-basics#fraud-review). However, don't use this event as a trigger to initiate fulfillment operations. This is because the [order's](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders) `payment.charges[]` are not yet fully authorized.
For more information, refer to [handling pending payment orders](#handling-pending-payment-orders).
### The in-process fraud review event
An `order.review_opened` event indicates that Digital River is conducting a secondary fraud review and has moved the [order's ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders)`state` to [`in_review`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders/order-basics#order-states-and-events). 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 [handling in review orders](#handling-in-review-orders).
### The order accepted event
When all of an order's [`payment.charges[]`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/charges/charge-basics#how-a-charge-is-created) are authorized, and no irregularities are detected during the [fraud review](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders/order-basics#the-order-lifecycle), Digital River creates an [`order.accepted`](https://docs.digitalriver.com/digital-river-api/events-and-webhooks-1/events-1/event-types#order.accepted) event. Respond to this event by moving the commerce platform's order into a ready to fulfill state.
Unless you [synchronously receive an order in an `accepted` state](#accepted), your integration should wait until it receives `order.accepted` before initiating [fulfillment operations](https://docs.digitalriver.com/digital-river-api/order-management/fulfillments). Doing so reduces the risk of fraud and the frequency of [disputes and chargebacks](https://docs.digitalriver.com/digital-river-api/order-management/returns-and-refunds-1/disputes-and-chargebacks).
In the [`data.object`](https://docs.digitalriver.com/digital-river-api/events-and-webhooks-1/events-1#event-data) of the [expanded version](https://docs.digitalriver.com/digital-river-api/events-and-webhooks-1/events-1#expanded-events) 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](#handling-accepted-orders).
### The order cancelled event
When an [order's ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders)[`state`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders/order-basics#order-states-and-events) moves to `cancelled`, Digital River creates an [event ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/events)whose [`type`](https://docs.digitalriver.com/digital-river-api/events-and-webhooks-1/events-1#event-types) is [`order.cancelled`](https://docs.digitalriver.com/digital-river-api/events-and-webhooks-1/events-1/event-types#order.cancelled) and whose [`data.object`](https://docs.digitalriver.com/digital-river-api/events-and-webhooks-1/events-1#event-data) contains that [order](https://www.digitalriver.com/docs/digital-river-api-reference/#tag/Orders).
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](https://docs.digitalriver.com/digital-river-api/customer-notifications#successful-cancellation). This is because an [order's](https://www.digitalriver.com/docs/digital-river-api-reference/#tag/Orders) `state` doesn't move to `cancelled` until the [`state` ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/charges/charge-basics#the-charge-lifecycle)of all of its [`payment.charges[]`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/charges) 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](https://docs.digitalriver.com/digital-river-api/payments/supported-payment-methods/wire-transfer), [Konibini](https://docs.digitalriver.com/digital-river-api/payments/supported-payment-methods/konbini), and other [`type`](https://docs.digitalriver.com/digital-river-api/payments/payment-sources#supported-payment-methods)(s) of [sources ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/sources)that have a [`flow`](https://docs.digitalriver.com/digital-river-api/payments/payment-sources#authentication-flow) of `receiver`.
For example, after an [order ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders)with a [primary source](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/using-the-source-identifier#primary-payment-sources) [`type`](https://docs.digitalriver.com/digital-river-api/payments/payment-sources#supported-payment-methods) of `wireTransfer` is created, that order's [`state`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders/order-basics#order-states-and-events) typically becomes `pending_payment`. As a result, customers are provided instructions on how to authorize payment. For details, refer to [Handling pending payments](#handling-pending-payment-orders).
If these instructions aren't followed (i.e., the funds aren't pushed within the allotted time), then the [source ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/sources)expires, no [charge authorization](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/charges/charge-basics#how-a-charge-is-created) is created, and Digital River creates `order.cancelled`.
For more details, refer to [Handling cancelled orders](#handling-the-order.cancelled-event).
## Handling order state changes
The following provides information on handling [pending payment](#handling-pending-payment-orders), [in review](#handling-in-review-orders), [accepted](#handling-accepted-orders), [cancelled](#handling-the-order.cancelled-event) orders.
### Handling pending payment orders
If an [order's ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders)`state` is `pending_payment`, then the [charge ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/charges/charge-basics)on the [primary payment `sources[]`](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/using-the-source-identifier#primary-versus-secondary-sources) is not yet authorized, and the [order's ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders)goods should not be fulfilled.
To handle this `state` change event, determine the value of the order's [`payment.session.nextAction.action`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/payment-sessions#next-action).
* If it's `redirect`, refer to [Handling redirect payment methods](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/building-you-workflows/handling-redirect-payment-methods).
* If it's `show_payment_instructions`, refer to [Handling delayed payment methods](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/building-you-workflows/handling-delayed-payment-methods).
### Handling in review orders
[Orders ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders#orders)that are `in_review` should *not* be fulfilled. After an order transitions out of this [`state`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders/order-basics#the-order-lifecycle), Digital River creates either [`order.accepted`](#listening-for-the-order-accepted-event) or [`order.blocked`](#the-fraud-review-failure-event). So, ensure your integration is set up to handle both events.
### Handling accepted orders
When an [order's](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders) [`state` ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders/order-basics#order-states-and-events)becomes `accepted`, move the order in your system into a ready to fulfill state.
Depending on whether the order is [synchronously](#201-created) or [asynchronously](#listening-for-the-order-accepted-event) accepted, you should redirect customers to an order confirmation page and/or send them an [order confirmation notification](https://docs.digitalriver.com/digital-river-api/customer-notifications#order-confirmation).
At this point, [fulfillment operations](https://docs.digitalriver.com/digital-river-api/order-management/fulfillments) can be initiated.
### Handling the `order.cancelled` event
Upon receiving the [event ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/events)with a [`type`](https://docs.digitalriver.com/digital-river-api/events-and-webhooks-1/events-1#event-types) of [`order.cancelled`](#the-order-cancelled-event), we recommend that you:
* Update 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
## Reusing the checkout identifier
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:
{% tabs %}
{% tab title="JSON" %}
```javascript
{
"type": "not_found",
"errors": [
{
"code": "not_found",
"parameter": "orderId",
"message": "Order 180139250336 not found"
}
]
}
```
{% endtab %}
{% endtabs %}
.svg?alt=media&token=172f74f0-3247-4384-a86b-827b650cf9d7)
.svg?alt=media&token=c423f7a9-43fe-4fe6-bb0f-9ae4ca193451)
