# Applying store credit {% hint style="warning" %} This page explains how to use store credit in [versions](https://app.gitbook.com/s/ZrhMyLX5esFYS64lNWVW/digital-river-api-reference-guide/versioning) `2021-03-23` and higher. For versions `2020-09-30`, `2020-12-17`, and `2021-02-23`, refer to [Applying store credit (legacy)](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/applying-store-credit-legacy). {% endhint %} 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. {% hint style="info" %} Therefore, store credit is a [single-use payment source](https://docs.digitalriver.com/digital-river-api/payments/payment-sources#reusable-or-single-use) that can't be saved to a [customer's ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/customers)record. {% endhint %} You[ create the store credit payment source](#creating-store-credit) and then [attach the resource to the checkout](#attaching-store-credit-to-checkouts). Once the [order ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders)is created, you must also [search for store credit and deduct its amount](#handling-store-credit-in-orders). With store credit, the steps necessary to [handle fulfillments](https://docs.digitalriver.com/digital-river-api/order-management/fulfillments) and [request refunds](https://docs.digitalriver.com/digital-river-api/order-management/returns-and-refunds-1/refunds/issuing-refunds) remain the same, but, if an [order's ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders)`sources[]` contain store credit and a [primary payment source](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/using-the-source-identifier#primary-payment-sources), you should know how [Digital River handles captures, cancels, and refunds](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/using-the-source-identifier#how-we-handle-captures-cancels-and-refunds). {% hint style="info" %} Digital River API does not currently support Amazon Pay with store credit. {% endhint %} ## Creating store credit When customers opt to pay with store credit and they've specified an allowable amount, send your [confidential API key](https://docs.digitalriver.com/digital-river-api/administration/dashboard/developers/api-keys#standard-keys) in a [`POST /sources`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/sources#sources). When defining the request: * Retrieve the [checkout's](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts) [`payment.session.id`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/..#payment-session-identifier) and use it to set `paymentSessionId`. * Pass the `amount` of credit you're extending the customer. * Set `type` to `customerCredit`. * Use `upstreamId` to pass the identifier of the line of credit in your system. * Send an empty `customerCredit` object. {% hint style="info" %} An `owner` hash table is optional and can be used to meet [our billing address requirements](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/providing-address-information#billing-address-requirements). {% endhint %} ``` curl --location --request POST 'https://api.digitalriver.com/sources' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ' \ ... --data-raw '{ "type": "customerCredit", "paymentSessionId": "96e199dc-e9a4-4bb1-86ca-2adc502e62bf", "amount": 12.50, "upstreamId": "76-87-1298", "customerCredit": { } }' ``` A response with a `201 OK` status code contains a unique [source ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/sources)with a `type` of `customerCredit` whose [`state`](https://docs.digitalriver.com/digital-river-api/payments/payment-sources#source-state) is `chargeable`. {% hint style="info" %} If you pass `paymentSessionId` and set the checkout's [`billTo`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/providing-address-information#billing-address-requirements) before sending the create source request, Digital River retrieves that data and uses it to populate the source's `owner`. We also retrieve the checkout's [`currency`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/selecting-a-currency) and use it to set the source's `currency`. {% endhint %} {% tabs %} {% tab title="Source" %} ```javascript { "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 } ``` {% endtab %} {% endtabs %} ## Attaching store credit to checkouts After you [create a store credit payment source](#creating-store-credit), you'll need to retrieve its `id` and use that value to [associate the source with the checkout](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/using-the-source-identifier#attaching-sources-to-checkouts). ``` 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: ' \ ... --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`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/payment-sessions#amount-contributed-and-amount-remaining-to-be-contributed). If that's *not* the case, then the following error is thrown: {% code title="409 Conflict" %} ```json { "type": "conflict", "errors": [ { "code": "session_source_amount_too_large", "message": "Source amount(s) exceed session amount" } ] } ``` {% endcode %} 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](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/using-the-source-identifier#primary-payment-sources), or (3) combining store credit with a [reusable](https://docs.digitalriver.com/digital-river-api/payments/payment-sources#reusable-or-single-use) primary payment source. {% hint style="info" %} For details, refer to [Combining primary and secondary sources](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/using-the-source-identifier#combining-primary-and-secondary-payment-sources) on the [Managing sources](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/using-the-source-identifier) page. {% endhint %} In any of these cases, Digital River first computes taxes based on the checkout's `totalAmount`, and then applies the store credit. ## Handling store credit in orders After the [necessary payment preconditions](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/payment-sessions#how-to-determine-when-to-create-an-order) are met to successfully [convert the checkout to an order](https://docs.digitalriver.com/digital-river-api/order-management/creating-and-updating-an-order#creating-an-order-with-the-checkout-identifier), and the [order's ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders)`state` is [`accepted`](https://docs.digitalriver.com/digital-river-api/order-management/creating-and-updating-an-order#handling-accepted-orders), 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`. {% tabs %} {% tab title="Order" %} ```javascript { "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": "marshallsBillingEmail@digitalriver.com", "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" } ``` {% endtab %} {% endtabs %}