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

‌In this flow, customers 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 or update a Checkout with all tax, shipping, duty and fee amounts in a final state.

Step two: Retrieve the payment session identifier from the Checkout, 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 page, specify a container to place Drop-in.

Drop-in renders in the specified container.

Customers enter their credit card information and click Pay Now.

Step five: If the customer 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 Checkout.

Step seven: Create the Order using the checkout identifier.

Elements

Prerequisites: Refer to the Elements prerequisites section.

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

Step two: Retrieve the payment session identifier from the Checkout, and use it to create a source. Once the customer provides the required SCA, a Source in a chargeable state is returned.

Step three: Attach the Source to a Checkout.

Step four: Create the Order using the checkout identifier.

Credit card details saved by customer

In this flow, customers 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 or update a Checkout with all tax, shipping, duty and fee amounts in a final state.

Step two: Retrieve the payment session identifier from the Checkout, and use it to create an instance of a configuration object that includes the option to show the save payment agreement to the customer.

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 checkout page, specify a container to place Drop-in.

Drop-in renders in the specified container.

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

Step five: If the customer 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 Customer.

Step seven: Attach the Customer to the Checkout.

Step eight: Create the Order using the checkout identifier.

Elements

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: Create or update a Checkout with all tax, shipping, duty and fee amounts in a final state.

Step two: Retrieve the payment session identifier from the Checkout, and use it to create a source.

If a customer 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 customer provides the required SCA, a Source in a chargeable state is returned.

Step three: Attach the Source to a Checkout.

Step four: Create the Order using the checkout identifier.

Credit card details retrieved by customer

In this flow, during the checkout process, customers 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 or update a Checkout with all tax, shipping, duty and fee amounts in a final state.

Step two: Retrieve the customer's payment sources using the Customers API and display them to the customer during the checkout flow.

Step three: If the customer 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 customer 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 Source in a chargeable state is returned.

Step four: Attach the Source to a Checkout.

Step five: Create the Order using the checkout identifier.

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

Customer enters credit card details during subscription acquisition

In this flow, during the checkout process, customers 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 or update a Checkout 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 Checkout, 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 page, specify a container to place Drop-in.

Drop-in renders in the specified container.

Customers enter their credit card information and click Pay Now.

Step five: If the customer 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 Checkout.

Step seven: Create the Order using the checkout identifier.

Elements

Prerequisites: Refer to the Elements prerequisites section.

Step one: Create or update a Checkout 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 Checkout, and use it to create a source.

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

Step three: Attach the Source to a Checkout.

Step four: Create the Order using the checkout identifier.

Customer retrieves credit card details during subscription acquisition

In this flow, during the checkout process, customers 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 or update a Checkout that contains an auto-renewing subscription and all tax, shipping, duty and fee amounts are in a final state.

Step two: Retrieve the customer's payment sources using the Customers API and display them to the customer during the checkout process.

Step three: If the customer 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 customer 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 Source in a chargeable state is returned.

Step four: Attach the Source to a Checkout.

Step five: Create the Order using the checkout identifier.

Merchant-initiated auto renewals

In this flow, you initiate a subscription auto-renewal for the customer. 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 customers 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 or update a Checkout with a charge type of moto and all tax, shipping, duty and fee amounts are in a final state.

Step two: Retrieve the payment session identifier from the Checkout, and use it to create a source.

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

Step three: Attach the Source to a Checkout.

Step four: Create the Order using the checkout identifier.

Account management flows

For account management flows, you only need to adhere to SCA regulations when saving a customer'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 customer'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 customers 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 checkout page, specify a container to place Drop-in.

Drop-in renders in the specified container.

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

Step five: If the customer 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 Customer.

Elements

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: If a customer 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 customer provides the required SCA, a Source in a chargeable state is returned.

Step three: Attach the Source to the Customer.

Updating a credit card's expiration date

In this flow, you're updating the expiration date on a customer'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 customer's payment sources using the Customers API and display them to the customer. The customer selects the payment method to update.

Step two: Capture the updated expiration date from the customer 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 customer'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 customer's payment sources using the Customers API and display them to the customer. The customer selects the payment method to update.

Step two: Capture the updated billing address from the customer and pass it to the update source method.