Managing sources
Learn how to manage payment sources
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.
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 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.
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.
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.
For versions:
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[].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."
}
]
}
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.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[].Digital River first captures the charge(s) created from secondary sources and then the single charge created from the primary source.
Digital River first cancels the single charge created from the primary source and then the charge(s) created from secondary sources.
Digital River first refunds the single charge created from the primary source and then the charge(s) created from secondary sources.
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. 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"
}'
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}. 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."
}
]
}
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 ''
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.
Prior to sending a save source to customer request, make sure that the source doesn't have any reusability and chargeability 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. 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. 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."
}
]
}
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."
}
]
}
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.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.
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 16d ago