Applying store credit
Learn how to apply store credit
This page explains how to use store credit in versions 2021-03-23
and higher. For versions 2020-09-30
, 2020-12-17
, and 2021-02-23
, refer to Applying store credit (legacy).
For non-recurring transactions, customers can pay using store credit, a unique payment type that allows you to connect your credit management system to the Digital River APIs. With store credit, you manage customers' credit on your end, and can display the amount available to them during the checkout process.
Store credit is a single-use payment source and therefore can't be saved to a customer's record.
You create the store credit payment source and then attach the resource to the checkout. Once the order is created, you'll also need to search for store credit and deduct its amount.
With store credit, the steps necessary to handle fulfillments and request refunds remain the same, but, if an order's sources[]
contain store credit and a primary payment source, you should be aware of how Digital River handles captures, cancels, and refunds.
Digital River API does not currently support Amazon Pay with store credit.
Creating store credit
When customers opt to pay with store credit and they've specified an allowable amount, send your confidential API key in a POST /sources
.
When defining the request:
Retrieve the checkout's
payment.session.id
and use it to setpaymentSessionId
.Pass the
amount
of credit you're extending the customer.Set
type
tocustomerCredit
.Use
upstreamId
to pass the identifier of the line of credit in your system.Send an empty
customerCredit
object.
An owner
hash table is optional and can be used to meet our billing address requirements.
A response with a 201 OK
status code contains a unique source with a type
of customerCredit
whose state
is chargeable
.
Attaching store credit to checkouts
After you create a store credit payment source, you'll need to retrieve its id
and use that value to associate the source with the checkout.
Before submitting this request, check to determine whether the source's amount
is less than or equal to the checkout's payment.session.amountRemainingToContribute
. If that's not the case, then the following error is thrown:
At what point in the flow you should submit this request depends on whether customers are (1) paying entirely with store credit, (2) combining store credit with a single-use primary payment source, or (3) combining store credit with a reusable primary payment source.
For details, refer to Combining primary and secondary sources on the Managing sources page.
In any of these cases, Digital River first computes taxes based on the checkout's totalAmount
, and then applies the store credit.
Handling store credit in orders
After the necessary payment preconditions are met to successfully convert the checkout to an order, and the order's state
is accepted
, iterate through its sources[]
and identify any that have a type
of customerCredit
. For each of these objects, use its upstreamId
to look up the line of credit in your system and deduct what's available by amount
.
Last updated