Managing sources
Learn how to manage payment sources.
In the Digital River API, there are two broad categories of payment sources: primary and secondary.
For both categories, after you create a payment source, you can always attach it to a checkout or invoice so that we can use it to generate a one-time charge. You can also detach sources from checkouts.
Once you create a primary source that supports reusability, you can save it to a customer's account and then, if necessary, remove it at a later time. For customers who have multiple saved payment sources, we also provide you the ability to set the default one.
You can combine primary and secondary sources, but how you sequence them depends on whether they're being used in guest or registered checkouts.
And when building your payment flows, the DigitalRiver.js library contains 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. Nearly all transactions are conducted with a primary source, but each order can only contain one. Once you create them and then attach them to a customer, primary sources can be re-used in future transactions (assuming the underlying payment method supports reusability). You can also attach them to a checkout so we can use them to create a one-time charge.
Once they are successfully associated with a transaction, primary sources move the payment session into the necessary state and fully fund the transaction.

Secondary payment sources

Secondary payment sources are typically used to supplement a primary source. Unlike primary sources, an order can contain an unlimited number of secondary sources.
In the Digital River API, customerCredit is currently the only type of supported secondary source.
You can successfully submit an order entirely with secondary sources, but you need to ensure the payment session state is valid and the amount contributed is sufficient.
Secondary sources do not support reusability. Therefore, they cannot be saved to a customer's account. They should only be attached to a checkout to create a one-time charge when that checkout is converted to an order.

Creating payment sources

We provide multiple options for creating primary sources and creating secondary sources.

Creating primary sources

Creating secondary sources

You create secondary sources through the Sources API by sending your confidential API key in a POST/sources request.
In versions 2020-09-30, 2020-12-17 and 2021-02-23, you can also create secondary sources using the Checkouts API.
When defining the request, you retrieve the payment session identifier from the checkout you're building. The amount is optional, except when the type is customerCredit. The type is required and we currently only support customerCredit. You must also send an empty hash table whose name matches the type.
The owner hash table is optional and can be used to meet our billing address requirements. The upstreamId parameter is useful for mapping the source to your credit management system.
POST/sources request
1
curl --location --request POST 'https://api.digitalriver.com/sources' \
2
--header 'Authorization: Bearer <API_key>' \
3
...
4
--data-raw '{
5
"paymentSessionId": "ps_8cecaa32-f692-44cc-b103-4cf24dc93913",
6
"amount": 2,
7
"type": "customerCredit",
8
"owner": {
9
"firstName": "John",
10
"lastName": "Doe",
11
"email": "[email protected]",
12
"address": {
13
"line1": "10380 Bren Road West",
14
"city": "Minnetonka",
15
"state": "MN",
16
"country": "US",
17
"postalCode": "55343"
18
}
19
},
20
"customerCredit": {}
21
"upstreamId": "7765374748",
22
}'
Copied!
A 201 OK response returns a unique source in a chargeable state. You should attach it to a checkout so that we can use it to generate a one-time charge.
POST/sources response
1
{
2
"id": "99fe8ad1-999e-4e13-95d5-248e472aa7c8",
3
"createdTime": "2021-02-24T21:59:05Z",
4
"type": "customerCredit",
5
"currency": "USD",
6
"amount": 2.0,
7
"reusable": false,
8
"state": "chargeable",
9
"owner": {
10
"name": "John Doe",
11
"email": "[email protected]",
12
"address": {
13
"line1": "10380 Bren Road West",
14
"city": "Minnetonka",
15
"state": "MN",
16
"country": "US",
17
"postalCode": "55343"
18
}
19
},
20
"clientSecret": "99fe8ad1-999e-4e13-95d5-248e472aa7c8_a8c8bbb4-e9da-4cd7-a3c3-3a00272ced18",
21
"customerCredit": {},
22
"paymentSessionId": "ps_8cecaa32-f692-44cc-b103-4cf24dc93913",
23
"upstreamId": "7765374748",
24
"liveMode": false
25
}
Copied!

Combining primary and secondary payment sources

You can associate a primary payment source with one or more secondary payment sources.
In the Checkouts API, the following types of primary sources are currently supported for use with customerCredit (the only secondary source we currently support): creditCard, googlePay, applePay, payPal, payPalCredit, payPalBilling, wireTransfer, klarnaCredit, klarnaCreditRecurring, alipay, konbini, bPay, directDebit and onlineBanking.
In the Invoices API, you can also use customerCredit with any of the above primary payment sources. Just make sure you turn off billing optimization.
When building your workflows, you need to 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.
Also, you should be aware of how we handle captures, cancels, and refunds when multiple sources are applied to a transaction.

Using secondary sources with a single use primary source

If a primary payment source is created during the checkout process and then not saved to the customer’s record (perhaps because the customer is checking out as a guest, the customer is registered but chooses not to save the source, or the payment method used to create the source doesn’t support reusability), then you must attach all the secondary sources to the checkout before attaching the primary source.
Once the checkout contains a single-use primary source, any attempt to attach additional secondary sources to the checkout returns a 409 Conflict with an error code of session_update_not_allowed.

Using secondary sources with a saved primary source

You have more flexibility to sequence the combination of primary and secondary sources when the primary source is saved to the customer’s record. In this case, you can attach one or more secondary sources to the checkout in any sequence.
Below are some scenarios that involve combining secondary sources with a saved primary source. In these scenarios, the saved source can refer to a primary source created during the current checkout process, saved to the customer’s record, and then attached to the checkout. Alternatively, it may refer to a source created during an earlier process, retrieved from the customer’s record during the current checkout process, and then attached to the checkout.

Scenario 1

A registered customer builds a cart and then decides to fully fund the transaction with a saved credit card. Later in the checkout process, the customer decides to apply a secondary source to the purchase.
Back-end: When the checkout’s sources array only contains a saved primary source, then the checkout’s payment.session.state will typically be requires_confirmation and the payment.sesssion.amountRemainingToBeContributed will be 0.
At this point, however, you can still create a secondary source and submit a request that attaches the source to the checkout.
Each time you submit this request, the primary source’s amount gets reduced by the amount of the secondary source.

Scenario 2

A registered customer builds a cart and then partially funds the transaction with multiple secondary sources. Later in the checkout process, the customer applies a saved credit card to make up the difference.
Back-end: In this scenario, the checkout’s sources array will initially only contain secondary sources, payment.session.state will be requires_source and payment.sesssion.amountRemainingToBeContributed will be greater than 0.
When the customer selects a saved source, you can retrieve that primary source from the customer and submit a request that attaches the source to the checkout. Once you submit this request, we use the amount remaining to be contributed on the payment session to set the primary source’s amount, and the checkout’s payment.session.state becomes requires_confirmation.

How we handle captures, cancels, and refunds

When combining secondary payment sources with a primary payment source, you should be aware of how we process captures, cancels, and refunds.

Captures

We fully capture the charges created from secondary sources before attempting to capture the charge created from the primary source.

Cancels

We fully cancel the charge created from the primary source before cancelling the charges created from secondary sources.

Refunds

We fully refund the charge created from the primary source before refunding the charges created from secondary sources.

Attaching sources to checkouts

Your storefront may be configured to allow guest checkouts. Alternatively, registered customers may opt to use a payment method for a single purchase and not save it to their account. In these cases, after you create a payment source and retrieve its unique identifier, you can then use that value to attach the source to a checkout.
There are two methods for attaching a source to a checkout. These methods work for both primary and secondary sources. You can either send the source identifier in the request payload or pass its identifier as a path parameter.
These operations are useful when building your payment workflows. However, in both operations, unless you first save the source to a customer's account, once it's attached to a checkout, it transitions to a consumed state. If you then attempt to save that source to a customer's account or a different checkout, a 409 Conflict status code is returned.
You can only associate one primary source with a checkout. If there's a primary source in the sources array of a checkout and you attempt to attach a different primary source, using either the payload or path parameter approach, then the existing source is replaced.
There is no limit however on the number of secondary sources you can attach to a checkout. If you send a secondary source in the payload or as a path parameter, we simply append it to the checkout's sources array.

Sending a source identifier in the request payload

You can send a payment source identifier in the payload of a POST/checkouts, POST/checkouts/{id}, or POST/invoices request.
cURL
1
curl --location --request POST 'https://api.digitalriver.com/checkouts/177642590336' \
2
--header 'Authorization: <API_key>' \
3
--header 'Content-Type: text/plain' \
4
--data-raw '{
5
"sourceId": "7a3ce24c-5e18-4b8d-a667-d64a513ed33f"
6
}'
Copied!

Passing the source identifier as a path parameter

You can use the POST/checkouts/{id}/sources/{sourceId} operation to attach a payment source to a transaction. You just need to provide the identifier of both the checkout and source as path parameters.
Unless the source has been saved to a customer's account, both of these operations move the source into a consumed state.
200 OK
1
{
2
"id": "6bad6458-95e2-4662-bc34-d08d9189335c",
3
"createdTime": "2021-02-22T18:41:46Z",
4
"type": "creditCard",
5
"currency": "USD",
6
"amount": 5.0,
7
"reusable": false,
8
"state": "consumed",
9
"owner": {
10
"firstName": "William",
11
"lastName": "Brown",
12
"email": "[email protected]",
13
"address": {
14
"line1": "10380 Bren Road West",
15
"city": "Minnetonka",
16
"postalCode": "55343",
17
"state": "MN",
18
"country": "US"
19
}
20
},
21
"paymentSessionId": "75485429-4856-4d76-9ccc-6a24b4ce5fa2",
22
"clientSecret": "6bad6458-95e2-4662-bc34-d08d9189335c_56868c23-24f3-4032-a17f-4557092742ed",
23
"creditCard": {
24
"brand": "Visa",
25
"expirationMonth": 7,
26
"expirationYear": 2027,
27
"lastFourDigits": "1111"
28
},
29
"liveMode": false
30
}
Copied!

Detaching sources from checkouts

When you need to remove a payment source from a transaction, you can send a DELETE/checkouts/{id}/sources/{sourceId}. A successful request returns a 204 No Content status code and the state of the source transitions to cancelled. If you attempt to reattach this source to a checkout, you'll receive a 409 Conflictstatus:
409 Conflict
1
{
2
"type": "conflict",
3
"errors": [
4
{
5
"code": "source_status_invalid_for_session",
6
"message": "The source status is invalid for this session."
7
}
8
]
9
}
Copied!
In this scenario, if you'd like to use this specific payment instrument in a checkout, you'll have to reacquire the customer's payment information and create another source.

Saving sources to customers

After you create a primary payment source that supports reusability, you can save it to a customer's record for use in future transactions. However, you're not allowed to save non-reusable or non-chargeable sources to a customer.
For a list of payment methods that support reusability, refer to the Supported payment methods section on the Drop-in page.
To save a source to a customer, send their unique identifiers as path parameters in a POST/customers/{customerId}/sources/{sourceId} request.
1
curl --location --request POST 'https://api.digitalriver.com/customers/544671250336/sources/05642ad9-d227-4250-a73e-92514ef68620' \
2
...
3
--data-raw ''
Copied!
A successful request flips the source's reusable value to true and returns the source. When you receive a 200 OK or a customer.source.created event, update your system and notify customers that the payment method has been added to their account.
200 OK
1
{
2
"id": "05642ad9-d227-4250-a73e-92514ef68620",
3
"createdTime": "2021-09-16T14:29:45Z",
4
"type": "creditCard",
5
"reusable": true,
6
"state": "chargeable",
7
"customerId": "544671250336",
8
"owner": {
9
...
10
},
11
"clientSecret": "05642ad9-d227-4250-a73e-92514ef68620_be853d8e-0422-436e-af3e-45f8a92b25e9",
12
"creditCard": {
13
"brand": "Visa",
14
"expirationMonth": 7,
15
"expirationYear": 2027,
16
"lastFourDigits": "1111"
17
},
18
"liveMode": false
19
}
Copied!

Restrictions on saving sources

When you attempt to save a source to a customer, we place restrictions on reusability and chargeability.

Reusability restrictions

If you submit a POST/customers/{customerId}/sources/{sourceId} request and the source doesn't support reusability, then a 409 Conflict is returned:
Secondary sources do not support reusability and should not be saved to a customer's record.
409 Conflict
1
{
2
"type": "conflict",
3
"errors": [
4
{
5
"code": "nonreusable_source",
6
"message": "Only a reusable source may be attached to a customer."
7
}
8
]
9
}
Copied!
You can avoid this error by verifying certain values at the time of source creation. Once the primary source creation method is successfully invoked, use the response to verify that readyForStorage and supportsStorage are both true. If this is the case, you can safely save the source to the customer.

Chargeability restrictions

Only chargeable sources can be saved to a customer. If the source is not chargeable (perhaps because it has a redirect payment type and the customer has yet to successfully authorize a charge), and you attempt to save the source to a customer, you'll receive a 409 Conflict whose error's code is source_not_chargeable.

Restrictions on using saved sources

Saved payment sources can't be used to fund a transaction unless the customer is also associated with that transaction. For example, if a source is saved to a customer, and then you attach that same source to a checkout, but don't associate the customer with the checkout, you receive the following error when you convert the checkout to an order.
409 Conflict
1
{
2
"type": "conflict",
3
"errors": [
4
{
5
"code": "source_in_use",
6
"parameter": "sourceId",
7
"message": "Source '37dcb9dc-c1ea-4295-b787-7d872e94cefd' is attached to a different customer."
8
}
9
]
10
}
Copied!

Using the save sources feature

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.

Removing sources from customers

If you'd like to detach a payment source saved to a customer's account, you can use a DELETE/customers/{id}/sources/{sourcesId} request. When you do so, the state of the source switches to cancelled and it cannot be used to create any future charges.
If you attempt to reattach this source to a customer, you'll receive the following 409 Conflict response:
409 Conflict
1
{
2
"type": "conflict",
3
"errors": [
4
{
5
"code": "source_not_chargeable",
6
"parameter": "sourceId",
7
"message": "Source '24f4f281-9613-4d6d-8831-808952ed4915' is not chargeable."
8
}
9
]
10
}
Copied!
In this scenario, if you'd like to use this specific payment instrument in a checkout, you'll have to reacquire the customer's payment information and create another source.

Setting the default payment source

Registered customers can have multiple payment sources saved to their account. These payment sources are stored in the customer's sources array.
The first source you attach to a customer automatically becomes the default and its identifier is assigned to the 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.
Last modified 1mo ago