Charge basics
Learn about what a charge is, how it's created, and how captures, cancels, and refunds work
Last updated
Learn about what a charge is, how it's created, and how captures, cancels, and refunds work
Last updated
A charge represents a payment authorization. Digital River handles the charge creation process. The object can contain one or more captures, cancels, and refunds throughout a charge's lifecycle.
Whether you're using or , the payment authorization process remains the same.
At the time of , Digital River creates a charge 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 charge 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 to capturable and creates an event with a of order.charge.capturable.
A charge's amount represents the initial authorization on a customer's payment method. But it's ultimately all the captures, cancellations, and refunds during an order's lifecycle determine how much a customer pays.
An order's payment.charges[] contains an enduring record of all the captures[], cancels[], and refunds[] that occur during that order's lifecycle.
During an order's lifecycle, an order's 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 charge's full amount be captured all at once, while others permit multiple captures.
When a POST/ fulfillments that specifies an items[].quantity is submitted, Digital River attempts to capture payment.
The following POST /fulfillments seeks to partially capture payment on an order.
Once submitted, you can be notified that the capture process has begun by listening for the event 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 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 capturedAmount provides a running total of how much has been settled.
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 can be partially cancelled or only supports full cancellations.
When you send a POST /fulfillments that specifies an items[].cancelQuantity, Digital River attempts to cancel payment.
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 contains two cancels[], each with a unique id and a cancelled amount.
In an order, a payment.charges[].refunds[] represents a partial or full reversal of a payment.charges[].captures[].
An order might contain one or more charges[].refunds[]. Each array element represents a charge refund, which is not the same object as a refund. This is because, for batch processing purposes, Digital River often aggregates numerous refunds into a lesser number of charge refunds.
For example, the following GET /refunds request searches for all the refunds created on an order.
The response shows that, in this particular example, two unique refunds exist, each represented by an element in data[] and both with the same orderId.
This is because two POST /refunds were previously submitted. Digital River, however, added the amount of these unique refunds together to arrive at a single charges[].refunds[].amount.
By passing charges[].id, which is the same in both refunds, as a path parameter in a GET /charges/{id}, you can access the unique id of this single charge refund. Note that its value is different than the id of each of the two refunds.
When a payment authorization request is unsuccessful, the charge's state becomes failed. The same is true for failed captures, cancels, and refunds.
Each of these objects contains a failureMessage and failureCode that you can use to pinpoint a reason for the failure.
A charge's state can be pending, capturable, processing, complete, cancelled, or failed.
When a charge's state changes, Digital River creates a corresponding event. For example, when the charge's state changes from pending to capturable an event 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 and their corresponding events:
...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
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 event with a type of order.charge.cancel.pending, followed by either or .
For more details, refer to the page.
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 .
For more details, refer to the page.
In this particular example, since all of the order's charges[] are either captured or cancelled, the order's state moves to complete and is created.
For details on how to create refunds, refer to or Third.
For more information, refer to and .
For different success and error scenarios, you can to determine whether your integration returns the expected state value.