Managing sources
Learn how to manage payment sources
In the Digital River API, payment sources fall into two broad categories: primary and secondary.
For both categories, after source creation, you can always attach a source to a checkout so that Digital River can attempt to generate a charge 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 customers 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.
And when building your payment flows, the Digital River object exposes methods for authenticating and updating sources that can be useful in purchase and account management scenarios.
Primary versus secondary sources
When building your payment workflows, you should be aware of the differences between primary and secondary payment sources and how they affect the payment session.
Primary payment sources
Primary payment sources 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 checkout's 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 charge authorization request after you create the order.
Once a checkout contains a primary source, the necessary payment preconditions are met to convert that checkout to an order.
Secondary payment sources
Secondary payment sources are typically used to supplement a primary source.
In the Digital River APIs, secondary sources have a type of customerCredit.
If a checkout only contains secondary sources[], you may be able to successfully create the order, but before doing so, you need to ensure the necessary payment preconditions are met.
Secondary sources do not support reusability. Therefore, they cannot be saved to a customer's account. Rather, they can only be attached to a checkout to create a one-time charge upon order creation.
Creating payment sources
We provide multiple options for creating primary sources and creating secondary sources.
Creating primary 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.
Creating secondary sources
How you create sources with a type of customerCredit depends on the version you're using.
For versions:
2021-03-23and higher, refer to Applying store credit.2020-09-30,2020-12-17, and2021-02-23, refer to Applying store credit (legacy).
Combining primary and secondary payment sources
A checkout's sources[] is able to hold a single primary source and/or one or more secondary sources.
In checkouts, 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 of the above primary payment sources in invoices. Just make sure you turn off billing optimization. For details, refer to supported payment methods with invoices.
When building your workflows, make sure 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.
Also, you should be aware of how Digital River handle captures, cancels, and refunds when an order contains multiple charges[].
Using secondary sources with a single use primary source
If a primary source is created during the checkout process and then not associated with a customer (perhaps because the customer is checking out as a guest, the customer is registered but chooses not to save the source, or the source's type doesn’t support reusability), then you must attach all secondary sources to the checkout before attaching the primary source.
If a checkout's primary sources[] has a reusable value that is false, then any attempt to associate a secondary source with the checkout returns the following error:
Using 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.
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 source's amount.
How we handle captures, cancels, and refunds
When combining secondary sources with a primary source, you should be aware of how Digital River processes captures, cancels, and refunds on an order's charges[].
Captures
Digital River first captures the charge(s) created from secondary sources and then the single charge created from the primary source.
Cancels
Digital River first cancels the single charge created from the primary source and then the charge(s) created from secondary sources.
Refunds
Digital River first refunds the single charge created from the primary source and then the charge(s) created from secondary sources.
Attaching sources to checkouts
After you create or authenticate a payment source and then retrieve its unique identifier, you can use that value to associate the source with a checkout.
You do this by either 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.
Passing a source's identifier in the request body
To associate a payment source with a checkout, you can send its sourceId in the body of a POST /checkouts or POST /checkouts/{id} request.
Passing a source's identifier as a path parameter
To associate a payment source with a checkout, you can pass the checkout's identifier and the source's identifier as path parameters in a POST /checkouts/{id}/sources/{sourceId}.
Detaching sources from checkouts
When you need to remove a payment source from a checkout, you can send a DELETE /checkouts/{id}/sources/{sourceId}. A successful request returns a 204 No Content status code and an empty body.
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:
Saving sources to customers
In some cases, after you create a primary payment source, you can save it to a customer for use in future checkouts.
Attaching sources to customers 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 customer by sending their unique identifiers as path parameters in a POST/customers/{customerId}/sources/{sourceId} request.
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.
Restrictions on saving sources
Prior to sending a save source to customer request, make sure that the source doesn't have any reusability and chargeability restrictions.
Reusability restrictions
If a source doesn't support reusability and you pass its identifier in a POST/customers/{customerId}/sources/{sourceId}, then the following error is returned:
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.
Chargeability restrictions
Only source's whose state is chargeable can successfully be saved to a customer. If the source 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 source can be associated with a customer.
Restrictions on using saved sources
A source saved to a customer can't be used to generate a charge unless you associate the customer with the checkout.
If a customer 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.
Removing sources from customers
If you'd like to detach a payment source saved to a customer, you can send a DELETE/customers/{id}/sources/{sourcesId} request. When you do so, the source's state becomes cancelled and the resource can't be used to create any future charges.
If you attempt to reattach this source to a customer, you'll receive the following error:
Setting the default payment source
Customers can store multiple payment sources[].
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 update customer request.
Authenticating 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.
Updating sources
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.
Last updated