Building your workflows

Learn how to create SCA-compliant workflows using Drop-in and 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, you'll first need to perform some common, initial steps before proceeding to the workflow's specific steps.‌

When using Elements to support SCA, you'll need to complete the prerequisites detailed here.

For all the supported workflows, whether you are using Drop-in or Elements, any SCA requirements are automatically handled by Digital River.

If you build the workflows that are applicable to you and your solution, you will be SCA compliant.

Common Drop-in steps

For any SCA-compliant workflow that uses Drop-in, 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.

Elements prerequisites

When using 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.

Purchase Flows

For almost all one-off, subscription, and mail-order/telephone-order (MOTO) transaction scenarios, Digital River supports SCA-compliant workflows that use Drop-in, Elements, or both.‌

One-off

‌SCA is required for one-off credit card purchases. In this section, you'll find more information on developing SCA workflows for the following one-off checkout scenarios:

Credit card details entered by shopper

‌In this flow, shoppers enter their credit card information during the checkout process.

SCA required?

Drop-in supported?

Elements supported?

Yes

Yes

Yes

‌The following demonstrates how to build a workflow for this scenario using both Drop-in and Elements. We also provide a demo.

Drop-in
Elements
Drop-in

Prerequisites: Perform the common drop-in steps.

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.

Step three: Use the configuration object to initialize Drop-in.

let configuration = {
sessionId: "d3941a36-6821-4d93-be23-6190226ae5f7",
...
}
let dropin = digitalriverpayments.createDropin(configuration);

Step four: On your cart page, specify a container to place Drop-in.

Drop-in renders in the specified container.

Shoppers enter their credit card information and click Pay Now.

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.

Step six: Attach the source to the cart.

Step seven: Create the order by submitting the cart.

Elements

Prerequisites: Refer to the Elements prerequisites section.

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

Credit card details saved by shopper

In this flow, shoppers save their credit card information during the checkout process. This is done by setting the showSavePaymentAgreement option to true.

SCA required?

Drop-in supported?

Elements supported?

Yes

Yes

Yes

The following demonstrates how to build workflows for this scenario using both Drop-in and Elements. We also provide a demo. In these workflows, the key steps are to set the showSavePaymentAgreement option to true for Drop-in and futureUse to true for Elements.

Drop-in
Elements
Drop-in

Prerequisites: Perform the common drop-in steps.

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 that includes the option to show the save payment agreement to the shopper.

Step three: Use the configuration object to initialize Drop-in.

let configuration = {
sessionId: "d3941a36-6821-4d93-be23-6190226ae5f7",
options: {
"showSavePaymentAgreement": true
},
...
}
let dropin = digitalriverpayments.createDropIn(configuration);

Step four: On your cart page, specify a container to place Drop-in.

Drop-in renders in the specified container.

Shoppers enter their credit card information, select the save account and payment information option and click Pay Now.

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.

Elements

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 from the cart, and use it to create a source.

If a shopper selects the option to save a payment method and agrees to the displayed terms, specify futureUse as true and provide the mandate.terms in the create source payload.

var payload = {
"type": "creditCard",
"sessionId": "ea03bf6f-84ef-4993-b1e7-b7d5ecf71d1f",
"futureUse": true,
...
"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 cart.

Step four: Create the order by submitting the cart.

Credit card details retrieved by shopper

In this flow, during the checkout process, shoppers select a credit card that they previously saved to their account.

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
Elements
Drop-in

Drop-in does not currently support retrieving stored payment methods. In order to handle this flow, use Elements.

Elements

Prerequisites: Refer to the Elements prerequisites section.

Step one: Create a cart with all tax, shipping, duty and fee amounts in a final state.

Step two: Retrieve the shopper's payment sources and display them to the shopper during the checkout flow.

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 and pass in the sessionId, sourceId, and sourceClientSecret of the current transaction. You can also provide the returnUrl where the shopper will land if 3D Secure 1 is required.

...
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 the cart.

Step five: Create the order by submitting the cart.

Subscription

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:‌

Shopper enters credit card details during subscription acquisition

In this flow, during the checkout process, shoppers enter their credit card information when acquiring an auto-renewing subscription.

SCA required?

Drop-in supported?

Elements supported?

Yes

Yes

Yes

The following demonstrates how to build a workflow for this scenario using both Drop-in and Elements.

Drop-in
Elements
Drop-in

Prerequisites: Perform the common drop-in steps.

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.

Step three: Use the configuration object to initialize Drop-in.

let configuration = {
sessionId: "d3941a36-6821-4d93-be23-6190226ae5f7",
...
}
let dropin = digitalriverpayments.createDropIn(configuration);

Step four: On your checkout/cart page, specify a container to place Drop-in.

Drop-in renders in the specified container.

Shoppers enter their credit card information and click Pay Now.

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.

Step six: Attach the source to the cart.

Step seven: Create the order by submitting the cart.

Elements

Prerequisites: Refer to the Elements prerequisites section.

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

Once the shopper provides the required SCA, a Source in a chargeable state is returned.

Step three: Attach the source to a cart.

Step four: Create the order by submitting the cart.

Shopper retrieves credit card details during subscription acquisition

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
Elements
Drop-in

Drop-in does not currently support retrieving stored payment methods. In order to handle this flow, use Elements.

Elements

Prerequisites: Refer to the Elements prerequisites section.

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 and pass in the sessionId, sourceId, and sourceClientSecret of the current transaction. You can also provide the returnUrl where the shopper will land if 3D Secure 1 is required.

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

Merchant-initiated auto renewals

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 supported?

Elements supported?

No

N/A

N/A

Mail order/telephone order

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 supported?

Elements supported?

No

No

Yes

The following demonstrates how to build a workflow for this scenario using Elements.

Drop-in
Elements
Drop-in

For this flow type, you should use Element to capture credit card details.

Elements

Prerequisites: Refer to the Elements prerequisites section.

Step one: Create a cart with 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 a source.

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.

Account management flows

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.

Saving a credit card for future use

In this flow, you're saving a shopper's credit card details for use in a future transaction.

SCA required?

Drop-in supported?

Elements supported?

Yes

Yes

Yes

The following demonstrates how to build a workflow for this scenario using both Drop-in and Elements. We also provide a demo. In these workflows, the key steps are to set the flow option to managePaymentMethods for Drop-in and futureUse to true for Elements.

Drop-in
Elements
Drop-in

Prerequisites: Perform the common drop-in steps.

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. To do this, set flow to managePaymentMethods.

Step three: Use the configuration object to initialize Drop-in.

let configuration = {
options: {
"flow": "managePaymentMethods"
},
...
}
let dropin = digitalriverpayments.createDropIn(configuration);

Step four: On your cart page, specify a container to place Drop-in.

Drop-in renders in the specified container.

Shoppers enter their credit card information, select the save account and payment information option and click Add Payment Method.

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.

Elements

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 shopper selects the option to save a payment method and agrees to the displayed terms, specify futureUse as true and provide the mandate.terms in the create source payload.

var payload = {
"type": "creditCard",
"futureUse": true,
...
"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.

Updating a credit card's expiration date

In this flow, you're updating the expiration date on a shopper's saved credit card.

SCA required?

Drop-in supported?

Elements supported?

No

No

Yes

The following demonstrates how to build a workflow for this scenario using Elements.

Drop-in
Elements
Drop-in

Drop-in does not support interacting directly with saved payment methods‌

Elements

Prerequisites: Refer to the Elements prerequisites section.

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.

Updating a credit card's billing address

In this flow, you're updating the billing address on a shopper's saved credit card.

SCA required?

Drop-in supported?

Elements supported?

No

No

Yes

The following demonstrates how to build a workflow for this scenario using Elements.

Drop-in
Elements
Drop-in

Drop-in does not support interacting directly with saved payment methods‌

Elements

Prerequisites: Refer to the Elements prerequisites section.

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.