Links

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 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

Creating secondary sources

How you create sources with a type of customerCredit depends on the version you're using.
For versions:

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, bPay, directDebit and onlineBanking.
In invoices, you can also use secondary sources with any of the above primary payment sources. 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:
409 Conflict
{
"type": "conflict",
"errors": [
{
"code": "session_update_not_allowed",
"message": "Updating source is not allowed for the current session state."
}
]
}

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'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.
curl --location --request POST 'https://api.digitalriver.com/checkouts/177642590336' \
--header 'Authorization: <API_key>' \
--header 'Content-Type: text/plain' \
--data-raw '{
"sourceId": "7a3ce24c-5e18-4b8d-a667-d64a513ed33f"
}'

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:
409 Conflict
{
"type": "conflict",
"errors": [
{
"code": "source_status_invalid_for_session",
"message": "The source status is invalid for this session."
}
]
}

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.
curl --location --request POST 'https://api.digitalriver.com/customers/544671250336/sources/05642ad9-d227-4250-a73e-92514ef68620' \
...
--data-raw ''
A successful request flips the source's reusable value to true and returns the source.
200 OK
{
"id": "05642ad9-d227-4250-a73e-92514ef68620",
"createdTime": "2021-09-16T14:29:45Z",
"type": "creditCard",
"reusable": true,
"state": "chargeable",
"customerId": "544671250336",
"owner": {
...
},
"clientSecret": "05642ad9-d227-4250-a73e-92514ef68620_be853d8e-0422-436e-af3e-45f8a92b25e9",
"creditCard": {
"brand": "Visa",
"expirationMonth": 7,
"expirationYear": 2027,
"lastFourDigits": "1111"
},
"liveMode": false
}
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:
409 Conflict
{
"type": "conflict",
"errors": [
{
"code": "nonreusable_source",
"message": "Only a reusable source may be attached to a customer."
}
]
}
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:
409 Conflict
{
"type": "conflict",
"errors": [
{
"code": "source_not_chargeable",
"parameter": "sourceId",
"message": "Source 'ea6b3297-d05f-4d5d-a12d-95234e93d450' is not chargeable."
}
]
}
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.
409 Conflict
{
"type": "conflict",
"errors": [
{
"code": "source_in_use",
"parameter": "sourceId",
"message": "Source '37dcb9dc-c1ea-4295-b787-7d872e94cefd' is attached to a different customer."
}
]
}

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:
409 Conflict
{
"type": "conflict",
"errors": [
{
"code": "source_not_chargeable",
"parameter": "sourceId",
"message": "Source '24f4f281-9613-4d6d-8831-808952ed4915' is not chargeable."
}
]
}

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 then 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.