Building payment workflows

Search…
Learn how to create SCA-compliant workflows using Drop-in Payments and DigitalRiver.js with 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 Payments, you'll first need to perform some common, initial steps before proceeding to the workflow's specific steps.‌ For workflows using DigitalRiver.js with elements, to complete some prerequisites.
Each purchase and account management workflow has some key settings and methods. 
Whether you are using Drop-in Payments or DigitalRiver.js with elements, any 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. 
Limitations and constraints
Note the following limitations and constraints when building your payments workflow.
Do not change the currency when there is a secondary source in the cart. Specify the correct currency when creating a secondary payment source. After you apply the secondary source to the cart, do not change the currency.

If you change the currency when calling /v1/shoppers, a 409 Conflict response contains specific information about what triggered the failure. In this instance, one of the currencies in the cart is not supported.
Error
1
{
2
    "errors": {
3
        "error": [
4
            {
5
                "relation": "https://developers.digitalriver.com/v1/shoppers/ShoppersResource",
6
                "code": "invalid-request",
7
                "description": "One or more sources in the cart does not support locale {Locale} and currency {Currency}."
8
            }
9
        ]
10
    }
11
​
12
}
Copied!
At this time, you cannot use store credit to purchase a subscription product.
At this time, you cannot use store credit to pre-order a product.
At this time, you cannot use store credit to purchase a product on backorder.
At this time, you cannot attach more than one store credit source to an order. Multiple secondary sources are not supported.
Common Drop-in Payment steps
For any workflow that uses Drop-in Payments, whether it's a purchase or account management flow, you'll first need to perform the following steps.‌
1.​Include DigitalRiver.js on your page.
2.​Include the Drop-in Payments CSS file.
3.​​Initialize DigitalRiver.js with your public key.
4.​​Create a container for Drop-in Payments.
Once you've completed these steps, you can move on to the steps specific to your workflow scenario.
Elements prerequisites
When using DigitalRiver.js with 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.
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) transaction scenarios, Digital River supports SCA-compliant workflows that use either Drop-in Payments or DigitalRiver.js 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, s enter their credit card information during the checkout process.
SCA required?
Drop-in Payments supported?
Elements supported?
Yes
Yes
Yes
‌The following demonstrates how to build a workflow for this scenario using both Drop-in Payments and Elements. We also provide a demo. 
Drop-in Payments
DigitalRiver.js with elements
Prerequisites: Perform the common Drop-in Payments 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.  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 Payments.   
1
let dropin = digitalriver.createDropin(configuration);
Copied!
Step four: On your cart page, specify a container to place Drop-in Payments.
Drop-in Payments renders in the specified container.
Customers  enter their credit card information and click the configurable Pay Now button. 
If the customers 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!
A chargeable source is returned.
Step five: Attach the source to the cart. 
Step six: Create the order by submitting the cart.
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.
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 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.
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 Payments supported?
Elements supported?
Yes
Yes
Yes
The following demonstrates how to build workflows for this scenario using both Drop-in Payments and Elements. We also provide a demo. 
Drop-in Payments
DigitalRiver.js with elements
Prerequisites: Perform the common Drop-in Payments 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. In the configuration options, set flow to checkout and usage to convenience. To prompt Drop-in payments to display the save payment option, set showSavePaymentAgreement to true.
You should also configure the usage parameter. Doing so identifies the future use of the payment source. 
1
let configuration = {
2
    sessionId: "d3941a36-6821-4d93-be23-6190226ae5f7",
3
    options: {
4
        "showSavePaymentAgreement": true,
5
        "usage": "subscription"
6
    },
7
    ...
8
}
9
​
10
let dropin = digitalriver.createDropIn(configuration);
Copied!
Step three: Use the configuration object to initialize Drop-in Payments. 
1
let dropin = digitalriver.createDropIn(configuration);
Copied!
Step four: On your cart page, specify a container to place Drop-in Payments.
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. 
If the customers 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 shopper.
Step six: Attach the shopper to the cart.
Step seven: Create the order by submitting the cart.
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 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 source is returned. 
Step three: Attach the source to the customer.
Step four: Attach the source to the cart.
Step five: Create the order by submitting the cart.
Customers retrieve their credit card information
In this one-off purchase flow, the customers select a credit card 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
DigitalRiver.js with elements
​Drop-in Payments do not currently support retrieving stored payment methods. In order to handle this flow, use 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 customer'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.
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.
If authentication is successful, Digital River returns the Source in a chargeable state.
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​
​Shopper retrieves credit card details during subscription acquisition​
​Merchant-initiated auto renewals​
Shopper apply and save their credit card information during a subscription acquisition
In this flow, during the checkout process, shoppers use a credit card to simultaneously acquire an auto-renewing subscription and save their payment information.
SCA required?
Drop-in Payments supported?
Elements supported?
Yes
Yes
Yes
The following demonstrates how to build a workflow for this scenario using both Drop-in Payments and Elements.
Drop-in Payments
DigitalRiver.js with elements
Prerequisites: Perform the common Drop-in Payments 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.  When specifying options, set flow to checkout , showSavePaymenAgreement to true, and usage to subscription.
Step three: Use the configuration object to initialize Drop-in Payments.
1
let configuration = {
2
    sessionId: "d3941a36-6821-4d93-be23-6190226ae5f7",
3
    options: {
4
        "flow": "checkout",
5
        "showSavePaymentAgreement": true,
6
        "usage": "subscription"
7
    },
8
}
9
  
10
let dropin = digitalriverpayments.createDropIn(configuration);
Copied!
Step four: On your cart page, specify a container to place Drop-in Payments.
Drop-in renders in the specified container.
Shoppers 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 shopper completes the SCA steps necessary to make the source chargeable, then call the onSucess method.
1
...
2
onSuccess: function (data) { doSometingWithTheSource(data) },
3
...
Copied!
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.
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 a cart that contains an auto-renewing subscription and all tax, shipping, duty and fee amounts are in a final state.
Step two: If a shopper selects the option to save the payment method and agrees to the displayed terms, retrieve the payment session identifier from the cart, 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 shopper agreed to on your storefront. 
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!
Once the shopper provides the required SCA, a Source in a chargeable state is returned.
Step three: Attach the source to the shopper.
Step four: Attach the shopper to the cart.
Step five: 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 Payments
DigitalRiver.js with elements
Drop-in Payments does not currently support retrieving stored payment methods. In order to handle this flow, use Digital River with 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. 
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.
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 Payments 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 Payments supported?
Elements supported?
No
No
Yes
The following demonstrates how to build a workflow for this scenario using Elements.
Drop-in Payments
DigitalRiver.js with elements
For this flow type, you should use Element to capture credit card details. 
Prerequisites: Refer to the Elements prerequisites section. 
Step one: Create a cart with all tax, shipping, duty, and fee amounts 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.
For Drop-in PaymentsDrop-in Payments, 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.
SCA required?
Drop-in Payments supported?
Elements supported?
Text
Yes
Yes
Yes
​
The following demonstrates how to build a workflow for this scenario using both Drop-in Payments and Elements. We also provide a demo. 
Drop-in
DigitalRiver.js with  elements
Prerequisites: Perform the common Drop-in Payments 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. 
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. 
Step three: Use the configuration object to initialize Drop-in Payments.
1
let configuration = {
2
    options: {
3
        "flow": "managePaymentMethods",
4
        "usage": "subscription"
5
    },
6
    ...
7
}
8
  
9
let dropin = digitalriverpayments.createDropIn(configuration);
Copied!
Step four: On the account management page, specify a container to place Drop-in Payments.
Drop-in renders in the specified container.
Shoppers 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 shopper completes the SCA steps necessary to make the source chargeable, then call the onSucess method.
1
...
2
onSuccess: function (data) { doSometingWithTheSource(data) },
3
...
Copied!
A chargeable source is returned that is ready for storage. 
Step six: Attach the source to the shopper.
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 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. 
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 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 Payments supported?
Elements supported?
No
No
Yes
The following demonstrates how to build a workflow for this scenario using Elements.
Drop-in Payments
Digital River with elements
Drop-in Payments does not support interacting directly with saved payment methods‌
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 Payments supported?
Elements supported?
No
No
Yes
The following demonstrates how to build a workflow for this scenario using Elements.
Drop-in Payments
DigitalRiver.js with elements
Drop-in Payments does not support interacting directly with saved payment methods‌
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.
​