Applying store credit (legacy)
Learn how to apply store credit
Last updated
Learn how to apply store credit
Last updated
This page explains how to use store credit in 2020-09-30, 2020-12-17, and 2021-02-23. For versions 2021-03-23 and higher, refer to Applying store credit.
For non-recurring transactions, customers can pay using store credit, a unique payment type that allows you to connect your credit management system to . With store credit, you manage customers' credit on your end and can display the amount available to them during the checkout process.
You create store credit payment sources, and then Digital River attaches the store credit to the checkout.
When funding the transaction, you can use store credit alone or pair it with a primary payment source.
With store credit, the steps necessary to handle fulfillment and request refunds remain the same. However, if an sources[] contain store credit and a primary payment source, you should be aware of how Digital River handles captures, cancels, and refunds.
You create store credit by passing creditAmount in either a s or request. The value you pass represents the store credit amount you're extending to the customer.
You can only send creditAmount once. If the already contains a creditAmount and you pass creditAmount in an , then the following error is thrown:
So, when customers opt to apply multiple lines of credit to the transaction, aggregate that amount and send creditAmount in a single API request.
You can fund a transaction entirely with store credit or pair store credit with a primary payment source. In either case, Digital River first computes taxes based on the checkout's totalAmount, and then applies the store credit.
However, if a checkout's only sources[] has a type of customerCredit, you must set the checkout's billTo. If you don't, you'll receive a 409 Conflict when you submit the create order request.
If you don't do this and you attempt to convert the checkout to an order, you receive the following error:
How you sequence the use of store credit with a primary source depends on whether the latter is single-use or reusable.
If the primary source has a reusable value that's false, you must first create the store credit before attaching the primary source.
When pairing store credit with a primary payment source, you should know the logic Digital River uses to capture charges, cancel charges and process refunds.
But, since not all of the order's items[] are fulfilled, the charge amount created from the creditCard is only partially captured. As a result, that charge's state remains capturable.
After being fulfilled, the client system submitted an order-level refund of 50 percent.
Notice that the credit card is fully refunded. However, the customerCredit is only partially refunded. This means that in any subsequent refund requests, the order's remaining availableToRefundAmount will be issued to the customerCredit.
After you create store credit, Digital River adds a sources[] with a type of customerCredit to the .
A customer can make a purchase entirely with store credit. To do so, a creditAmount must be equal to or greater than its totalAmount before you create the order. In this case, you're not required to pair store credit with a primary payment source.
If a creditAmount is less than its totalAmount, you'll need to associate a primary payment source with the checkout.
If a checkout's sources[] contains customerCredit as well as a primary payment source, you can replace the primary source with a different primary source by sending its sourceId in the payload of a .
If your integration attaches a single-use primary payment source to a checkout, and then attempts to with a creditAmount, you'll receive the following 409 Conflict:
If the primary source has a reusable value that's true, thereby indicating that it's saved to the record, then the sequence doesn't matter. In other words, your workflow can create store credit before or after attaching a primary source to the checkout.
If a only sources[] has a type of customerCredit, then, upon order creation, Digital River uses that source to generate a single .
On the other hand, if you pair store credit with a primary source in a checkout, and then create the , Digital River generates two charges. In the following example, the sources[] with a type of customerCredit is used to generate one of the charges[] and the creditCredit source is used to generate the other.
When you notify Digital River that an order is partially or completely fulfilled, we attempt to the created by the customerCredit source before capturing the charge generated from the primary payment source.
The following example demonstrates this concept. The order contains a single items[] with a quantity of 2 and its totalAmount is 26.89. The order was created with a creditAmount of 11.0 and a supplemental credit card to cover the shortfall. As a result, two objects are contained in its charges[].
So, in this example, when a with a quantity of 1 gets submitted, thereby notifying Digital River of a partial fulfillment, we completely capture the charge amount created from customerCredit and move that charge's to complete.
When you notify us that an order is partially or completely cancelled, we attempt to the created from the primary payment source before cancelling the charge generated from the customerCredit.
The following example demonstrates this concept. The order contains a single items[] with a quantity of 2 and its totalAmount is 20.0. The order was created with a creditAmount of 5.0 and a supplemental credit card to cover the shortfall. As a result, two objects are contained in its charges[].
So, in this example, when a with a cancelQuantity of 1 gets submitted, we partially cancel the charge amount created from the creditCard source. Note that no cancels have been performed yet on the charge generated from the customerCredit.
When you issue a refund on an that uses store credit, the refund is first applied to the primary payment source and then the store credit.
The following example demonstrates this concept. The order was funded with store credit and a supplemental credit card. It was completely fulfilled, meaning both of its were fully and moved into a state.