LogoLogo
System Status
2021-12-13
2021-12-13
  • 2021-12-13
  • Charges
    • Charge basics
  • Checkouts
  • Country specifications
  • Customers
  • Events
  • Fees
  • File Links
    • File link basics
  • Files
    • File basics
  • Fulfillments
  • Fulfillment cancellations
  • Fulfillment orders
  • Fulfillment returns
  • Inventory items
  • Inventory levels
  • Invoices
    • Invoice basics
  • Logistics returns
  • Orders
    • Order basics
  • Payouts
  • Plans
    • Plan basics
  • Refunds
  • Reservations
  • Returns
  • Sales summaries
  • Sales transactions
  • Shipments
  • Shipping labels
  • Shipping quotes
  • SKUs
  • SKU Groups
  • Sources
  • Subscriptions
    • Subscription basics
  • Tax identifiers
  • Webhooks
  • Drop-in checkout links
  • Drop-in checkout sessions
    • Checkout-sessions basics
  • Drop-in shipping quotes
  • Store credit callout
Powered by GitBook
On this page
  • How a charge is created
  • How captures, cancels, and refunds work
  • Captures
  • Cancels
  • Charge refunds
  • Handling charge failures
  • The charge lifecycle
  1. Charges

Charge basics

Learn about what a charge is, how it's created, and how captures, cancels, and refunds work

PreviousChargesNextCheckouts

Last updated 5 months ago

A represents a payment authorization. Digital River handles the . The object can contain one or more throughout a .

How a charge is created

Whether you're using or , the payment authorization process remains the same.

At the time of , Digital River creates a whose amount is equal to the associated amount and then submits an authorization request that gets routed to the appropriate payment provider.

For example, as you , customers might provide credit card information during the . This information is then used to that you . After you convert, Digital River creates a 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 to capturable and creates an with a of order.charge.capturable.

Once a provider authorizes payment, the charge on a credit card typically remains capturable for seven days.

A amount represents the initial authorization on a customer's payment method. But it's ultimately all the during determine how much a customer pays.

{
    "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"
            }
        ],
        ...
    }
    ...
}

How captures, cancels, and refunds work

Order
{
    "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"
            }
        ],
    ...
}
Order
{
    "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,
    ...
}

Captures

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
    }
  ]
}'
{
    "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,
    ...
}

Cancels

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
    }
  ]
}'

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

{
    "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,
    ...
}

Charge refunds

{
    "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

curl --location 'https://api.digitalriver.com/refunds?orderId=312049410336' \
...
--header 'Authorization: Bearer <Secret API Key>' \
...
--data ''
Refunds
{
    "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"
                }
            ]
        }
    ]
}
curl --location 'https://api.digitalriver.com/charges/7574d182-b47a-4740-911b-8c584665493a' \
...
--header 'Authorization: Bearer <Secret API key>' \
...
--data ''
{
    "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
}

Handling charge failures

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

The charge lifecycle

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

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

An payment.charges[] contains an enduring record of all the , , and that occur during that .

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 is created.

For example, when you initiate the , Digital River creates an with a type of order.charge.cancel.pending, followed by either or .

During an , an 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.

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 full amount be captured all at once, while others permit multiple captures.

When a that specifies an items[].quantity is submitted, Digital River attempts to capture payment.

For more details, refer to the page.

The following POST /fulfillments seeks to partially capture payment on an .

Once submitted, you can be notified that the capture process has begun by listening for the 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 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 capturedAmount provides a running total of how much has been settled.

In this example, since the order's 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 .

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 can be partially cancelled or only supports full cancellations.

When you send a that specifies an items[].cancelQuantity, Digital River attempts to cancel payment.

For more details, refer to the page.

In the above example, the POST /fulfillments informed our payment services that two line items were cancelled. As a result, the contains two cancels[], each with a unique id and a cancelled amount.

In this particular example, since all of the charges[] are either captured or cancelled, the order's moves to complete and is created.

In an , a payment.charges[].refunds[] represents a partial or full reversal of a payment.charges[].captures[].

An might contain one or more charges[].refunds[]. Each array element represents a , which is not the same object as a . This is because, for batch processing purposes, Digital River often aggregates numerous into a lesser number of .

For details on how to create , refer to or Third.

For example, the following request searches for all the created on an .

The response shows that, in this particular example, two unique exist, each represented by an element in data[] and both with the same orderId.

This is because two were previously submitted. Digital River, however, added the amount of these unique together to arrive at a single charges[].refunds[].amount.

By passing charges[].id, which is the same in both , as a path parameter in a , you can access the unique id of this single . Note that its value is different than the id of each of the two refunds.

When a payment authorization request is unsuccessful, the becomes failed. The same is true for failed , , and .

For more information, refer to and .

A state can be pending, capturable, processing, complete, cancelled, or failed.

When a charge's state changes, Digital River creates a corresponding . For example, when the charge's state changes from pending to capturable an with a type of order.charge.capturable is created.

The following table lists the possible states of a and their corresponding events:

For different success and error scenarios, you can to determine whether your integration returns the expected state value.

charge's
POST/ fulfillments
order
event
order
order's
charge
order
order
refunds
POST /refunds
refunds
charge's
event
event
charge
charge's
state
captures
cancels
refunds
charge
charge
charge
event
charge's
charge creation process
captures, cancels, and refunds
charge's lifecycle
state
captures, cancellations, and refunds
order's
captures[]
cancels[]
refunds[]
event
order's
order's
order
charge refund
refund
refunds
refunds
refunds
order
refunds
charge refunds
GET /charges/{id}
charge refund
GET /refunds
order's lifecycle
order's lifecycle
POST /fulfillments
an order's lifecycle
state
Low-code checkouts
Direct integrations
order creation
source's
build a Direct Integrations' checkout
payment collection stage
create a primary source
associate with the checkout
the checkout to an order
type
event
payment cancellation process
order.charge.cancel.complete
order.charge.cancel.failed
Capturing and cancelling payment charges
primary payment source
order.charge.capture.complete
Capturing and cancelling payment charges
order.complete
Issuing refunds
-party coordinated returns
authorization declines
handling rejected orders
create tests