Issuing refunds
Learn how to use the Refunds API to issue full and partial refunds
Last updated
Learn how to use the Refunds API to issue full and partial refunds
Last updated
The allows you to reimburse customers for product costs, shipping expenses, taxes, duties, and regulatory fees.
Once you configure and create a refund, your integration should be set up to handle refund state changes.
To tailor a refund so that customers are only reimbursed for specific, non-product related expenses, you must specify type
.
Before submitting a request, make sure you have:
The should only be used once an is partially or completely fulfilled.
This is because can only be created on with in a state
of complete
. To be notified of this state
change event, you can subscribe to order.charge.capture.complete
.
Once a is complete
, Digital River increases availableToRefundAmount
.
A 200 OK
response contains an availableToRefundAmount
at both the order-level and the item-level.
At a high level, Digital River calculates these values by using the following formula:
availableToRefundAmount =
charge(s)amount
captured
− (
completed refunds
amount +
pending refunds
amount)
If you submit a POST/refunds
whose amount
is greater than the order's availableToRefundAmount
, or whose items[].amount
is greater than that items[].availableToRefundAmount
, then a 400 Bad Request
is thrown:
At the order level, availableToRefundAmount
reflects the unrefunded portion of an order's capturedAmount
. This availableToRefundAmount
may include product prices and any expenses related to shipping, duties, fees, and assessed taxes.
In the following example, note that each line item's availableToRefundAmount
excludes its shipping.amount
and shipping.taxAmount
.
You can issue product refunds at the order level and the line item level.
Omits type
Either (1) sets percent
to a value in the range of 0.01
to 100.00
inclusive or (2) sets amount
to a value that's less than or equal to the order's availableToRefundAmount
If you set percent
to 100
or amount
to the order's availableToRefundAmount
, then Digital River attempts to reimburse the full availableToRefundAmount
.
Omits items[].type
.
Either (1) sets items[].percent
to a value in the range of 0.01
to 100.00
, inclusive or (2) sets items[].amount
to a value that's less than or equal to that items[].availableToRefundAmount
.
If you configure the request this way, Digital River will attempt to refund the specified quantity
of items[]
by the given percent
or amount
.
Along with product costs, line item-level refund requests using this configuration proportionally reimburse that items[].tax.amount
. They do not, however, refund any shipping, regulatory fee, importer tax, or duty amounts (along with taxes assessed on those amounts) that are associated with that items[]
.
To get those expenses back, you could submit a separate POST /refunds
that specifies items[].type
.
When issuing refunds on product costs, make sure you omit type
in your POST /refunds
request.
For details on how to configure a refund request when type
is tax
or importer_tax
, refer to Refunding taxes.
In POST/refunds
, by setting type
to tax
, you can reimburse just the tax component of an order. You can't, however, partially refund taxes using type
.
In these cases, if you retrieve an order's totalTax
, and use that value to set amount
in a POST /refunds
, then a 400 Bad Request
is returned.
You also can issue refunds only on shipping costs. To do this, set type
to shipping
and specify an amount
or percent
.
In these cases, if you retrieve totalShipping
, and use that value to set amount
in a POST/refunds
, then a 400 Bad Request
is returned.
This state
indicates that Digital River and the payment processor have all the information they need to initiate the refund process.
A 201 Created
response code doesn't signify that the bank approved the refund. It only means that your refund request was successfully sent. To be notified of approved refunds, listen for the refund.complete
event.
You can use refund.pending
to trigger a notification to customers, informing them that their refund is being processed. Ensure you also update the refund status on their order details page.
In some cases, customers must first supply their banking details before payment processors act on a refund request. This is common when the purchase was made with a wire transfer or other delayed payment method.
For more information on how to handle this state
change, refer to the Refunding asynchronous payment methods page.
In the payload, amount
is how much you requested be refunded and refundedAmount
is the actual reimbursed amount.
You can use refund.complete
to trigger a refund confirmation email to customers. The message (typically an email) should notify them that their refund request was successful and inform them how much they were reimbursed. Ensure you also update the refund status on their order details page.
Some common reasons for a refund failure include:
A closed account
A frozen account due to suspected fraud
An expired credit card
Before submitting a , you can make a to determine whether the amount
you're requesting is less than or equal to what's available.
In orders, items[].availableToRefundAmount
reflects the unrefunded portion of that line item's amount
plus its tax.amount
. It doesn't include expenses related to shipping, duties, or fees.
If you'd like to refund shipping costs associated with an individual items[]
, then you can determine what customers paid by accessing items[].shipping.amount
and items[].shipping.taxAmount
.
A requires currency
. After you submit this request, Digital River doesn't perform a currency conversion. As a result, the value you pass must be the same as the associated currency
. If they're different, a 400 Bad Request
is thrown:
Before submitting a request, specific preconditions must exist. Once satisfied, you can request a variety of refunds. The following sections provide information on how to reimburse:
If you'd like to refund an product costs, then ensure that the body of your :
If you pass any lower percent
or amount
, then an product costs, shipping expenses, duties, and taxes are proportionally refunded.
Product refund requests do not reimburse regulatory fees. To do that, you must set type
to fees
in a separate .
If you'd like to refund an items[]
product costs, then ensure that the body of your :
Specifies an items[].quantity
that is less than or equal to the corresponding items[].quantity
in the .
If you want to only reimburse specific, non-product related costs, such as shipping, duties, regulatory fees, and taxes, your must specify type
at either the order-level or the line item-level.
When type
is shipping
, fees
, or duty
, any taxes assessed on those particular components of the are also refunded.
The doesn't support tax-only reimbursements at the items[]
level.
If you submit a that specifies a type
of tax
, then either (1) percent
must be 100
or (2) amount
must be equal to the unrefunded portion of an totalTax
. If either of these conditions are not met, then a 400 Bad Request
is returned.
When refunding taxes, we recommend you use percent
instead of amount
. This is because an totalTax
doesn't always reflect how much refundable tax exists. Previous refunds may have reduced what's available.
After you successfully submit a POST /refunds
with a type
of tax
, Digital River attempts to reclaim the unrefunded portion of an totalTax
.
We recommend using percent
instead of amount
. This is because an totalShipping
doesn't always reflect the actual refundable shipping costs. Previous refunds may have reduced what's available.
Depending on the value you assign percent
, passing a type
of shipping
fully or partially refunds both an shippingChoice.amount
and shippingChoice.tax
After submitting a refund request, we recommend that your integration be set up to listen for the following :
When a is successful, Digital River sets the state
to pending
and creates a refund.pending
event.
In that have a state
of pending
, refundedAmount
is always 0.0
.
When the bank requests this additional information, Digital River moves the state
to pending_information
and creates a refund.pending_information
event.
When a is successfully processed, Digital River moves its state
to succeeded
and creates an with a type
of refund.complete
.
If your refund request fails, Digital River moves the state
to failed
and creates a refund.failed
event. In these cases, refundedAmount
is 0.0
.
If a refund fails, your integration can attempt to submit another using the same itemId
(s) and/or orderId
. Alternatively, you can try to manually process the refund in Digital River Dashboard.
An refundedAmount
contains the total amount of all refunds issued on an order. This is a useful value to display to customers on their order details page.