Offering store credit
Learn how to offer your customers access to their store credit in low-code checkouts
Last updated
Learn how to offer your customers access to their store credit in low-code checkouts
Last updated
Store credit is a unique payment type that allows you to connect your credit management system to the Digital River APIs.
With store credit, you manage a customer's credit on your end and then pass that data to Digital River in so we can offer it as an option in Prebuilt Checkout or Components, our low-code checkout solutions.
On this page, you'll find information on:
You can provide a store credit endpoint in Digital River Dashboard. This allows you to manage the store credit you offer customers more closely and better defeat fraudulent attempts to abuse it.
If customers request to use their store credit in the payment collection stage, Digital River calls this endpoint to determine whether it should be authorized. If your hosted service approves the request, Digital River applies the credit to the purchase. Otherwise, we prevent the customer from using it.
When configuring your endpoint, you must enter a username and password. In both the and the that Digital River sends to your service, these credentials are transmitted using the basic authentication scheme.
If you want to give customers the option to use their store credit in a Prebuilt Checkout or the Payment component, then the body of your must include .
In the payment collection stage, customers might request to use that credit. Once it has been successfully applied to the transaction, they might also want to remove that payment option.
For details on handling both scenarios, refer to Attaching store credit and Removing store credit.
Whenever a customer requests to use their store credit, Digital River checks whether you have a saved endpoint.
To handle our request, you’ll need to have a hosted service set up that uses upstreamId
to look up that line of credit in your system and then check whether its available amount is sufficient to cover the amount
being requested.
If your authorization service determines this to be the case, send a reply with approval
set to true
. Make sure your response also specifies the amount
that's been approved. This value can be lower than the amount
Digital River sent in the request, but it should be greater than 0
.
Otherwise, if you reject the request, set approval
to false
. In this case, you don't need to return amount
.
Whether your service approves or rejects the request, it should return a 200 OK
status code and the body of the response should pass back the same upstreamId
so that we can check the values for parity.
Digital River handles your response by looking at the value of approval
.
In Prebuilt Checkout, after customers request to apply or remove their store credit, Digital River updates the totals in the order summary section.
Customers might also attempt to remove a store credit already successfully applied in the payment stage.
Your service should respond with a 204 No Content
status code and an empty body.
Once Digital River receives this code, we delete that customerCredit
source.
If the event’s data.object
contains one or more payment.sources[]
whose type
is customerCredit
, then customers applied their store credit to that transaction.
For each payment.sources[]
of this type
, we recommend that you use its upstreamId
to look up the line of credit in your system and then deduct how much is available by amount
.
If none exists, we use the and of the storeCredits[]
selected by that customer to create a with a type
of customerCredit
, and then add it to the sources[]
.
However, if we determine that a saved endpoint does exist, we to it.
At a minimum, the body of this s
will contain the amount
and upstreamId
of the selected store credit, plus a sessionId
that uniquely identifies the checkout. If you sent upstreamId
in the create checkout-session request, we also assign this value to sessionUpstreamId
.
If it’s true
, we use upstreamId
and amount
to with a type
of customerCredit
, add it to the sources[]
and then update the experience.
If approval
is false
, Digital River doesn’t . Instead, we display a generic error message to users.
Each time a customer makes this request, Digital River removes that payment option from the sources[]
and determines whether you have a saved store credit endpoint.
If an endpoint exists, Digital River passes the store credit’s upstreamId
as a path parameter in a removed payment notification. This request notifies you that the customer has removed that payment option.
If you're offering customers store credit, you should be set up to process it after it's been successfully applied to an . To do this, configure a webhook to listen for the event with a type
of checkout_session.order.created
.