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.
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.
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:
- 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.
curl --location --request POST 'https://api.digitalriver.com/sources' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <Your secret API key>' \
...
--data-raw '{
"type": "customerCredit",
"paymentSessionId": "96e199dc-e9a4-4bb1-86ca-2adc502e62bf",
"amount": 12.50,
"upstreamId": "76-87-1298",
"customerCredit": {
}
}'
Source
{
"id": "f2f6bced-37a0-4b10-965a-7c4f27e59288",
"createdTime": "2022-10-13T19:52:57Z",
"type": "customerCredit",
"currency": "USD",
"amount": 12.5,
"reusable": false,
"state": "chargeable",
"upstreamId": "76-87-1298",
"owner": {
"firstName": "Chase",
"lastName": "Marshall",
"address": {
"line1": "4321 Any Road W",
"city": "Minneapolis",
"postalCode": "55401",
"state": "MN",
"country": "US"
}
},
"paymentSessionId": "96e199dc-e9a4-4bb1-86ca-2adc502e62bf",
"clientSecret": "f2f6bced-37a0-4b10-965a-7c4f27e59288_fba8241d-b0f4-4305-bad4-1ecff4e03d3b",
"customerCredit": {},
"liveMode": false
}
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. curl --location --request POST 'https://api.digitalriver.com/checkouts/e869b46e-dd24-4896-a79e-6ad80bbbd460/sources/f2f6bced-37a0-4b10-965a-7c4f27e59288' \
--header 'Content-Type: application/json' \
--header 'Authorization: <Your secret API key>' \
...
--data-raw ''
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:409 Conflict
{
"type": "conflict",
"errors": [
{
"code": "session_source_amount_too_large",
"message": "Source amount(s) exceed session amount"
}
]
}
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.
In any of these cases, Digital River first computes taxes based on the checkout's
totalAmount
, and then applies the store credit.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
. Order
{
"id": "242764070336",
...
"payment": {
"charges": [
{
"id": "db5f33b5-3b1a-40c7-9e63-0e5b8a7dcad5",
"createdTime": "2022-10-13T19:55:58Z",
"currency": "USD",
"amount": 12.5,
"state": "capturable",
"captured": false,
"refunded": false,
"sourceId": "f2f6bced-37a0-4b10-965a-7c4f27e59288",
"type": "customer_initiated"
},
{
"id": "f30999a2-23c3-46b0-ae35-335f7ddd967b",
"createdTime": "2022-10-13T19:55:57Z",
"currency": "USD",
"amount": 14.51,
"state": "capturable",
"captured": false,
"refunded": false,
"sourceId": "a83ad586-c4ad-4b27-8676-1e0a897cf029",
"type": "customer_initiated"
}
],
"sources": [
{
"id": "a83ad586-c4ad-4b27-8676-1e0a897cf029",
"type": "creditCard",
"amount": 14.51,
"owner": {
"firstName": "Chase",
"lastName": "Marshall",
"email": "[email protected]",
"address": {
"line1": "Any other road W",
"city": "Eagan",
"postalCode": "55122",
"state": "MN",
"country": "US"
}
},
"creditCard": {
"brand": "Visa",
"expirationMonth": 7,
"expirationYear": 2027,
"lastFourDigits": "1111"
}
},
{
"id": "f2f6bced-37a0-4b10-965a-7c4f27e59288",
"type": "customerCredit",
"amount": 12.5,
"upstreamId": "76-87-1298",
"owner": {
"firstName": "Chase",
"lastName": "Marshall",
"address": {
"line1": "4321 Any Road W",
"city": "Minneapolis",
"postalCode": "55401",
"state": "MN",
"country": "US"
}
},
"customerCredit": {}
}
],
"session": {
"id": "96e199dc-e9a4-4bb1-86ca-2adc502e62bf",
"amountContributed": 27.01,
"amountRemainingToBeContributed": 0.0,
"state": "complete",
"clientSecret": "96e199dc-e9a4-4bb1-86ca-2adc502e62bf_57cb6a31-9594-4879-8cbd-740121cd35f7"
}
},
"state": "accepted",
"stateTransitions": {
"accepted": "2022-10-13T19:55:59Z"
},
...
"checkoutId": "e869b46e-dd24-4896-a79e-6ad80bbbd460"
}
Last modified 3mo ago