You can create Strong Customer Authentication (SCA) compliant workflows for both purchase transactions and customer account management.

When building the workflows that use Drop-in, you first need to perform some common, initial steps before proceeding to the workflow specific steps.‌

When using Elements to build your workflows, you also need to complete some prerequisites.

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

Common Drop-in steps

For any workflow that uses Drop-in, whether it's a purchase or an account management flow, you first need to perform the following steps.:

1. ​Include DigitalRiver.js on your page.

2. ​Include the Drop-in CSS file.

3. ​Initialize DigitalRiver.js with your public key.

4. ​Create a container for Drop-in.

Once you've completed these initial steps, you can perform those specific to your desired purchase or account management scenario.

Elements prerequisites

When using Elements to build workflows, you 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.

Purchase flows

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

One-off

‌You can develop workflows that allow customers to enter, save, and retrieve their credit card information while making one-off purchases. SCA is required for these types of purchase workflows.

Customers enter their credit card information

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

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

let configuration = {
    sessionId: "d3941a36-6821-4d93-be23-6190226ae5f7",
    ...
}

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

let dropin = digitalriver.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 the configurable Pay Now button.

Step five: If the customer completes the SCA steps necessary to make the source chargeable, then the onSucess method is called.

...
onSuccess: function (data) { doSometingWithTheSource(data) },
...

Digital River returns a unique Source in a chargeable state.

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 unique Source in a chargeable state is returned.

Step three: Attach the Source to a Checkout.

Step four: Create the Order using the checkout identifier.

Customers save their credit card information

In this flow, customers save their credit card information during the checkout process.

For Drop-in, the key step is to build the configuration object so that showSavePaymentAgreement is true and theusage parameter properly configures the source for future use.

When using Elements, your payload should set futureUse to true and ensure usage specifies a future use for the source.

The following demonstrates how to build workflows 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.

Set the showSavePaymentAgreement to true. This ensures that the save payment agreement option is displayed to the customer. 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"
    },
    ...
}

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

let dropin = digitalriver.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 the configurable Pay Now button.

Step five: If the customer completes the SCA steps necessary to make the source chargeable, then the onSucess method is called.

...
onSuccess: function (data) { doSometingWithTheSource(data) },
...

Digital River returns a unique Source in a chargeable state 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.

In the payload, you should also specify futureUse as true, configure usage to specify a future use for the source, and provide the mandate.terms that the customer agreed to on your storefront.

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

Step three: Attach the Source to a Customer.

Step four: Attach the Customer to the Checkout.

Step five: Create the Order using the Checkout identifier.

Customers retrieve their credit card information

In this one-off purchase flow, customers select a credit card that they previously saved to their account.

The following demonstrates how to build a workflow for this scenario using Elements. The key step is to call the authenticate source 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) {
​
});
...

Subscription

You can create SCA-compliant workflows that allow customers to enter and retrieve their credit card information during subscription acquisitions. You can also set up workflows that allow merchants to initiate autorenewals.

Customers apply and save their credit card information during a subscription acquisition

In this flow, customers use a credit card to simultaneously acquire an auto-renewing subscription and save their payment information.

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 acquisition 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. When specifying options, set flow to checkout , showSavePaymentAgreement to true, and usage to subscription.

let configuration = {
    sessionId: "d3941a36-6821-4d93-be23-6190226ae5f7",
    options: {
        "flow": "checkout",
        "showSavePaymentAgreement": true,
        "usage": "subscription"
    },    
    ...
}

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

let dropin = digitalriver.createDropIn(configuration);

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

Drop-in renders in the specified container.

Customers 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 customer completes the SCA steps necessary to make the source chargeable, then the onSucess method is called.

...
onSuccess: function (data) { doSometingWithTheSource(data) },
...

Digital River returns a unique Source in a chargeable state 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 that contains an auto-renewing subscription acquisition and all tax, shipping, duty and fee amounts are in a final state.

Step two: If a customer selects the option to save the payment method and agrees to the displayed terms, retrieve the payment session identifier from the Checkout, 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 customer 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 customer provides the required SCA, a unique Source in a chargeable state is returned.

Step three: Attach the Source to the Customer.

Step four: Attach the Customer to the Checkout.

Step five: Create the Order using the checkout identifier.

Customers retrieve credit card details during a subscription acquisition

In this flow, customers select a credit card they previously saved to their account in order to acquire an auto-renewing subscription.

‌The following demonstrates how to build a workflow for this scenario using Elements. When building this workflow, the key step is to call the authenticate source 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) {
​
});
...

Merchant-initiated auto renewals

In this workflow, the merchant initiates a subscription auto-renewal for the customer. Although this type of workflow 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.

Mail order/telephone order

​SCA is not required for transactions where customers provide their payment details by regular mail, fax, or telephone. But Elements supports building workflows for mail order and telephone order (MOTO) transactions.

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

Account management flows

You can create flows that allow customers to manage their payment methods on personalized account management pages.

For these flows, you only need to adhere to SCA regulations when saving a customer's credit card for future use. You're not required to provide SCA when updating a credit card's expiration date or billing address.

When building a flow that allows customers to save payment methods, you should identify the future use of the source. This increases the probability that future transactions will be approved.

Saving a credit card for future use

In this flow, you're saving a customer's credit card information for use in future transactions.

For Drop-in, 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.

Using either Drop-in or Elements, the following demonstrates how to build a workflow for this scenario. We also provide a demo.

Drop-in

Elements

Drop-in

Prerequisites: Perform the common drop-in steps.

Step one: Go to a page in your integration where customers manage their payment methods.

Step two: Create an instance of a configuration object. 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"
    },
    ...
}

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

let dropin = digitalriver.createDropIn(configuration);

Step four: On the account management 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 the configurable Add Payment Method button.

Step five: If the customer completes the SCA steps necessary to make the source chargeable, then the onSucess method is called.

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

Step two: Attach the Source to the Customer.

Updating a credit card's expiration date or billing address

In this flow, you're updating the expiration date or billing address on a customer's saved credit card.

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