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"
}
}
],
...
},
...
}
},
...
}