Building your workflows

Create a test account Sign in to Dashboard System status
Search…
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 account management.
When building workflows that use Drop-in, you first need to perform some common, initial steps before proceeding to the workflow specific steps.‌ For workflows using Elements, you also need to complete some prerequisites.
Each purchase and account management workflow has some key settings and methods. When implementing one-off, subscription, and mail-order/telephone-order workflows, it's especially important to use futureUse and usage in combination with chargeType. This allows Digital River to properly format these types of transactions. 
Whether you're using Drop-in or Elements, all 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-scenes" and requires no developer interaction. 
Key settings and methods
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 chargeType to customer_initiated. If you're using Drop-in to handle payments, use the createDropIn() method's configurable options to set flow to checkout and usage to convenience. With DigitalRiver.js, use the createSource() method's configuration object to set futureUse to true and usage to convenience. 
When customers are acquiring an auto-renewing subscription, and decide to retrieve a payment source saved to their account, set the checkout's chargeType to customer_initiated and  autoRenewal to true. In this flow type, Drop-in is not supported. So instead, you should use the DigitalRiver.js authenticateSource() method.
For a more complete description of how to build each flow, refer to the appropriate section on this page. This is especially important for subscription acquisition workflows. These workflows require additional configurations that force customers to (1) accept the autorenewal terms and (2) save the subscription's payment source for use in autorenewals. 
Click to enlarge image
Common Drop-in steps
For any workflow that uses Drop-in, whether it's built for purchases or account management, 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 payment information while making one-off purchases. 
Customers enter their credit card information
‌In this flow, customers supply their credit card information during a one-off transaction, but don't save it to their account.
SCA required?
Drop-in supported?
Elements supported?
Yes
Yes
Yes
‌The following demonstrates how to build this workflow using both Drop-in and Elements. We also provide a demo.
Drop-in
Elements
Prerequisites: Perform the common Drop-in steps.
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 use it to create an instance of a configuration object. In the configuration options, set flow to checkout and usage to convenience.
1
let configuration = {
2
    sessionId: "d3941a36-6821-4d93-be23-6190226ae5f7",
3
    options: {
4
        flow: "checkout",
5
        usage: "convenience"
6
    }
7
    ...
8
}
Copied!
Step three: Use the configuration object to initialize Drop-in.
1
let dropin = digitalriver.createDropin(configuration);
Copied!
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.
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.
1
...
2
onSuccess: function (data) { doSometingWithTheSource(data) },
3
...
Copied!
Step five: Attach the Source to the Checkout.
Step six: Convert the Checkout to an Order.
Prerequisites: Refer to the Elements prerequisites section.
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 use it to configure the createSource() method. The configuration object should also set futureUse to false and usage to convenience.
1
let payload = {
2
    "sessionId": "ea03bf6f-84ef-4993-b1e7-b7d5ecf71d1f",
3
    "futureUse": false,
4
    "usage": "convenience",
5
    ...
6
}
7
​
8
digitalriver.createSource(payload).then(function(result) {
9
    if(result.state === "chargeable") {
10
        sendToBackEnd(result);
11
    } else {
12
        doErrorScenario();
13
    }
14
});
Copied!
Once the method is called and the customer provides the required SCA, a unique Source in a chargeable state is returned.
Step three: Attach the Source to the Checkout.
Step four: Convert the Checkout to an Order.
Customers save their credit card information
In this flow, customers enter credit card information and save it to their account during a one-off transaction.
SCA required?
Drop-in supported?
Elements supported?
Yes
Yes
Yes
The following demonstrates how to build this workflow using both Drop-in and Elements. We also provide a demo.
Drop-in
Elements
Prerequisites: Perform the common Drop-in steps.
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 use it to create an instance of a configuration object. In the configuration options, set flow to checkout and usage to convenience. To prompt Drop-in to display the save payment option, set showSavePaymentAgreement to true. 
1
let configuration = {
2
    sessionId: "d3941a36-6821-4d93-be23-6190226ae5f7",
3
    options: {
4
        "flow": "checkout",
5
        "showSavePaymentAgreement": true,
6
        "usage": "convenience"
7
    },
8
    ...
9
}
Copied!
Step three: Use the configuration object to initialize Drop-in.
1
let dropin = digitalriver.createDropIn(configuration);
Copied!
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, actively accept the save payment agreement and click the configurable pay now button.
If the customer completes the SCA necessary to make the source chargeable, then the onSuccess method is called and Digital River returns a unique Source in a chargeable state that is readyForStorage.
1
...
2
onSuccess: function (data) { doSometingWithTheSource(data) },
3
...
Copied!
Step five: Attach the Source to the Customer.
Step six: Attach the Source to the Checkout.
Step seven: Convert the Checkout to an Order.
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 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.
1
var payload = {
2
    "type": "creditCard",
3
    "sessionId": "ea03bf6f-84ef-4993-b1e7-b7d5ecf71d1f",
4
    "futureUse": true,
5
    "usage": "convenience",
6
    ...
7
    "mandate": {
8
        "terms": "Yes, please save this account and payment information for future purchases."
9
    }
10
}
11
​
12
digitalriver.createSource(payload).then(function(result) {
13
    if (result.error) {
14
        //handle errors
15
    } else {
16
        var source = result.source;
17
        //send source to back end
18
        sendToBackend(source);
19
    }
20
});
Copied!
Once the method is called and 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 Source to the Checkout.
Step five: Convert the Checkout to an Order.
Customers retrieve their credit card information
In this one-off purchase flow, 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 this workflow for both Drop-in and Elements. The key step is to call the authenticate source method.
Drop-in
Elements
Drop-in does not currently support retrieving saved payment methods. In order to handle this flow, use Elements.
Prerequisites: Refer to the Elements prerequisites section.
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 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, you'll need to determine whether SCA is required. To do this, configure and call the authenticateSource() method.
1
...
2
digitalriver.authenticateSource({
3
    "sessionId": "65b1e2c2-632c-4240-8897-195ca22ce108",
4
    "sourceId": "ee90c07c-5549-4a6b-aa5f-aabe29b1e97a",
5
    "sourceClientSecret": "ee90c07c-5549-4a6b-aa5f-aabe29b1e97a_51afe818-0e7f-46d7-8257-b209b20f4d8",
6
    "returnUrl": "https://returnurl.com"
7
}).then(function(data) {
8
​
9
});
10
...
Copied!
After the method is invoked, 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.
If authentication is successful, Digital River returns the Source in a chargeable state.
Step four: Attach the Source to the Checkout.
Step five: Convert the Checkout to an Order.
Subscription
You can create SCA-compliant workflows that allow customers to save and retrieve their credit card information during subscription acquisitions. You can also set up workflows for merchant-initiated autorenewals.
SCA is required for subscription acquisitions but not merchant-initiated auto-renewals.
Customers enter and save their credit card information during a subscription acquisition
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 supported?
Elements supported?
Yes
Yes
Yes
The following demonstrates how to build this workflow using both Drop-in and Elements.
Drop-in
Elements
Prerequisites: Perform the common drop-in steps.
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 payment session identifier, and use it to create an instance of a configuration object. In the configuration options, set flow to checkout and usage to subscription. To prompt Drop-in to display the combined subscription terms and save payment agreement, set showTermsOfSaleDisclosure to true.
1
let configuration = {
2
    sessionId: "d3941a36-6821-4d93-be23-6190226ae5f7",
3
    options: {
4
        "flow": "checkout",
5
        "showTermsOfSaleDisclosure": true,
6
        "usage": "subscription"
7
    },    
8
    ...
9
}
Copied!
Step three: Use the configuration object to initialize Drop-in.
1
let dropin = digitalriver.createDropIn(configuration);
Copied!
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, actively accept the terms 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. Digital River returns a unique Source in a chargeable state that is readyForStorage.
1
...
2
onSuccess: function (data) { doSometingWithTheSource(data) },
3
...
Copied!
Step five: Attach the Source to the Customer.
Step six: Attach the Source to the Checkout.
Step seven: Convert the Checkout to an Order.
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 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.
Once the customer provides the required SCA, a unique Source in a chargeable state is returned.
1
var payload = {
2
    "type": "creditCard",
3
    "sessionId": "ea03bf6f-84ef-4993-b1e7-b7d5ecf71d1f",
4
    "futureUse": true,
5
    "usage": "subscription",
6
    ...
7
    "mandate": {
8
        "terms": "Yes, please save this account and payment information for future purchases."
9
    }
10
}
11
​
12
digitalriver.createSource(payload).then(function(result) {
13
    if (result.error) {
14
        //handle errors
15
    } else {
16
        var source = result.source;
17
        //send source to back end
18
        sendToBackend(source);
19
    }
20
});
Copied!
Step three: Attach the Source to the Customer.
Step four: Attach the Source to the Checkout.
Step five: Convert the Checkout to an Order.
Customers retrieve credit card details during a subscription acquisition
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 supported?
Elements supported?
Yes
No
Yes
‌The following demonstrates how to build a workflow for this scenario using Elements. The key step is to call the authenticate source method.
Drop-in
Elements
Drop-in does not currently support retrieving stored payment methods. In order to handle this flow, use Elements.
Prerequisites: Refer to the Elements prerequisites section.
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, you'll need to determine whether SCA is required. To do this, configure and call the authenticateSource() method.
1
...
2
digitalriver.authenticateSource({
3
    "sessionId": "65b1e2c2-632c-4240-8897-195ca22ce108",
4
    "sourceId": "ee90c07c-5549-4a6b-aa5f-aabe29b1e97a",
5
    "sourceClientSecret": "ee90c07c-5549-4a6b-aa5f-aabe29b1e97a_51afe818-0e7f-46d7-8257-b209b20f4d8",
6
    "returnUrl": "https://returnurl.com"
7
}).then(function(data) {
8
​
9
});
10
...
Copied!
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.
Digital River returns a unique Source in a chargeable state.
Step four: Attach the Source to the Checkout.
Step five: Convert the Checkout to an Order.
Merchant-initiated auto renewals
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 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 both Drop-in and Elements support building workflows for mail order and telephone order (MOTO) transactions.
SCA required?
Drop-in supported?
Elements supported?
No
Yes
Yes
The following demonstrates how to build this workflow using Drop-in and Elements.
Drop-in
Elements
Prerequisites: Perform the common Drop-in steps.
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 to display only payment methods that are supported in MOTO transactions.
Step two: Retrieve the payment session identifier, and use it to create an instance of a configuration object. In the configuration options, set flow to checkout and usage to convenience.
1
let configuration = {
2
    sessionId: "d3941a36-6821-4d93-be23-6190226ae5f7",
3
    options: {
4
        flow: "checkout",
5
        usage: "convenience"
6
    }
7
    ...
8
}
Copied!
Step three: Use the configuration object to initialize Drop-in.
1
let dropin = digitalriver.createDropin(configuration);
Copied!
Step four: On the checkout page, specify a container to place Drop-in.
Drop-in 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.
1
...
2
onSuccess: function (data) { doSometingWithTheSource(data) },
3
...
Copied!
Step five: Attach the Source to the Checkout.
Step six: Convert the Checkout to an Order.
Prerequisites: Refer to the Elements prerequisites section.
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 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.
1
let payload = {
2
    "sessionId": "ea03bf6f-84ef-4993-b1e7-b7d5ecf71d1f",
3
    "futureUse": false,
4
    "usage": "convenience",
5
    ...
6
}
7
​
8
digitalriver.createSource(payload).then(function(result) {
9
    if(result.state === "chargeable") {
10
        sendToBackEnd(result);
11
    } else {
12
        doErrorScenario();
13
    }
14
});
Copied!
Step three: Attach the Source to a Checkout.
Step four: Convert the Checkout to an Order.
Account management flows
You can create flows that allow customers to manage 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.
Saving a credit card for future use
In this flow, customers use their account portal to save credit card information for use in future transactions.
SCA required?
Drop-in supported?
Elements supported?
Yes
Yes
Yes
The following demonstrates how to build this workflow using either Drop-in or Elements. We also provide a demo.
Drop-in
Elements
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. Set flow to managePaymentMethods and  specify a value for usage that identifies the likely future use of the payment source.
1
let configuration = {
2
    options: {
3
        "flow": "managePaymentMethods",
4
        "usage": "convenience",
5
        "showComplianceSection": true,
6
        "showTermsOfSaleDisclosure": false,
7
    },
8
    ...
9
}
Copied!
Step three: Use the configuration object to initialize Drop-in.
1
let dropin = digitalriver.createDropIn(configuration);
Copied!
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 payment agreement option and click the configurable add payment method button.
If the customer completes the SCA steps necessary to make the source chargeable, then the onSuccess method is called and a chargeable Source is returned that is readyForStorage.
1
...
2
onSuccess: function (data) { doSometingWithTheSource(data) },
3
...
Copied!
Step five: Attach the Source to the Customer.
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, 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.
1
var payload = {
2
    "type": "creditCard",
3
    "futureUse": true,
4
    "usage": "subscription",
5
    ...
6
    "mandate": {
7
        "terms": "Yes, please save this account and payment information for future purchases."
8
    }
9
}
10
​
11
digitalriver.createSource(payload).then(function(result) {
12
    if (result.error) {
13
        //handle errors
14
    } else {
15
        var source = result.source;
16
        //send source to back end
17
        sendToBackend(source);
18
    }
19
});
Copied!
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, customers use their account portal to update the expiration date or billing address on a 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 does not support interacting directly with saved payment methods‌
Prerequisites: Refer to the Elements prerequisites section.
Step one: Retrieve the customer's payment sources and display them to the customer.
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.
How to ensure SCA compliance
Testing scenarios
Last modified 24d ago
Copy link
Contents
Key settings and methods
Common Drop-in steps
Elements prerequisites
Purchase flows
One-off
Subscription
Mail order/telephone order
Account management flows
Saving a credit card for future use
Updating a credit card's expiration date or billing address