Offering store credit
Learn how to offer your customers access to their store credit in low-code checkouts
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 create checkout-session requests 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:
Providing a store credit endpoint
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 payment authorization request and the removed store credit notification that Digital River sends to your service, these credentials are transmitted using the basic authentication scheme.
Managing store credit in checkouts
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 create checkout-session request must include options.storeCredits[].
In the payment collection stage, customers might request to use that credit. Once 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.
Attaching store credit
Whenever a customer requests to use their store credit, Digital River checks whether you have a saved endpoint.
If none exists, we use the upStreamId and amount of the storeCredits[] selected by that customer to create a source with a type of customerCredit, and then add it to the checkout-session’s sources[].
However, if we determine that a saved endpoint does exist, we send a store credit authorization request to it.
At a minimum, the body of this POST /checkouts/store-credits will contain the amount and upstreamId of the selected store credit, plus a sessionId that uniquely identifies the checkout-session. If you sent upstreamId in the create checkout-session request, we also assign this value to sessionUpstreamId.
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 checks 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.
If it’s true, we use upstreamId and amount to create a source with a type of customerCredit, add it to the checkout-session’s sources[] and then update the experience.
In Prebuilt Checkout, after customers request to apply or remove their store credit, Digital River updates the totals in the order summary section.
If approval is false, Digital River doesn’t create a source. Instead, we display a generic error message to users.
Removing store credit
In the payment stage, customers might also attempt to remove a store credit that's already been successfully applied.
Each time a customer makes this request, Digital River removes that payment option from the checkout-session’s sources[] and then 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. The purpose of this DELETE /checkouts/store-credits/{upstreamId} is to notify you that the customer has opted to remove that payment option.
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.
Processing store credit in orders
If you're offering customers store credit, you should be set up to process it after it's been successfully applied to an order. To do this, configure a webhook to listen for the event with a type of checkout_session.order.created.
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.
Last updated
