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 creating a source, 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.

When building payment flows, the Digital River object exposes methods for authenticating and updating sources useful in the purchase and account management scenarios.

Primary versus secondary sources

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 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 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 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-23 and higher, refer to Applying store credit.

• 2020-09-30, 2020-12-17, and 2021-02-23, refer to Applying store credit (legacy).

Combining primary and secondary payment sources

A checkout's sources[] can 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 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, 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 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), 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 charges created from secondary sources and then the single charge 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 retrieve its unique identifier, you can use that value to associate the source with a checkout.

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.

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

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