# 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/charges/charge-basics.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.