Building payment workflows

Learn how to create SCA-compliant workflows using Drop-in payments or Elements.

Using Drop-in payments or Elements, you can create Strong Customer Authentication (SCA) compliant workflows for purchase transactions and account management.

Whatever payment solution you use, all SCA requirements are managed by Digital River. Two-factor authentication is handled by our authenticate source method. 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 key settings and methods for 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 the checkout's chargeType to customer_initiated. If you're using Drop-in payments, use the createDropIn() method's configurable options to set flow to checkout and usage to convenience. With DigitalRiver.js with elements, 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 payments is not supported. Instead, you'll need to use the authenticateSource() method.

Click to enlarge image

Common Drop-in payments steps

For any workflow that uses Drop-in payments, whether it's intended to handle 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 payments.

Elements prerequisites

If you're using Elements to build purchase workflows, complete the necessary migration to payment sessions. We assume you are familiar with creating and styling elements and capturing payment details.

Purchase flows

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

One-off

‌One-off workflows allow customers to enter, save, and retrieve their payment information while making one-time purchases.

Customers enter their payment information

‌In this one-off flow, customers supply their payment information but don't save it to their account.

SCA required?	Drop-in payments supported?	Elements supported?
Yes	Yes	Yes

Drop-in payments

Prerequisites: Perform the common Drop-in payments 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 checkout's payment session identifier, and use it to set sessionId in the configuration object. In options, set flow to checkout and usage to convenience.

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

Step three: Pass the configuration object to the create Drop-in method.

let dropin = digitalriver.createDropin(configuration);

Step four: Drop-in payments are rendered in the designated container on your checkout page.

Customers enter their payment information and click the configurable pay now button.

If customers complete any SCA that may be required, onSuccess returns a source.

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

Step five: Attach the Source to the Checkout.

Step six: Convert the Checkout to an Order.

Elements

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 assign it to sessionId in the createSource() method's configuration object. You should also set futureUse to false and usage to convenience.

let payload = {
    "sessionId": "ea03bf6f-84ef-4993-b1e7-b7d5ecf71d1f",
    "futureUse": false,
    "usage": "convenience",
    ...
}

digitalriver.createSource(payload).then(function(result) {
    if(result.state === "chargeable") {
        sendToBackEnd(result);
    } else {
        doErrorScenario();
    }
});

After the method is called and customers complete any required SCA, a unique source is returned.

Step three: Attach the Source to the Checkout.

Step four: Convert the Checkout to an Order.

Customers save their payment information

In this one-off flow, customers enter payment information and save it to their account.

SCA required?	Drop-in payments supported?	Elements supported?
Yes	Yes	Yes

Drop-in payments

Prerequisites: Perform the common Drop-in payments 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 checkout's payment session identifier and use it to set sessionId in the Drop-in payments' configuration object. You should also use options to set flow to checkout, usage to convenience, and showSavePaymentAgreement to true.

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

Step three: Pass the configuration object to the create Drop-in method.

let dropin = digitalriver.createDropIn(configuration);

Step four: Drop-in payments are rendered in the designated container on your checkout page.

Customers enter their credit card information, actively accept the save payment agreement and click the configurable pay now button.

If customers complete any SCA that may be required, onSuccess returns a source that is readyForStorage.

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

Step five: Attach the Source to the Customer.

Step six: Attach the Source to the Checkout.

Step seven: Convert the Checkout to an Order.

Elements

Prerequisites: Refer to the Elements prerequisites section. Your flow also needs to display the storage terms and allow customers to save 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 assign it to sessionId in the createSource() method's configuration object. You should also set futureUse to true and usage to convenience. Use mandate.terms to pass the save payment agreement that the customer accepts.

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);
    }
});

After the method is called and customers complete any required SCA, a unique source 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 payment information

In this one-off purchase flow, customers select a payment method 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

Drop-in payments do not currently support retrieving saved payment methods. To handle this flow, use Elements.

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

Step three: If the customer uses a saved payment method, you must determine whether SCA is required. To do this, configure and call the authenticateSource() method. For details, refer to Authenticating sources on the DigitalRiver object page.

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

});
...

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 or retrieve a recurring payment method during subscription acquisitions and set up workflows for merchant-initiated autorenewals.

SCA is required for subscription acquisitions but not merchant-initiated auto-renewals.

Customers enter and save their payment 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 payments supported?	Elements supported?
Yes	Yes	Yes

Drop-in payments

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 checkout's payment session identifier, and use it to set sessionId in the configuration object. In options, set flow to checkout, usage to subscription, and showTermsOfSaleDisclosure to true.

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

Step three: Pass the configuration object to the create Drop-in method.

let dropin = digitalriver.createDropIn(configuration);

Step four: Drop-in payments are rendered in the designated container on your checkout page.

Customers must enter their payment information, actively accept the terms and click the configurable pay now button.

If customers complete any SCA that may be required, onSuccess returns a source that is readyForStorage.

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

Step five: Attach the Source to the Customer.

Step six: Attach the Source to the Checkout.

Step seven: Convert the Checkout to an Order.

Elements

Prerequisites: Refer to the Elements prerequisites section. At some point during the flow, you also need to display the subscription's terms, save the 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 assign it to sessionId in the createSource() method's configuration object. You should also set futureUse to true and usage to subscription. Use mandate.terms to pass the save payment agreement that the customer accepts.

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);
    }
});

After the method is called and customers complete any required SCA, a unique source 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 saved payments 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.

‌The key step is to call the authenticate source method.

SCA required?	Drop-in payments supported?	Elements supported?
Yes	No	Yes

Drop-in payments

Drop-in payments does not currently support retrieving stored payment methods. To handle this flow, use Elements.

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: Configure and call the authenticateSource() method if the customer uses a saved payment method. For details, refer to Authenticating sources on the DigitalRiver object page.

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

});
...

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 a subscription's auto-renewal. Although this type of workflow doesn't require SCA, you should ensure you correctly handle auto-renewing subscriptions.

SCA required?	Drop-in payments supported?	Elements supported?
No	N/A	N/A

Mail order/telephone order

SCA is not required for transactions where customers provide payment details by mail, fax, or telephone. However, both Drop-in payments and Elements support building workflows for mail order and telephone order (MOTO) transactions.

SCA required?	Drop-in payments supported?	Elements supported?
No	Yes	Yes

Drop-in payments

Prerequisites: Perform the common Drop-in payments 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 payments to display only payment methods supported in MOTO transactions.

Step two: Retrieve the checkout's payment session identifier, and use it to set sessionId in the Drop-in payments' configuration object. In options, set flow to checkout and usage to convenience.

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

Step three: Pass the configuration object to the create Drop-in method.

let dropin = digitalriver.createDropin(configuration);

Step four: Drop-in payments are rendered in the designated container on your checkout page.

The merchant's representative enters the customer's credit card information and clicks the configurable pay now button. If the payment is authorized, then onSuccess returns a unique source in a chargeable state.

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

Step five: Attach the Source to the Checkout.

Step six: Convert the Checkout to an Order.

Elements

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 assign it to sessionId in the createSource() method's configuration object. You should also set futureUse to false and usage to convenience.

let payload = {
    "sessionId": "ea03bf6f-84ef-4993-b1e7-b7d5ecf71d1f",
    "futureUse": false,
    "usage": "convenience",
    ...
}

digitalriver.createSource(payload).then(function(result) {
    if(result.state === "chargeable") {
        sendToBackEnd(result);
    } else {
        doErrorScenario();
    }
});

After the method is called and customers complete any required SCA, a unique source is returned.

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 recurring 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, attempt to identify the intended use of the source. This increases the probability that future transactions will be approved.

You're not required to do SCA when updating a credit card's expiration date or billing address.

Saving a credit card for future use

Customers use their account portal to save payment information for future transactions in this flow.

SCA required?	Drop-in payments supported?	Elements supported?
Yes	Yes	Yes

Drop-in payments

Prerequisites: Perform the common drop-in steps.

Step one: On the page where customers manage their payment methods, use the configuration object's options to set flow to managePaymentMethods and specify a value for usage that identifies the likely future use of the payment.

If customers are replacing an active subscription's recurring billing instrument, make sure you set usage to subscription and showTermsofSaleDisclosure to true. This prompts Drop-in payments to display a recurring billing agreement and forces customers to accept it.

Because this is a managePaymentMethods flow, and there's no payment session to reference, you shouldn't provide a sessionId. As a result, you'll need to pass the billing information you collect from customers in billingAddress.\

Step three: Pass the configuration object to the create Drop-in method.

let dropin = digitalriver.createDropIn(configuration);

Step four: Drop-in payments are rendered in the designated container on your checkout page.

Customers enter their payment information, select the save payment agreement option and click the configurable add payment method button.

If customers complete any SCA that may be required, onSuccess returns a source that is readyForStorage.

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

Step five: Attach the Source to the Customer.

Elements

Prerequisites: Refer to the Elements prerequisites section. You must display the save payment agreement and acquire the customer's acceptance.

Step one: Once a customer selects the option to save a payment method and agrees to the displayed terms, use the createSource() method's configuration object to set futureUse to true.

Make sure you also assign a value to usage that identifies the future use of the payment source and passes 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, customers use their account portal to update their saved credit card's expiration date or billing address.

SCA required?	Drop-in payments supported?	Elements supported?
No	No	Yes

Drop-in payments

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

Elements

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 customer's updated expiration date or billing address and pass it to the update source method.