Offering store credit
Learn how to offer your customers the use of store credit in Prebuilt Checkout
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 customers' credit on your end and then pass that data to Digital River in create checkout-session requests so we can offer it as a payment option in the Prebuilt Checkout.
On this page, you'll find information on:
To more closely manage the store credit you offer to customers and to better defeat fraudulent attempts to abuse it, you can provide a store credit endpoint in Dashboard.
If you want to give customers the option to use store credit in Prebuilt Checkout, then the body of your create checkout-session request must include
storeCredits[]
. After you create the checkout modal, customers might request to use these store credit options during the payment collection stage. Once a store credit has been successfully applied, they might also want remove that payment option.
For details on how to handle these scenarios, refer to Attaching store credit and Removing store credit.
Each time a customer requests to use store credit, Digital River checks whether you have a saved endpoint.

If no endpoint exists, Digital River uses the store credit’s
upStreamId
and amount
to create a source with a type
of customerCredit
, adds it to the checkout-session’s sources[]
, and then updates the order summary totals in the modal.Otherwise, if an endpoint does exist, Digital River sends a store credit authorization request to the url you specified.
At a minimum, the body of this
POST /checkouts/store-credits
request contains the amount
and upstreamId
of the store credit selected by the customer, plus a sessionId
that uniquely identifies the checkout-session. If you sent upstreamId
in the create checkout-session request, Digital River also passes through this value in sessionUpstreamId
.To handle this 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, set
approval
to true
in the response. Make sure you also specify the amount
that's been approved. This value can be lower than the amount
Digital River sent in the request but should be greater than 0
.
Otherwise, if you reject the request, set approval
to false
. In this case, you don't need to return an 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 compare the values for parity. Digital River handles your response by checking the value of
approval
.If it’s
true
, we use upstreamId
and amount
to create a source with a type
of customerCredit
. We then add it to the checkout-session’s sources[]
and update the order summary section.
If
approval
is false
, Digital River doesn’t create a source. Instead, we display a generic error message to users.
In the payment stage, customers may 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[]
, updates the modal's order summary totals and then checks 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 that gets sent to your saved url. The purpose of this DELETE /checkouts/store-credits/{upstreamId}
request is to notify you that the customer has opted to remove that payment option.Your service should reply with a
204 No Content
status code and the body of the response should be empty.If you're offering customers the use of 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 the customer applied store credit to the transaction. For each
payment.sources[]
of this type
, we recommend that you use that object's upstreamId
to look up the line of credit in your system and then deduct how much is available by amount
.{
"id": "bc7c8d7b-c9b6-473c-8de1-1381afcae70a",
"type": "checkout_session.order.created",
"data": {
"object": {
"id": "253375130336",
"checkoutId": "d868418a-1302-4685-8a37-cab789164aea",
"checkoutSessionId": "a5e8133f-d874-4b48-b2c5-88f31d9860eb",
...
"payment": {
...
"sources": [
{
"id": "3848c570-c12c-4383-9588-8d4765a6f753",
"createdTime": "2023-01-24T16:46:20Z",
"type": "customerCredit",
"currency": "USD",
"amount": 11.4,
"reusable": false,
"state": "consumed",
"upstreamId": "7654-2345-0987-123456",
"clientSecret": "3848c570-c12c-4383-9588-8d4765a6f753_56424640-f3e3-43a8-b641-d0c498f88e1d",
"customerCredit": {}
},
{
"id": "57a3df40-86d7-437f-bc9b-4de2e7b2d0d1",
"createdTime": "2023-01-24T16:47:07Z",
"type": "creditCard",
"currency": "USD",
"amount": 53.99,
"reusable": false,
"state": "consumed",
"owner": {
"firstName": "John",
"lastName": "Smith",
"email": "[email protected]",
"address": {
"line1": "10380 Bren Rd W",
"city": "Minnetonka",
"postalCode": "55129",
"state": "MN",
"country": "US"
},
"organization": "Digital River",
"additionalAddressInfo": {
"neighborhood": "Centro",
"phoneticFirstName": "ヤマダ",
"phoneticLastName": "タロ",
"division": "営業部"
}
},
"paymentSessionId": "0afec58c-1f3a-4082-a0ad-86736a904ad7",
"clientSecret": "57a3df40-86d7-437f-bc9b-4de2e7b2d0d1_443ca230-4330-4f0c-9b6a-3ea288362227",
"creditCard": {
"brand": "MasterCard",
"expirationMonth": 12,
"expirationYear": 2023,
"lastFourDigits": "0008",
"fundingSource": "credit"
}
}
],
...
},
...
}
},
...
}