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 is reusable, 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 checkout, 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 is in the necessary state and the amount contributed is sufficient.

Secondary sources are not re-usable. So, after you create a secondary source, you shouldn't save it to a customer's account. If you do, its reusable value remains false. It 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

You create primary sources with your public API key using Drop-in or DigitalRiver.js. Once the state of the source is chargeable, you should either attach it to a checkout or save it to a customer's account for use in registered checkouts.

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 customer credit through the Checkouts API.

When defining the request, you retrieve the payment session identifier from the checkout you're going to attach the secondary source to. 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 cannot 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
POST/sources request
curl --location --request POST 'https://api.digitalriver.com/sources' \
--header 'Authorization: Bearer <API_key>' \
...
--data-raw '{
"paymentSessionId": "ps_8cecaa32-f692-44cc-b103-4cf24dc93913",
"amount": 2,
"type": "customerCredit",
"owner": {
"firstName": "John",
"lastName": "Doe",
"email": "[email protected]",
"address": {
"line1": "10380 Bren Road West",
"city": "Minnetonka",
"state": "MN",
"country": "US",
"postalCode": "55343"
}
},
"customerCredit": {}
"upstreamId": "7765374748",
}'

A 201 OK response returns a unique source object 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
POST/sources response
{
"id": "99fe8ad1-999e-4e13-95d5-248e472aa7c8",
"createdTime": "2021-02-24T21:59:05Z",
"type": "customerCredit",
"currency": "USD",
"amount": 2.0,
"reusable": false,
"state": "chargeable",
"owner": {
"name": "John Doe",
"email": "[email protected]",
"address": {
"line1": "10380 Bren Road West",
"city": "Minnetonka",
"state": "MN",
"country": "US",
"postalCode": "55343"
}
},
"clientSecret": "99fe8ad1-999e-4e13-95d5-248e472aa7c8_a8c8bbb4-e9da-4cd7-a3c3-3a00272ced18",
"customerCredit": {},
"paymentSessionId": "ps_8cecaa32-f692-44cc-b103-4cf24dc93913",
"upstreamId": "7765374748",
"liveMode": false
}

Combining primary and secondary payment sources

You can use 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, and klarnaCreditRecurring.

When building your workflows, you need to ensure you're properly sequencing the application of primary and secondary sources. This sequence depends on whether you're combining payment sources in guest checkouts or combining them in registered checkouts.

Also, you should be aware of how we handle captures, cancels, and refunds.

Sequencing multiple sources in guest checkouts

In guest checkout scenarios, you must attach all the secondary sources to the checkout before you attach the primary source. Once your workflow adds the primary source, the amount remaining to be contributed drops to zero and the payment session moves into the state necessary to convert the checkout to an order. At this point, if you attempt to attach a secondary source, you'll receive the following error:

409 Conflict
409 Conflict
{
"type": "conflict",
"errors": [
{
"code": "session_update_not_allowed",
"message": "Updating source is not allowed for the current session state."
}
]
}

Sequencing multiple sources in registered checkouts

In registered checkouts (where a primary source is saved to the customer's account), you can attach one or more secondary sources to the checkout in any sequence. We first use the secondary sources to build up the amount contributed. Any amount remaining to be contributed is applied to the customer's default primary source.

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 instrument for a single purchase and not save it to their account. In these cases, after you create a payment source and retrieve is 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 you can pass its identifier as a path parameter. In both operations, once the source is successfully attached, it transitions to a consumed state.

These operations are especially useful when building workflows that allow customers to provide their credit card information during one-off purchases and mail order/telephone order transactions.

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.

You cannot however attach a source to a checkout when that source is already associated with a customer. If you attempt to do this, you receive the following error when you convert the checkout to an order.

409 Conflict
409 Conflict
{
"type": "conflict",
"errors": [
{
"code": "source_in_use",
"parameter": "sourceId",
"message": "Source '37dcb9dc-c1ea-4295-b787-7d872e94cefd' is attached to a different customer."
}
]
}

Additionally, because a source attached to a checkout transitions to a consumed state, if you attempt to attach that same source to a customer or a different checkout, you also get back a 409 Conflict status.

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
cURL
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 the source identifier as a path parameter

You can use the POST/checkouts/{id}/sources/{sourceId} operation to attach a payment source to a checkout. You just need to provide the identifier of both the checkout and source as path parameters.

In the response, the source object you attached is returned in a consumed state.

200 OK
200 OK
{
"id": "6bad6458-95e2-4662-bc34-d08d9189335c",
"createdTime": "2021-02-22T18:41:46Z",
"type": "creditCard",
"currency": "USD",
"amount": 5.0,
"reusable": false,
"state": "consumed",
"owner": {
"firstName": "William",
"lastName": "Brown",
"email": "[email protected]",
"address": {
"line1": "10380 Bren Road West",
"city": "Minnetonka",
"postalCode": "55343",
"state": "MN",
"country": "US"
}
},
"paymentSessionId": "75485429-4856-4d76-9ccc-6a24b4ce5fa2",
"clientSecret": "6bad6458-95e2-4662-bc34-d08d9189335c_56868c23-24f3-4032-a17f-4557092742ed",
"creditCard": {
"brand": "Visa",
"expirationMonth": 7,
"expirationYear": 2027,
"lastFourDigits": "1111"
},
"liveMode": false
}

Detaching sources from checkouts

When you need to remove a payment source from a checkout, you can send aDELETE/checkouts/{id}/sources/{sourceId} request. 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
409 Conflict
{
"type": "conflict",
"errors": [
{
"code": "source_status_invalid_for_session",
"message": "The source status is invalid for this session."
}
]
}

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.

Attaching sources to customers

After you create a primary payment source, you can save it to a customer's account by sending its unique identifier in a POST/customers/{id}/sources/{sourceId} request.

curl --location --request POST 'https://api.digitalriver.com/customers/08161945/sources/7a3ce24c-5e18-4b8d-a667-d64a513ed33f' \
--header 'Authorization: Bearer <API_key> \

Once associated with a registered customer, certain payment sources become reusable. However, you should only attach a source to a customer when it supports re-usability. Otherwise its reusable value remains false and the customer won't be able to apply that payment source to future transactions.

This operation can be useful when building workflows that allow customers to save their credit card information during one-off purchases or within their account portals.

When a source is successfully attached to a customer, your integration receives a customer.source.created event. Once you receive this event, you can update your system and notify customers that the payment method has been saved to their account.

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

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.