Building payment workflows
Learn how to create SCA-compliant workflows using Drop-in Payments and DigitalRiver.js with elements.
You can create Strong Customer Authentication (SCA) compliant workflows for both purchase transactions and customer account management.
For all the workflows that use Drop-in Payments, you'll first need to perform some common, initial steps before proceeding to the workflow's specific steps. For workflows using DigitalRiver.js with elements, to complete some prerequisites.
Whether you are using Drop-in Payments or DigitalRiver.js with elements, any SCA requirements are automatically managed by Digital River. Two-factor authentication is handled by our authenticate source method. And our card acquirers use the 3-D Secure protocol to communicate with issuing banks. This protocol operates "behind-the-scenes" and requires no developer interaction.
Note the following limitations and constraints when building your payments workflow.
- Do not change the currency when there is a secondary source in the cart. Specify the correct currency when creating a secondary payment source. After you apply the secondary source to the cart, do not change the currency. If you change the currency when calling /v1/shoppers, a
409 Conflict
response contains specific information about what triggered the failure. In this instance, one of the currencies in the cart is not supported.
{
"errors": {
"error": [
{
"relation": "https://developers.digitalriver.com/v1/shoppers/ShoppersResource",
"code": "invalid-request",
"description": "One or more sources in the cart does not support locale {Locale} and currency {Currency}."
}
]
}
}
- At this time, you cannot use store credit to purchase a subscription product.
- At this time, you cannot use store credit to pre-order a product.
- At this time, you cannot use store credit to purchase a product on backorder.
- At this time, you cannot attach more than one store credit source to an order. Multiple secondary sources are not supported.
For any workflow that uses Drop-in Payments, whether it's a purchase or account management flow, you'll first need to perform the following steps.
Once you've completed these steps, you can move on to the steps specific to your workflow scenario.
When using DigitalRiver.js with elements to support SCA, you'll need to be using payment sessions, so ensure you've completed the necessary migration. We also assume you are familiar with creating and styling elements as well as the basics of capturing payment details.
Once you've completed these prerequisites, you can perform the steps specific to your desired purchase or account management scenario.
For almost all one-off, subscription, and mail-order/telephone-order (MOTO) transaction scenarios, Digital River supports SCA-compliant workflows that use either Drop-in Payments or DigitalRiver.js elements.
In this flow, s enter their credit card information during the checkout process.
SCA required? | Drop-in Payments supported? | Elements supported? |
---|---|---|
Yes | Yes | Yes |
The following demonstrates how to build a workflow for this scenario using both Drop-in Payments and Elements. We also provide a demo.
Drop-in Payments
DigitalRiver.js with elements
Step two: Retrieve the payment session identifier from the cart, and use it to create an instance of a configuration object. In the configuration
options
, set flow
to checkout
and usage
to convenience
.let configuration = {
sessionId: "d3941a36-6821-4d93-be23-6190226ae5f7",
options: {
flow: "checkout",
usage: "convenience"
}
...
}
let dropin = digitalriver.createDropin(configuration);
Drop-in Payments renders in the specified container.

If the customers completes the SCA steps necessary to make the source chargeable, then the
onSuccess
method is called and Digital River returns a unique Source in a chargeable state....
onSuccess: function (data) { doSometingWithTheSource(data) },
...
A chargeable source is returned.
Step five: Attach the source to the cart.
Step six: Create the order by submitting the cart.
Step one: Create a cart with all tax, shipping, duty, and fee amounts in a final state.
let payload = {
"sessionId": "ea03bf6f-84ef-4993-b1e7-b7d5ecf71d1f",
"futureUse": false,
"usage": "convenience",
...
}
digitalriver.createSource(payload).then(function(result) {
if(result.state === "chargeable") {
sendToBackEnd(result);
} else {
doErrorScenario();
}
});
Once the shopper provides the required SCA, a chargeable source is returned.
Step four: Create the order by submitting the cart.
In this flow, customers enter credit card information and save it to their account during a one-off transaction.
SCA required? | Drop-in Payments supported? | Elements supported? |
---|---|---|
Yes | Yes | Yes |
The following demonstrates how to build workflows for this scenario using both Drop-in Payments and Elements. We also provide a demo.
Drop-in Payments
DigitalRiver.js with elements
Step one: Create a cart with all tax, shipping, duty, and fee amounts in a final state.
Step two: Retrieve the payment session identifier from the cart, and use it to create an instance of a configuration object. In the configuration
options
, set flow
to checkout
and usage
to convenience.
To prompt Drop-in payments to display the save payment option, set showSavePaymentAgreement
to true
.You should also configure the
usage
parameter. Doing so identifies the future use of the payment source. let configuration = {
sessionId: "d3941a36-6821-4d93-be23-6190226ae5f7",
options: {
"showSavePaymentAgreement": true,
"usage": "subscription"
},
...
}
let dropin = digitalriver.createDropIn(configuration);
let dropin = digitalriver.createDropIn(configuration);
Drop-in renders in the specified container.

Customers enter their credit card information, select the save account and payment information option and click the configurable Pay Now button.
If the customers completes the SCA steps necessary to make the source chargeable, then the
onSuccess
method is called and Digital River returns a unique Source in a chargeable state....
onSuccess: function (data) { doSometingWithTheSource(data) },
...
Step five: Attach the source to the shopper.
Step six: Attach the shopper to the cart.
Step seven: Create the order by submitting the cart.
Prerequisites: Refer to the Elements prerequisites section. Your flow also needs to display the storage terms and provide shoppers the option of saving their payment information.
Step one: Create a cart with all tax, shipping, duty and fee amounts in a final state.
Step two: Retrieve the payment session identifier and use it to configure the
createSource()
method. The configuration object should also set futureUse
to true
and usage
to convenience
. Use mandate.terms
to pass the save payment agreement that the customer accepts.var payload = {
"type": "creditCard",
"sessionId": "ea03bf6f-84ef-4993-b1e7-b7d5ecf71d1f",
"futureUse": true,
"usage": "convenience",
...
"mandate": {
"terms": "Yes, please save this account and payment information for future purchases."
}
}
digitalriver.createSource(payload).then(function(result) {
if (result.error) {
//handle errors
} else {
var source = result.source;
//send source to back end
sendToBackend(source);
}
});
Once the method is called and the customer provides the required SCA, a unique Source in a chargeable source is returned.
Step five: Create the order by submitting the cart.
In this one-off purchase flow, the customers select a credit card that they previously saved to their account. The key step is to call the authenticate source method.
SCA required? | Drop-in Payments supported? | Elements supported? |
---|---|---|
Yes | No | Yes |
Drop-in Payments
DigitalRiver.js with elements
Drop-in Payments do not currently support retrieving stored payment methods. In order to handle this flow, use Elements.
Step one: Create a cart with all tax, shipping, duty, and fee amounts in a final state.
Step two: Retrieve the customer's payment sources and display them to the shopper during the checkout process.
Step three: If the shopper selects a saved payment method, you'll need to determine whether SCA is required. To do this, call the
authenticateSource()
method....
digitalriver.authenticateSource({
"sessionId": "65b1e2c2-632c-4240-8897-195ca22ce108",
"sourceId": "ee90c07c-5549-4a6b-aa5f-aabe29b1e97a",
"sourceClientSecret": "ee90c07c-5549-4a6b-aa5f-aabe29b1e97a_51afe818-0e7f-46d7-8257-b209b20f4d8",
"returnUrl": "https://returnurl.com"
}).then(function(data) {
});
...
After invoking this method, Digital River automatically handles any required SCA. Once authentication is complete or is determined not to be necessary, the method resolves, allowing the checkout flow to continue.
Step five: Create the order by submitting the cart.
SCA is required for subscription acquisitions but not merchant-initiated auto-renewals. In this section, you'll find more information on developing SCA-compliant workflows for the following subscription checkout scenarios:
In this flow, during the checkout process, shoppers use a credit card to simultaneously acquire an auto-renewing subscription and save their payment information.
SCA required? | Drop-in Payments supported? | Elements supported? |
---|---|---|
Yes | Yes | Yes |
The following demonstrates how to build a workflow for this scenario using both Drop-in Payments and Elements.
Drop-in Payments
DigitalRiver.js with elements
Step one: Create a cart that contains an auto-renewing subscription and all tax, shipping, duty, and fee amounts are in a final state.
Step two: Retrieve the payment session identifier from the cart, and use it to create an instance of a configuration object. When specifying
options
, set flow
to checkout
, showSavePaymenAgreement
to true
, and usage
to subscription
.let configuration = {
sessionId: "d3941a36-6821-4d93-be23-6190226ae5f7",
options: {
"flow": "checkout",
"showSavePaymentAgreement": true,
"usage": "subscription"
},
}
let dropin = digitalriverpayments.createDropIn(configuration);
Drop-in renders in the specified container.
Shoppers must enter their credit card information, select the save account and payment information option and click the configurable Pay Now button.
Step five: If the shopper completes the SCA steps necessary to make the source chargeable, then call the
onSucess
method....
onSuccess: function (data) { doSometingWithTheSource(data) },
...
A chargeable source is returned that is ready for storage.
Step six: Attach the source to the shopper.
Step seven: Attach the shopper to the cart.
Step eight: Create the order by submitting the cart.
Your flow also needs to display the storage terms and provide customers the option of saving their payment information.
Step one: Create a cart that contains an auto-renewing subscription and all tax, shipping, duty and fee amounts are in a final state.
Step two: If a shopper selects the option to save the payment method and agrees to the displayed terms, retrieve the payment session identifier from the cart, and use it to create a source.
The
payload
should set futureUse
to true
, configure usage
to subscription
, and provide the mandate.terms
that the shopper agreed to on your storefront. var payload = {
"type": "creditCard",
"sessionId": "ea03bf6f-84ef-4993-b1e7-b7d5ecf71d1f",
"futureUse": true,
"usage": "subscription",
...
"mandate": {
"terms": "Yes, please save this account and payment information for future purchases."
}
}
digitalriver.createSource(payload).then(function(result) {
if (result.error) {
//handle errors
} else {
var source = result.source;
//send source to back end
sendToBackend(source);
}
});
Once the shopper provides the required SCA, a Source in a
chargeable
state is returned.Step three: Attach the source to the shopper.
Step four: Attach the shopper to the cart.
Step five: Create the order by submitting the cart.
In this flow, during the checkout process, shoppers select a credit card they previously saved to their account in order to acquire an auto-renewing subscription.
SCA required? | Drop-in supported? | Elements supported? |
Yes | No | Yes |
The following demonstrates how to build a workflow for this scenario using Elements. When building this workflow, the key step is to call the
authenticateSource
method.Drop-in Payments
DigitalRiver.js with elements
Drop-in Payments does not currently support retrieving stored payment methods. In order to handle this flow, use Digital River with elements.
Step one: Create a cart that contains an auto-renewing subscription and all tax, shipping, duty, and fee amounts are in a final state.
Step two: Retrieve the shopper's payment sources and display them to the shopper during the checkout process.
Step three: If the shopper selects a saved payment method, you'll need to determine whether SCA is required. To do this, call the
authenticateSource
method. ...
digitalriver.authenticateSource({
"sessionId": "65b1e2c2-632c-4240-8897-195ca22ce108",
"sourceId": "ee90c07c-5549-4a6b-aa5f-aabe29b1e97a",
"sourceClientSecret": "ee90c07c-5549-4a6b-aa5f-aabe29b1e97a_51afe818-0e7f-46d7-8257-b209b20f4d8",
"returnUrl": "https://returnurl.com"
}).then(function(data) {
});
...
After invoking this method, Digital River automatically handles any required SCA. Once authentication is complete or is determined not to be necessary, the method resolves, allowing the checkout flow to continue.
A chargeable source is returned.
Step four: Attach the source to a cart.
Step five: Create the order by submitting the cart.
In this flow, you initiate a subscription auto-renewal for the shopper. Although this flow type does not require SCA, you should ensure you're properly managing subscriptions, setting up auto-renewals, and initiating the charge type during the checkout process.
SCA required? | Drop-in Payments supported? | Elements supported? |
---|---|---|
No | N/A | N/A |
SCA is not required for transactions where shoppers provide their payment details by regular mail, fax, or telephone. But mail order and telephone order (MOTO) transactions are supported by Elements.
SCA required? | Drop-in Payments supported? | Elements supported? |
---|---|---|
No | No | Yes |
The following demonstrates how to build a workflow for this scenario using Elements.
Drop-in Payments
DigitalRiver.js with elements
For this flow type, you should use Element to capture credit card details.
Step one: Create a cart with all tax, shipping, duty, and fee amounts final state.
Once the shopper provides the required SCA, a chargeable source is returned.
Step three: Attach the source to a cart.
Step four: Create the order by submitting the cart.
For account management flows, you only need to adhere to SCA regulations when saving a shopper's credit card for future use. However, the other two scenarios, updating a credit card's expiration date and updating a credit's card billing address, while not required to have SCA, are both supported by elements.
In this flow, you're saving a shopper's credit card details for use in a future transaction.
For Drop-in PaymentsDrop-in Payments, the key step is to build the configuration object so that
flow
is set to managePaymentMethods
and theusage
parameter properly configures the source for future use. When using Elements, your
payload
should set futureUse
to true
, ensure usage
specifies a future use for the source, and provide the mandate.terms
that the customer agreed to.SCA required? | Drop-in Payments supported? | Elements supported? | Text |
---|---|---|---|
Yes | Yes | Yes | |
The following demonstrates how to build a workflow for this scenario using both Drop-in Payments and Elements. We also provide a demo.
Drop-in
DigitalRiver.js with elements
Step one: You are on a page where the Customer may configure payment methods stored against their account.
Step two: Create an instance of a configuration object that offers shoppers the ability to save payment methods on their account page.
You should configure the
flow
parameter to allow customers to manage their payment methods and the usage
parameter to identify the future use of the payment source. let configuration = {
options: {
"flow": "managePaymentMethods",
"usage": "subscription"
},
...
}
let dropin = digitalriverpayments.createDropIn(configuration);
Drop-in renders in the specified container.

Shoppers enter their credit card information, select the save account and payment information option and click the configurable Add Payment Method button.
Step five: If the shopper completes the SCA steps necessary to make the source chargeable, then call the
onSucess
method....
onSuccess: function (data) { doSometingWithTheSource(data) },
...
Step six: Attach the source to the shopper.
Prerequisites: Refer to the Elements prerequisites section. Your flow also needs to display the storage terms and provide shoppers the option of saving their payment information.
Step one: If a customer selects the option to save a payment method and agrees to the displayed terms, the
payload
should set futureUse
to true
, configure usage
to identify the future use of the payment source, and provide the mandate.terms
that the customer agreed to on your storefront. var payload = {
"type": "creditCard",
"futureUse": true,
"usage": "subscription",
...
"mandate": {
"terms": "Yes, please save this account and payment information for future purchases."
}
}
digitalriver.createSource(payload).then(function(result) {
if (result.error) {
//handle errors
} else {
var source = result.source;
//send source to back end
sendToBackend(source);
}
});
Once the shopper provides the required SCA, a chargeable source is returned.
Step three: Attach the source to the shopper.
In this flow, you're updating the expiration date on a shopper's saved credit card.
SCA required? | Drop-in Payments supported? | Elements supported? |
---|---|---|
No | No | Yes |
The following demonstrates how to build a workflow for this scenario using Elements.
Drop-in Payments
Digital River with elements
Drop-in Payments does not support interacting directly with saved payment methods
Step one: Retrieve the shopper's payment sources and display them to the shopper.
The shopper selects the payment method to update.
Step two: Capture the updated expiration date from the shopper and pass it to the update source method.
In this flow, you're updating the billing address on a shopper's saved credit card.
SCA required? | Drop-in Payments supported? | Elements supported? |
---|---|---|
No | No | Yes |
The following demonstrates how to build a workflow for this scenario using Elements.
Drop-in Payments
DigitalRiver.js with elements
Drop-in Payments does not support interacting directly with saved payment methods
Step one: Retrieve the shopper's payment sources and display them to the shopper.
The shopper selects the payment method to update.
Step two: Capture the updated billing address from the shopper and pass it to the update source method.
Last modified 2mo ago