Comment on page
Building payment workflows
Learn how to create SCA-compliant workflows using Drop-in payments or Elements.
Using Drop-in payments or Elements, you can create Strong Customer Authentication (SCA) compliant workflows for both purchase transactions and account management.
Whichever payment solution you're using, all SCA requirements are 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.
The following chart lists some of the key settings and methods you should use when building purchase and account management flows. It's meant to be read from left-to-right and top-to-bottom. For example:
- In one-off purchase flows in which customers save a new payment source to their account, you should set the checkout's
chargeType
tocustomer_initiated
. If you're using Drop-in payments, use thecreateDropIn()
method's configurableoptions
to setflow
tocheckout
andusage
toconvenience
. With DigitalRiver.js with elements, use thecreateSource()
method's configuration object to setfutureUse
totrue
andusage
toconvenience
. - When customers are acquiring an auto-renewing subscription, and decide to retrieve a payment source saved to their account, set the checkout's
chargeType
tocustomer_initiated
andautoRenewal
totrue
. In this flow type, Drop-in payments is not supported. Instead, you'll need to use theauthenticateSource()
method.

Click to enlarge image
For any workflow that uses Drop-in payments, whether it's intended to handle purchases or account management, you first need to perform the following steps:
If you're using Elements to build purchase workflows, make sure you complete the necessary migration to payment sessions. We also assume you are familiar with creating and styling elements as well as the basics of capturing payment details.
For almost all one-off, subscription, and mail-order/telephone-order (MOTO) transactions, Digital River supports SCA-compliant workflows that use either Drop-in payments or Elements.
In this one-off flow, customers supply their payment information, but don't save it to their account.
SCA required? | Drop-in payments supported? | Elements supported? |
---|---|---|
Yes | Yes | Yes |
Drop-in payments
Elements
Step one: Build a checkout with all tax, shipping, duty and fee amounts in a final state and a
chargeType
that is customer_initiated
.Step two: Retrieve the checkout's payment session identifier, and use it to set
sessionId
in the 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"
}
...
}
let dropin = digitalriver.createDropin(configuration);
Step four: On your checkout page, Drop-in payments renders in the designated container.
...
onSuccess: function (data) { doSometingWithTheSource(data) },
...
Step one: Build a checkout 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 and assign it to
sessionId
in the createSource()
method's configuration object. You 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();
}
});
After the method is called and customers complete any SCA that may be required, a unique source is returned.
SCA required? | Drop-in payments supported? | Elements supported? |
---|---|---|
Yes | Yes | Yes |
Drop-in payments
Elements
Step one: Build a checkout with a registered customer and all tax, shipping, duty and fee amounts in a final state. The
chargeType
should be customer_initiated
.Step two: Retrieve the checkout's payment session identifier and use it to set
sessionId
in the Drop-in payments' configuration object. You should also use options
to set flow
to checkout
, usage
to convenience
, and showSavePaymentAgreement
to true
.let configuration = {
sessionId: "d3941a36-6821-4d93-be23-6190226ae5f7",
options: {
"flow": "checkout",
"showSavePaymentAgreement": true,
"usage": "convenience"
},
...
}
let dropin = digitalriver.createDropIn(configuration);
Step four: On your checkout page, Drop-in payments renders in the designated container.
Customers enter their credit card information, actively accept the save payment agreement and click the configurable pay now button.
If customers complete any SCA that may be required,
onSuccess
returns a source that is readyForStorage
....
onSuccess: function (data) { doSometingWithTheSource(data) },
...
Prerequisites: Refer to the Elements prerequisites section. Your flow also needs to display the storage terms and provide customers the option of saving their payment information.
Step one: Build a checkout with a registered customer and all tax, shipping, duty and fee amounts in a final state. The
chargeType
should be customer_initiated
.Step two: Retrieve the payment session identifier and assign it to
sessionId
in the createSource()
method's configuration object. You 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);
}
});
After the method is called and customers complete any SCA that may be required, a unique source is returned.
In this one-off purchase flow, customers select a payment method 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
Elements
Drop-in payments does not currently support retrieving saved payment methods. In order to handle this flow, use Elements.
Step one: Build a checkout with a registered customer and all tax, shipping, duty and fee amounts in a final state. The
chargeType
should be customer_initiated
.Step three: If the customer opts to use 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 the method is invoked, Digital River 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
Elements
Step one: Build a checkout with a registered customer and all tax, shipping, duty and fee amounts in a final state. Set
chargeType
to customer_initiated
and autoRenewal
to true
.Step two: Retrieve the checkout's payment session identifier, and use it to set
sessionId
in the configuration object. In options
, set flow
to checkout
, usage
to subscription
, and showTermsOfSaleDisclosure
to true
.let configuration = {
sessionId: "d3941a36-6821-4d93-be23-6190226ae5f7",
options: {
"flow": "checkout",
"showTermsOfSaleDisclosure": true,
"usage": "subscription"
},
...
}
let dropin = digitalriver.createDropIn(configuration);
Step four: On your checkout page, Drop-in payments renders in the designated container.

Customers must enter their payment information, actively accept the terms and click the configurable pay now button.
If customers complete any SCA that may be required,
onSuccess
returns a source 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: Build a checkout with a registered customer and all tax, shipping, duty and fee amounts in a final state. Set
chargeType
to customer_initiated
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 assign it to
sessionId
in the createSource()
method's configuration object. You 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, 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);
}
});
After the method is called and customers complete any SCA that may be required, a unique source is returned.
In this flow, customers select a credit card they previously saved to their account and use it to acquire an auto-renewing subscription.
SCA required? | Drop-in payments supported? | Elements supported? |
---|---|---|
Yes | No | Yes |
Drop-in payments
Elements
Drop-in payments does not currently support retrieving stored payment methods. In order to handle this flow, use Elements.
Step one: Build a checkout with a registered customer and all tax, shipping, duty and fee amounts in a final state. Set
chargeType
to customer_initiated
and autoRenewal
to true
.Step two: Retrieve the customer's payment sources and display them to the customer during the checkout process.
Step three: If the customer opts to use a saved payment method, 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, and returns a unique Source.
In this workflow, a merchant initiates the auto-renewal of a subscription. Although this type of workflow doesn't require SCA, you should ensure you're correctly handling auto-renewing subscriptions.
SCA required? | Drop-in payments supported? | Elements supported? |
---|---|---|
No | N/A | N/A |
SCA is not required for transactions where customers provide their payment details by regular 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 | Yes | Yes |
Drop-in payments
Elements
Step one: Build a checkout 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 that are 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"
}
...
}
let dropin = digitalriver.createDropin(configuration);
Step four: On your checkout page, Drop-in payments renders in the designated 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
onSuccess
returns a unique source in a chargeable
state....
onSuccess: function (data) { doSometingWithTheSource(data) },
...
Step one: Build a checkout 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 assign it to
sessionId
in the createSource()
method's configuration object. You 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();
}
});
After the method is called and customers complete any SCA that may be required, a unique source is returned.
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, attempt to identify the intended use of the source. This increases the probability that future transactions will be approved.
In this flow, customers use their account portal to save payment information for use in future transactions.
SCA required? | Drop-in payments supported? | Elements supported? |
---|---|---|
Yes | Yes | Yes |
Drop-in payments
Elements
Step one: On the page where customers manage their payment methods, use the configuration object's
options
to set flow
to managePaymentMethods
and specify a value for usage
that identifies the likely future use of the payment.If customers are replacing an active subscription's recurring billing instrument, make sure you set
usage
to subscription
and showTermsofSaleDisclosure
to true
. This prompts Drop-in payments to display a recurring billing agreement and forces customers to accept it.Because this is a
managePaymentMethods
flow, and there's no payment session to reference, you shouldn't provide a sessionId
. As a result, you'll need to pass the billing information you collect from customers in billingAddress
.
let dropin = digitalriver.createDropIn(configuration);
Step four: On your checkout page, Drop-in payments renders in the designated container.
Customers enter their payment information, select the save payment agreement option and click the configurable add payment method button.
If customers complete any SCA that may be required,
onSuccess
returns a source that is readyForStorage
....
onSuccess: function (data) { doSometingWithTheSource(data) },
...
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: Once a customer selects the option to save a payment method and agrees to the displayed terms, use the
createSource()
method's configuration object to set futureUse
to true
. Make sure you also assign a value to
usage
that identifies the future use of the payment source and pass 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);
}
});
In this flow, customers use their account portal to update the expiration date or billing address on a saved credit card.
SCA required? | Drop-in payments supported? | Elements supported? |
---|---|---|
No | No | Yes |
Drop-in payments
Elements
The customer selects the payment method to update.
Step two: Capture the updated expiration date or billing address from the customer and pass it to the update source method.
Last modified 2mo ago