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 account management.
When building 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, you must also 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 scene" 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
, a409 Conflict
response contains specific information about what triggered the failure. In this instance, one of the currencies in the cart is not supported.
Error
{
"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}."
}
]
}
}
- Currently, you can't use the store credit to buy subscription products, pre-order products, or products on backorder. Additionally, you can't link more than one store credit source to an order, as multiple secondary sources are not currently supported.
You must perform the following steps for any workflow that uses Drop-in Payments, whether built for purchases or account management.
Once you've completed these initial steps, you can perform those specific to your desired purchase or account management scenario.
You need to use payment sessions when using DigitalRiver.js with elements to build workflows. So ensure you've completed the necessary migration. We assume you are familiar with creating and styling elements and 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) transactions, Digital River supports SCA-compliant workflows using Drop-in Payments or DigitalRiver.js elements.
In this flow, customers supply their credit card information during a one-off transaction but don't save it to their accounts.
SCA required? | Drop-in Payments supported? | Elements supported? |
---|---|---|
Yes | Yes | Yes |
Drop-in Payments
DigitalRiver.js with elements
Step one: Create a cart with all tax, shipping, duty, and fee amounts in a final state and a
chargeType
that is customer_initiated
.Step two: Retrieve the cart's payment session identifier, and use it to set the sessionId in the Drop-in Payments' configuration object. In
options
, set flow
to checkout
and usage
to convenience
, and (to prompt Drop-in payments to display the save payment option) showSavePaymentAgreement
to true
.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 customer completes the SCA, then the
onSuccess
method is called, and Digital River returns a unique source in a chargeable state....
onSuccess: function (data) { doSometingWithTheSource(data) },
...
Step one: Create a cart with all tax, shipping, duty, and fee amounts in a final state and a
chargeType
that is customer_initiated
.Step two: Retrieve the payment session identifier from the cart, and use it to configure the
createSource()
method. The configuration object should also set futureUse
to false
and usage
to convenience
.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 method is called and the shopper provides the required SCA, a unique Source in a chargeable state is returned.
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 |
Drop-in Payments
DigitalRiver.js with elements
Step one: Create a cart with all tax, shipping, duty, and fee amounts in a final state. Set
chargeType
to customer_initiated
and autoRenewal
to true
.Step two: Retrieve the cart's payment session identifier, and use it to set the sessionId in the Drop-in Payments 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);
The modal renders in the specified container.

Customers enter their credit card information, actively accept the save payment agreement, and click the configurable Pay Now button.
If the customer 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 with the option of saving their payment information.
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.
In this one-off purchase flow, the customers select a credit card 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. To handle this flow, use Elements.
Step one: Create a cart with all tax, shipping, duty, and fee amounts in a final state. The
chargeType
should be customer_initiated
.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, configure and 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.
You can create SCA-compliant workflows that allow customers to either save or retrieve a recurring payment method during subscription acquisitions. You can also set up workflows for merchant-initiated autorenewals.
In this flow, customers save payment information to their account and use that payment source to acquire an auto-renewing subscription.
SCA required? | Drop-in Payments supported? | Elements supported? |
---|---|---|
Yes | Yes | Yes |
Drop-in Payments
DigitalRiver.js with elements
Step one: Create a cart with an authenticated customer, and all tax, shipping, duty, and fee amounts are in a final state. Set
chargeType
to customer_initiate
and autoRenewal
to true
.Step two: Retrieve the payment session identifier from the cart, and use it to set the
sessionId
in the Drop-in Payments configuration object. In
options
, set flow
to checkout
and usage
to convenience
, and (to prompt Drop-in payments to display the save payment option) showTermsOfSaleDisclosure
to true
.let configuration = {
sessionId: "d3941a36-6821-4d93-be23-6190226ae5f7",
options: {
"flow": "checkout",
"showTermsOfSaleDisclosure": true,
"usage": "subscription"
},
...
}
let dropin = digitalriver.createDropIn(configuration);
Drop-in renders in the specified container.

If the shopper completes the necessary SCA steps, then the
onSucess
method is called an,d Digital River returns a unique source in a chargeable state that is readyForStorage
....
onSuccess: function (data) { doSometingWithTheSource(data) },
...
Prerequisites: Refer to the Elements prerequisites section. At some point during the flow, you also need to display the subscription's terms and save payment agreement and acquire the customer's active acceptance of them.
Step one: Create a cart with an authenticated customer and all tax, shipping, duty, and fee amounts are in a final state. Set
chargeType
to customer_initiate
and autoRenewal
to true
.Step two: Once the customer selects the option to save the payment method and agrees to the displayed terms, 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 subscription
. 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": "subscription",
...
"mandate": {
"terms": "Yes, 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 the source to back end
sendToBackend(source);
}
});
In this flow, during the checkout process, shoppers select a credit card they previously saved to their account 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. To handle this flow, use Digital River with elements.
Step one: Create a cart with an authenticated customer and all tax, shipping, duty, and fee amounts are in a final state. Set
chargeType
to customer_initiate
and autoRenewal
to true
.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.
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 payment details by mail, fax, or telephone. But both Drop-in Payments and Elements support building workflows for mail order and telephone order (MOTO) transactions.
SCA required? | Drop-in Payments supported? | Elements supported? |
---|---|---|
No | No | Yes |
Drop-in Payments
DigitalRiver.js with Elements
Step one: Create a cart with a
chargeType
of moto
and all tax, shipping, duty, and fee amounts in a final state. This configures Drop-in payments to display only payment methods supported in MOTO transactions.Step two: Retrieve the checkout's payment session identifier, and use it to set
sessionId
in the Drop-in payments' configuration object. In options
, set flow
to checkout
and usage
to convenience
.let configuration = {
sessionId: "d3941a36-6821-4d93-be23-6190226ae5f7",
options: {
flow: "checkout",
usage: "convenience"
}
...
}
Step three: Use the configuration object to instantiate Drop-in payments.
let dropin = digitalriver.createDropin(configuration);
The modal window renders in the specified container.

The merchant's representative enters the customer's credit card information and clicks the configurable Pay Now button. If the payment is authorized, then the
onSuccess
method is called, and Digital River returns a unique source in a chargeable
state....
onSuccess: function (data) { doSometingWithTheSource(data) },
...
Step one: Create a cart with a charge type of
moto
and 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 false
and usage
to convenience
.Once the method is invoked and payment is authorized, a unique Source is returned in a
chargeable
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();
}
});
You can create flows that allow customers to manage recurring payment methods through their account portal.
In these account management flows you only need to adhere to SCA regulations when saving a customer's credit card for future use. While storing a card, make sure you identify the future use of the source. This increases the probability that future transactions will be approved.
You're not required to provide SCA when updating a credit card's expiration date or billing address.
SCA required? | Drop-in Payments supported? | Elements supported? | Text |
---|---|---|---|
Yes | Yes | Yes | |
Drop-in payments
DigitalRiver.js with elements
Step one: Go to a page in your integration where customers manage their payment methods.
Step two: In the configuration object's
options
, set flow
to managePaymentMethods
and specify a value for usage
that identifies the potential future use of the payment source.let configuration = {
options: {
"flow": "managePaymentMethods",
"usage": "subscription"
},
...
}
let dropin = digitalriverpayments.createDropIn(configuration);
The modal window renders in the specified container.

Shoppers enter their credit card information, select the save payment agreement option and click the configurable add payment method button.
If the shopper completes the necessary SCA steps, then the
onSucess
method is called, and Digital River returns a unique source in a chargeable state that is readyForStorage
....
onSuccess: function (data) { doSometingWithTheSource(data) },
...
Step six: Attach the source to the shopper.
Prerequisites: Refer to the Elements prerequisites section You also need to display the save payment agreement and acquire the customer's active acceptance.
Step one: If a customer selects the option to save a payment method and agrees to the displayed terms, the configuration object 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);
}
});
Customers use their account portal to update their saved credit card's expiration date or billing address in this flow.
SCA required? | Drop-in Payments supported? | Elements supported? |
---|---|---|
No | No | Yes |
Drop-in Payments
Digital River with elements
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.
Last modified 22d ago