Managing sources
Learn how to manage payment sources
Last updated
Learn how to manage payment sources
Last updated
In the Digital River API, payment sources fall into two broad categories: primary and secondary.
For both categories, after creating a source, you can always attach a source to a checkout so that Digital River can attempt to generate a after you create the order. You can also detach sources from checkouts.
If a primary source supports reusability, you may also be able to save it to a customer's account. For with multiple sources[], we also provide you the ability to set the default one.
You can combine primary and secondary sources, but how you sequence their application depends on whether or not the primary source is reusable.
When building payment flows, the Digital River object exposes methods for authenticating and updating sources useful in the purchase and account management scenarios.
When building your payment workflows, you should know the differences between primary and secondary payment sources and how they affect the payment session.
Primary payment are created from traditional payment methods such as credit cards, Google Pay, PayPal, and wire transfers. Most customers use a primary source when making a purchase, but a sources[]can only contain one primary source.
Primary sources created from payment methods that support reusability may be able to be associated with a customer and then reused in future transactions.
Alternatively, you can simply attach a primary source to a checkout, thereby enabling Digital River to submit a after you create the order.
Once a contains a primary source, the necessary payment preconditions are met to convert that checkout to an order.
Secondary payment are typically used to supplement a primary source.
In the Digital River APIs, secondary sources have a type of customerCredit.
We provide multiple options for creating primary sources and creating secondary sources.
Primary sources are created with your public API key using Drop-in payments or DigitalRiver.js with elements. Once created, you can attach the source to a checkout or, in some cases, save the source to a customer.
For versions:
2021-03-23 and higher, refer to Applying store credit.
2020-09-30, 2020-12-17, and 2021-02-23, refer to Applying store credit (legacy).
When building your workflows, ensure you're properly sequencing the application of primary and secondary sources. The sequence depends on whether you use secondary sources with a single-use primary source or secondary sources with a saved primary source.
If a checkout's primary sources[] is saved to the customer making the purchase, then you have more flexibility in how you sequence the application of primary and secondary sources.
You do this by sending the source's identifier in the request's payload or passing its identifier as a path parameter. This is true for both primary and secondary sources.
You're only allowed to associate one primary source with a checkout. If a checkout's sources[] contains a primary source, and you submit a request to attach a different primary source, using either the payload or path parameter approach, then the existing source is replaced.
However, as long as the aggregated amount of all of a checkout's sources[] doesn't exceed the checkout's totalAmount, there's no limit to the number of secondary sources you can attach to a checkout.
If the source's reusable value is false when you submit the detach request, then the source's state transitions to cancelled, and any attempt to reattach the source to a checkout returns the following error:
In some cases, after you create a primary payment source, you can save it to a customer for use in future checkouts.
A successful request flips the source's reusable value to true and returns the source.
At this point, you can update your system and notify customers that the payment method has been saved to their account.
For a list of payment methods that can be used in recurring transactions, refer to the Supported payment methods page.
With Drop-in payments, you can also use supportsStorage in the onSuccess event's data to make this determination.
If you attempt to reattach this source to a customer, you'll receive the following error:
Customers can store multiple payment sources[].
After you retrieve a source, you can pass its identifier, payment session identifier, and client secret to the authenticate source method in the DigitalRiver.js library. This operation is especially helpful when building workflows that allow customers to retrieve saved credit card information during one-off purchases or subscription acquisitions.
After you retrieve a source, you can pass its identifier, payment session identifier, and client secret to the update source method in the DigitalRiver.js library. This operation is useful when building workflows that allow customers to update a credit card's expiration date or billing address.
If a only contains secondary sources[], you may be able to successfully create the order, but before doing so, you must ensure the necessary payment preconditions are met.
Secondary sources do not support reusability. Therefore, they cannot be saved to a customer's account. They can only be attached to a checkout to create a one-time upon creation.
A sources[] can hold a single primary source and/or one or more secondary sources.
In , you can combine a secondary source with any primary source that has one of the following type values: alipayCn, creditCard, googlePay, applePay, payPal, payPalCredit, payPalBilling, wireTransfer, klarnaCredit, klarnaCreditRecurring, alipay, konbini, directDebit and onlineBanking.
You can also use secondary sources with any primary payment sources in . Just make sure you turn off . For details, refer to .
Also, you should be aware of how Digital River handle captures, cancels, and refunds when an contains multiple .
If a primary source is created during the checkout process and then not (perhaps because the customer is checking out as a guest, the customer is registered but chooses not to save the , or the source's type doesn’t support reusability), you must attach all secondary sources to the before attaching the primary source.
If a primary sources[] has a reusable value that is false, then any attempt to associate a secondary source with the checkout returns the following error:
More specifically, if a checkout's primary sources[] has a reusable value of true, then you can request to associate a secondary source with the checkout. Each time this request is successfully submitted, the checkout's primary sources[].amount gets reduced by the secondary amount.
When combining secondary sources with a primary source, you should be aware of how Digital River processes captures, cancels, and refunds on an charges[].
Digital River first the created from secondary sources and then the single charge from the primary source.
Digital River first the single created from the primary source and then the charge(s) created from secondary sources.
Digital River first the single created from the primary source and then the charge(s) created from secondary sources.
After you create or authenticate a payment and retrieve its unique identifier, you can use that value to associate the source with a .
To associate a payment with a , you can send its sourceId in the body of a or request.
To associate a payment source with a , you can pass the checkout's identifier and the source's identifier as path parameters in a .
When you need to remove a payment source from a checkout, you can send a . A successful request returns a 204 No Content status code and an empty body.
Attaching to can be useful when building workflows that allow customers to save their payment information during one-off purchases, subscription acquisitions, or on account management pages.
As long as the necessary preconditions are satisfied, you can save a primary source to a by sending their unique identifiers as path parameters in a request.
Before sending a save source to customer request, make sure that the doesn't have any reusability and chargeability restrictions.
If a doesn't support reusability and you pass its identifier in a , then the following error is returned:
Only whose state is chargeable can successfully be saved to a . If the isn't chargeable (perhaps because it has a redirect payment flow, the customer has yet to successfully authorize payment, and, as a result, its state is still pending_redirect), and you attempt to save the source to a customer, you'll receive the following error:
With Drop-in payments, you can use readyForStorage in the onSuccess event's data to determine whether a can be associated with a .
A saved to a can't be used to unless you associate the with the .
If a has a saved sources[], and you associate that source with the checkout but neglect to associate that customer with the checkout, you'll receive the following error when you convert the checkout to an order.
If you'd like to detach a payment saved to a customer, you can send a request. When you do so, the source's state becomes cancelled and the resource can't be used to .
The first source you attach to a customer automatically becomes its default, and its identifier is assigned to the customer's defaultSourceId attribute. If you'd like to assign a customer a different default payment source, you must first ensure it's attached to the customer. Once that's done, you can set its identifier as the defaultSourceId in an .