> For the complete documentation index, see [llms.txt](https://docs.digitalriver.com/digital-river-api-reference/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/charges/charge-basics.md).

# Charge basics

A [charge ](https://www.digitalriver.com/docs/digital-river-api-reference/#tag/Charges)represents a payment authorization. Digital River handles the [charge creation process](#how-a-charge-is-created). The object can contain one or more [captures, cancels, and refunds](#how-captures-cancels-and-refunds-work) throughout a [charge's lifecycle](#the-charge-lifecycle).

## How a charge is created

Whether you're using [Low-code checkouts](https://docs.digitalriver.com/digital-river-api/integration-options/low-code-checkouts) or [Direct integrations](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts), the payment authorization process remains the same.

At the time of [order creation](https://docs.digitalriver.com/digital-river-api/order-management/creating-and-updating-an-order), Digital River creates a [charge](https://www.digitalriver.com/docs/digital-river-api-reference/#tag/Charges) whose `amount` is equal to the associated [source's ](https://docs.digitalriver.com/digital-river-api/payments/payment-sources)`amount` and then submits an authorization request that gets routed to the appropriate payment provider.

For example, as you [build a Direct Integrations' checkout](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts), customers might provide credit card information during the [payment collection stage](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts#collecting-payment). This information is then used to [create a primary source](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/using-the-source-identifier#creating-primary-sources) that you [associate with the checkout](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/using-the-source-identifier#attaching-sources-to-checkouts). After you convert[ the checkout to an order](https://docs.digitalriver.com/digital-river-api/order-management/creating-and-updating-an-order#creating-an-order-with-the-checkout-identifier), Digital River creates a [charge](https://www.digitalriver.com/docs/digital-river-api-reference/#tag/Charges) and then sends an authorization request to a payment processor who forwards it to a payment provider. If the request is approved by the provider, Digital River moves the charge's [`state`](#the-charge-lifecycle) to `capturable` and creates an [event ](/digital-river-api-reference/2021-12-13/events.md)with a [`type` ](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/events-1#event-types)of `order.charge.capturable`.

{% hint style="info" %}
Once a provider authorizes payment, the charge on a credit card typically remains `capturable` for seven days.
{% endhint %}

A [charge's](/digital-river-api-reference/2021-12-13/charges.md) `amount` represents the initial authorization on a customer's payment method. But it's ultimately all the [captures, cancellations, and refunds](#how-captures-cancels-and-refunds-work) during [an order's lifecycle](/digital-river-api-reference/2021-12-13/orders/order-basics.md#the-order-lifecycle) determine how much a customer pays.

{% tabs %}
{% tab title="Order" %}

```javascript
{
    "id": "178727320336",
    ...
    "state": "accepted",
    ...
    "payment": {
        "charges": [
            {
                "id": "b469adb4-d9d1-4baa-80b1-e55c26feb4e8",
                "createdTime": "2020-07-02T20:10:47Z",
                "currency": "USD",
                "amount": 145.16,
                "state": "capturable",
                "captured": false,
                "refunded": false,
                "sourceId": "9d9cff59-2b43-4b0a-a171-f49a243e5ea8"
            }
        ],
        ...
    }
    ...
}
```

{% endtab %}
{% endtabs %}

## How captures, cancels, and refunds work

An [order's](https://www.digitalriver.com/docs/digital-river-api-reference/#tag/Orders) `payment.charges[]` contains an enduring record of all the [`captures[]`](#captures), [`cancels[]`](#cancels), and [`refunds[]`](#refunds) that occur during that [order's lifecycle](/digital-river-api-reference/2021-12-13/orders/order-basics.md#the-order-lifecycle).

{% code title="Order" %}

```javascript
{
    "id": "178728710336",
    "createdTime": "2020-07-02T21:43:28Z",
    ...
    "payment": {
        "charges": [
            {
                "id": "c23d5317-3410-4abb-af86-8c8570b9dc90",
                "createdTime": "2020-07-02T21:43:30Z",
                "currency": "USD",
                "amount": 145.16,
                "state": "complete",
                "captured": true,
                "captures": [
                    {
                        "id": "075224cd-0d07-440f-9c16-a17f16cb9692",
                        "createdTime": "2020-07-02T21:50:35Z",
                        "amount": 64.52,
                        "state": "complete"
                    },
                    {
                        "id": "966387d3-3693-4d35-bf8e-9f190b58e2a8",
                        "createdTime": "2020-07-02T21:50:35Z",
                        "amount": 24.2,
                        "state": "complete"
                    }
                ],
                "refunded": true,
                "refunds": [
                    {
                        "createdTime": "2020-07-02T22:39:00Z",
                        "amount": 53.77,
                        "state": "complete"
                    }
                ],
                "cancels": [
                    {
                        "id": "5c13a17a-8c30-4550-be27-ddd84894b45e",
                        "createdTime": "2020-07-02T21:54:51Z",
                        "amount": 32.26,
                        "state": "complete"
                    },
                    {
                        "id": "58d9ff72-d043-4e00-9552-fb6dd8144a6c",
                        "createdTime": "2020-07-02T21:54:51Z",
                        "amount": 24.18,
                        "state": "complete"
                    }
                ],
                "sourceId": "9d9cff59-2b43-4b0a-a171-f49a243e5ea8",
                "type": "customer_initiated"
            }
        ],
    ...
}
```

{% endcode %}

All captures, cancels, and refunds have an initial `state` of `pending` and then either transition to `complete` or `failed`. With each of these `state` transitions, a corresponding [event ](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/events-1)is created.

For example, when you initiate the [payment cancellation process](https://docs.digitalriver.com/digital-river-api/order-management/informing-digital-river-of-a-fulfillment), Digital River creates an [event](https://www.digitalriver.com/docs/digital-river-api-reference/#tag/Events) with a `type` of `order.charge.cancel.pending`, followed by either [`order.charge.cancel.complete`](https://docs.digitalriver.com/digital-river-api/order-management/informing-digital-river-of-a-fulfillment#successful-charge-captures) or [`order.charge.cancel.failed`](https://docs.digitalriver.com/digital-river-api/order-management/informing-digital-river-of-a-fulfillment#failed-charge-captures).

During an [order's lifecycle](/digital-river-api-reference/2021-12-13/orders/order-basics.md#the-order-lifecycle), an [order's ](/digital-river-api-reference/2021-12-13/orders.md)`totalAmount` and each of its `payment.charges[].amount`(s) remain unaltered. The actual amount a payment method is debited or credited is reflected by `capturedAmount` and `refundedAmount`, respectively.

{% code title="Order" %}

```javascript
{
    "id": "178728710336",
    ...
    "totalAmount": 145.16,
    ...
    "refundedAmount": 53.77,
    "state": "complete",
    ...
    "charges": [
        {
            "id": "c23d5317-3410-4abb-af86-8c8570b9dc90",
            "createdTime": "2020-07-02T21:43:30Z",
            "currency": "USD",
            "amount": 145.16,
            "state": "processing",
            "captured": true,
            "captures": [
                ...
            ],
            "refunded": true,
            "refunds": [
                {
                    "createdTime": "2020-07-02T22:39:00Z",
                    "amount": 53.77,
                    "state": "complete"
                }
            ],
            "cancels": [
                ...
            ],
            "sourceId": "9d9cff59-2b43-4b0a-a171-f49a243e5ea8"
        }
    ],
    ...
    "capturedAmount": 88.72,
    "cancelledAmount": 56.44,
    "availableToRefundAmount": 34.94,
    ...
}
```

{% endcode %}

### Captures

A capture represents the settling of an authorization. In other words, how much a customer's payment method is debited. Some payment methods require that a [charge's ](/digital-river-api-reference/2021-12-13/charges.md)full `amount` be captured all at once, while others permit multiple captures.

When a [`POST/ fulfillments`](/digital-river-api-reference/2021-12-13/fulfillments.md) that specifies an `items[].quantity` is submitted, Digital River attempts to capture payment.

{% hint style="info" %}
For more details, refer to the [Capturing and cancelling payment charges](https://docs.digitalriver.com/digital-river-api/order-management/informing-digital-river-of-a-fulfillment) page.
{% endhint %}

The following `POST /fulfillments` seeks to partially capture payment on an [order](/digital-river-api-reference/2021-12-13/orders.md).

{% tabs %}
{% tab title="POST /fulfillments" %}

```
curl --location --request POST 'https://api.digitalriver.com/fulfillments' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API_key>' \
...
  "orderId": "178728710336",
  "items": [
    {
      "itemId": "98014170336",
      "quantity": 1
    },
    {
      "itemId": "98014180336",
      "quantity": 2
    }
  ]
}'
```

{% endtab %}
{% endtabs %}

Once submitted, you can be notified that the capture process has begun by listening for the [event](https://www.digitalriver.com/docs/digital-river-api-reference/#tag/Events) with a `type` of `order.charge.capture.pending`.

In the above example, the `POST /fulfillments` informed our payment services that two line items were fulfilled. As a result, the [order](https://www.digitalriver.com/docs/digital-river-api-reference/#tag/Orders) contains two `captures[]`, each with a unique `id` and a captured `amount`. As more goods are fulfilled, and you respond by submitting additional `POST /fulfillments`, an [order's](/digital-river-api-reference/2021-12-13/orders.md) `capturedAmount` provides a running total of how much has been settled.

{% tabs %}
{% tab title="Order" %}

```javascript
{
    "id": "178728710336",
    ...
    "payment": {
        "charges": [
            {
                "id": "c23d5317-3410-4abb-af86-8c8570b9dc90",
                "createdTime": "2020-07-02T21:43:30Z",
                "currency": "USD",
                "amount": 145.16,
                "state": "complete",
                "captured": true,
                "captures": [
                    {
                        "id": "075224cd-0d07-440f-9c16-a17f16cb9692",
                        "createdTime": "2020-07-02T21:50:35Z",
                        "amount": 64.52,
                        "state": "complete"
                    },
                    {
                        "id": "966387d3-3693-4d35-bf8e-9f190b58e2a8",
                        "createdTime": "2020-07-02T21:50:35Z",
                        "amount": 24.2,
                        "state": "complete"
                    }
                ],
                ...
                "sourceId": "9d9cff59-2b43-4b0a-a171-f49a243e5ea8",
                "type": "customer_initiated"
            }
        ],
        "sources": [
            {
                "id": "9d9cff59-2b43-4b0a-a171-f49a243e5ea8",
                "type": "creditCard",
                "amount": 145.16,
                ...
                },
                "creditCard": {
                    "brand": "Visa",
                    "expirationMonth": 7,
                    "expirationYear": 2027,
                    "lastFourDigits": "1111"
                }
            }
        ],
        ...
    },
    ...
    "capturedAmount": 88.72,
    ...
}
```

{% endtab %}
{% endtabs %}

In this example, since the order's [primary payment source](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/using-the-source-identifier#primary-payment-sources) has a `type` of `creditCard`, each `captures[]` will (typically) briefly transition to a `state` of `pending` before becoming `complete`. Once a capture moves into this `state`, Digital River creates [`order.charge.capture.complete`](https://docs.digitalriver.com/digital-river-api/order-management/informing-digital-river-of-a-fulfillment#successful-charge-captures).

### Cancels

A cancel negates all or part of a payment authorization. Cancels don't result in the debiting or crediting of a customer's payment method. That same underlying payment method determines whether a [charge](https://www.digitalriver.com/docs/digital-river-api-reference/#tag/Charges) can be partially cancelled or only supports full cancellations.

When you send a [`POST /fulfillments`](/digital-river-api-reference/2021-12-13/fulfillments.md#fulfillments-1) that specifies an `items[].cancelQuantity`, Digital River attempts to cancel payment.

{% hint style="info" %}
For more details, refer to the [Capturing and cancelling payment charges](https://docs.digitalriver.com/digital-river-api/order-management/informing-digital-river-of-a-fulfillment) page.
{% endhint %}

{% tabs %}
{% tab title="POST /fulfillments" %}

```
curl --location --request POST 'https://api.digitalriver.com/fulfillments' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API_key>' \
...
--data-raw '{
  "orderId": "178728710336",
  "items": [
    {
      "itemId": "98014170336",
      "cancelQuantity": 1
    },
    {
      "itemId": "98014180336",
      "cancelQuantity": 1
    }
  ]
}'
```

{% endtab %}
{% endtabs %}

Once submitted, you can be notified that the cancellation process has begun by listening for the `order.charge.cancel.pending`.

In the above example, the `POST /fulfillments` informed our payment services that two line items were cancelled. As a result, the [order ](/digital-river-api-reference/2021-12-13/orders.md)contains two `cancels[]`, each with a unique `id` and a cancelled `amount`.

In this particular example, since all of the [order's ](/digital-river-api-reference/2021-12-13/orders.md)`charges[]` are either captured or cancelled, the order's [`state` ](/digital-river-api-reference/2021-12-13/orders/order-basics.md#order-states-and-events)moves to `complete` and [`order.complete`](https://docs.digitalriver.com/digital-river-api/order-management/informing-digital-river-of-a-fulfillment#handling-the-order-complete-event) is created.

{% tabs %}
{% tab title="Order" %}

```javascript
{
    "id": "178728710336",
    ...
    "totalAmount": 145.16,
    ...
    "state": "complete",
    ...
    "payment": {
        "charges": [
            {
                "id": "c23d5317-3410-4abb-af86-8c8570b9dc90",
                "createdTime": "2020-07-02T21:43:30Z",
                "currency": "USD",
                "amount": 145.16,
                "state": "processing",
                "captured": true,
                "captures": [
                    ...
                ],
                "refunded": false,
                "cancels": [
                    {
                        "id": "5c13a17a-8c30-4550-be27-ddd84894b45e",
                        "createdTime": "2020-07-02T21:54:51Z",
                        "amount": 32.26,
                        "state": "complete"
                    },
                    {
                        "id": "58d9ff72-d043-4e00-9552-fb6dd8144a6c",
                        "createdTime": "2020-07-02T21:54:51Z",
                        "amount": 24.18,
                        "state": "complete"
                    }
                ],
                "sourceId": "9d9cff59-2b43-4b0a-a171-f49a243e5ea8"
            }
        ],
    ...
    }
    "capturedAmount": 88.72,
    "cancelledAmount": 56.44,
    "availableToRefundAmount": 88.71,
    ...
}
```

{% endtab %}
{% endtabs %}

### Charge refunds <a href="#refunds" id="refunds"></a>

In an [order](/digital-river-api-reference/2021-12-13/orders.md), a `payment.charges[].refunds[]` represents a partial or full reversal of a `payment.charges[].captures[]`. &#x20;

```json
{
    "id": "312049410336",
    ...
    "payment": {
        "charges": [
            {
                "id": "7574d182-b47a-4740-911b-8c584665493a",
                "createdTime": "2024-04-29T16:08:43Z",
                "currency": "USD",
                "amount": 100.0,
                "state": "complete",
                "captured": true,
                "captures": [
                    {
                        "id": "d07e1f98-c206-4e08-9f8a-4601f74c18e8",
                        "createdTime": "2024-04-29T16:08:50Z",
                        "amount": 100.0,
                        "state": "complete"
                    }
                ],
                "refunded": true,
                "refunds": [
                    {
                        "createdTime": "2024-04-29T16:12:11Z",
                        "amount": 36.0,
                        "state": "complete"
                    }
                ],
                "sourceId": "bc8cd140-bdf1-4a50-8ad1-eee0b157a3d8",
                "type": "customer_initiated"
            }
        ],
        ...
    },
    ...
    "capturedAmount": 100.0,
    "cancelledAmount": 0.0,
    "availableToRefundAmount": 64.0,
    "checkoutId": "aabbd115-7e1e-4a0b-ae1c-036972ddbab6"
}
```

#### How refunds differ from charge refunds

An [order ](/digital-river-api-reference/2021-12-13/orders.md)might contain one or more `charges[].refunds[]`. Each array element represents a [charge refund](/digital-river-api-reference/2021-12-13/charges.md), which is not the same object as a [refund](/digital-river-api-reference/2021-12-13/refunds.md). This is because, for batch processing purposes, Digital River often aggregates numerous [refunds](https://www.digitalriver.com/docs/digital-river-api-reference/#tag/Refunds) into a lesser number of [charge refunds](/digital-river-api-reference/2021-12-13/charges.md#charges-id).

{% hint style="success" %}
For details on how to create [refunds](/digital-river-api-reference/2021-12-13/refunds.md), refer to [Issuing refunds](https://docs.digitalriver.com/digital-river-api/order-management/returns-and-refunds-1/refunds/issuing-refunds) or Third[-party coordinated returns](https://docs.digitalriver.com/digital-river-api/order-management/returns-and-refunds-1/returns/creating-a-return).
{% endhint %}

For example, the following [`GET /refunds`](/digital-river-api-reference/2021-12-13/refunds.md#refunds) request searches for all the [refunds](https://www.digitalriver.com/docs/digital-river-api-reference/#tag/Refunds) created on an [order](/digital-river-api-reference/2021-12-13/orders.md).

The response shows that, in this particular example, two unique [refunds ](/digital-river-api-reference/2021-12-13/refunds.md)exist, each represented by an element in `data[]` and both with the same `orderId`.&#x20;

This is because two [`POST /refunds`](/digital-river-api-reference/2021-12-13/refunds.md) were previously submitted. Digital River, however, added the `amount` of these unique [refunds](/digital-river-api-reference/2021-12-13/refunds.md) together to arrive at a single `charges[].refunds[].amount`.

{% tabs %}
{% tab title="Request" %}

```
curl --location 'https://api.digitalriver.com/refunds?orderId=312049410336' \
...
--header 'Authorization: Bearer <Secret API Key>' \
...
--data ''
```

{% endtab %}

{% tab title="Response" %}
{% code title="Refunds" %}

```javascript
{
    "hasMore": false,
    "data": [
        {
            "id": "re_050b3f92-fc2d-4fdb-80e2-74b8566fd9dd",
            "amount": 16.0,
            "createdTime": "2024-04-29T16:10:15Z",
            "currency": "USD",
            "items": [],
            "orderId": "312049410336",
            "refundedAmount": 16.0,
            "state": "succeeded",
            "liveMode": false,
            "charges": [
                {
                    "id": "7574d182-b47a-4740-911b-8c584665493a",
                    "captured": true,
                    "refunded": true,
                    "refunds": [
                        {
                            "createdTime": "2024-04-29T16:12:11Z",
                            "amount": 36.0,
                            "state": "complete"
                        }
                    ],
                    "sourceId": "bc8cd140-bdf1-4a50-8ad1-eee0b157a3d8"
                }
            ]
        },
        {
            "id": "re_d8369038-d365-448d-bf9d-8a7551a609ae",
            "amount": 20.0,
            "createdTime": "2024-04-29T16:10:14Z",
            "currency": "USD",
            "items": [],
            "orderId": "312049410336",
            "refundedAmount": 20.0,
            "state": "succeeded",
            "liveMode": false,
            "charges": [
                {
                    "id": "7574d182-b47a-4740-911b-8c584665493a",
                    "captured": true,
                    "refunded": true,
                    "refunds": [
                        {
                            "createdTime": "2024-04-29T16:12:11Z",
                            "amount": 36.0,
                            "state": "complete"
                        }
                    ],
                    "sourceId": "bc8cd140-bdf1-4a50-8ad1-eee0b157a3d8"
                }
            ]
        }
    ]
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

By passing `charges[].id`, which is the same in both [refunds](/digital-river-api-reference/2021-12-13/refunds.md), as a path parameter in a [`GET /charges/{id}`](/digital-river-api-reference/2021-12-13/charges.md#charges-id), you can access the unique `id` of this single [charge refund](/digital-river-api-reference/2021-12-13/charges.md#charges-id). Note that its value is different than the `id` of each of the two refunds.

{% tabs %}
{% tab title="Request" %}

```
curl --location 'https://api.digitalriver.com/charges/7574d182-b47a-4740-911b-8c584665493a' \
...
--header 'Authorization: Bearer <Secret API key>' \
...
--data ''
```

{% endtab %}

{% tab title="Response" %}

```json
{
    "id": "7574d182-b47a-4740-911b-8c584665493a",
    "createdTime": "2024-04-29T16:08:43Z",
    "currency": "USD",
    "amount": 100.0,
    "state": "complete",
    "orderId": "312049410336",
    "captured": true,
    "captures": [
        {
            "id": "d07e1f98-c206-4e08-9f8a-4601f74c18e8",
            "createdTime": "2024-04-29T16:08:50Z",
            "amount": 100.0,
            "state": "complete",
            "fulfillmentId": "ful_47583179-91f6-440c-89c0-2939ec828d4f"
        }
    ],
    "refunded": true,
    "refunds": [
        {
            "id": "5a668d85-a0a5-49bc-80bd-5488465933ed",
            "createdTime": "2024-04-29T16:12:11Z",
            "amount": 36.0,
            "state": "complete"
        }
    ],
    "sourceId": "bc8cd140-bdf1-4a50-8ad1-eee0b157a3d8",
    "paymentSessionId": "2b7c5564-786e-4243-aef3-794e3e467ec3",
    "type": "customer_initiated",
    "liveMode": false
}
```

{% endtab %}
{% endtabs %}

## Handling charge failures <a href="#handling-failures" id="handling-failures"></a>

When a payment authorization request is unsuccessful, the [charge's ](/digital-river-api-reference/2021-12-13/charges.md)[`state`](#the-charge-lifecycle) becomes `failed`. The same is true for failed [captures](#captures), [cancels](#cancels), and [refunds](#refunds).

Each of these objects contains a `failureMessage` and `failureCode` that you can use to pinpoint a reason for the failure.

For more information, refer to [authorization declines](https://docs.digitalriver.com/digital-river-api/payments/authorization-declines) and [handling rejected orders](https://docs.digitalriver.com/digital-river-api/order-management/resubmitting-an-order).

## The charge lifecycle

A [charge's](/digital-river-api-reference/2021-12-13/charges.md) `state` can be `pending`, `capturable`, `processing`, `complete`, `cancelled`, or `failed`.

When a charge's `state` changes, Digital River creates a corresponding [event](/digital-river-api-reference/2021-12-13/events.md). For example, when the charge's `state` changes from `pending` to `capturable` an [event](/digital-river-api-reference/2021-12-13/events.md) with a `type` of `order.charge.capturable` is created.

The `state` values for a successful charge (i.e. the happy path) are `pending` > `capturable` > `processing` > `complete` .

The following table lists the possible states of a [charge ](/digital-river-api-reference/2021-12-13/charges.md)and their corresponding events:

| 1) When the charge...                                                                                                 | (2) its state transitions to... | (3) and an...event is emitted. |
| --------------------------------------------------------------------------------------------------------------------- | ------------------------------- | ------------------------------ |
| ...is awaiting authorization, typically because additional customer action is required                                | `pending`                       | `order.charge.pending`         |
| ...is authorized by the payment provider                                                                              | `capturable`                    | `order.charge.capturable`      |
| ...is being processed by the payment provider                                                                         | `processing`                    | `order.charge.processing`      |
| ...is captured in full (or captured in part with the remainder cancelled) and there are no pending charge operations. | `complete`                      | `order.charge.complete`        |
| ...is cancelled in full and there are no pending charge operations.                                                   | `cancelled`                     | `order.charge.cancelled`       |
| fails to authorize                                                                                                    | `failed`                        | `order.charge.failed`          |

For different success and error scenarios, you can [create tests](https://docs.digitalriver.com/digital-river-api/payments/testing-scenarios) to determine whether your integration returns the expected `state` value.