# Building payment workflows You can create Strong Customer Authentication (SCA) compliant workflows for [purchase transactions](/commerce-api/payments/building-your-workflows.md#purchase-flows) and [account management](/commerce-api/payments/building-your-workflows.md#account-management-flows). When building workflows that use Drop-in payments, you'll need to perform some [common initial steps](#common-drop-in-steps) before proceeding to the workflow's specific steps.‌ For workflows using [DigitalRiver.js with elements](/commerce-api/payments/payments-solutions/digitalriver.js.md), you must also complete some [prerequisites](#elements-prerequisites). Each purchase and account management workflow has some [key settings and methods](#common-drop-in-steps). Whether you are using Drop-in payments or [DigitalRiver.js with elements](/commerce-api/payments/payments-solutions/digitalriver.js.md), Digital River automatically manages any SCA requirements. Our authenticate source method handles two-factor authentication. Our card acquirers use the [3-D Secure](https://en.wikipedia.org/wiki/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 a secondary source is in the cart. Specify the correct currency when creating a [secondary payment source](/commerce-api/payments/sources/using-the-source-identifier.md#secondary-payment-sources). Do not change the currency after you [apply the secondary source](/commerce-api/payments/sources/using-the-source-identifier.md#creating-secondary-sources) to the cart.\ \ If you change the currency when calling `/v1/shoppers`, a [`409 Conflict`](https://docs.digitalriver.com/commerce-api-references/warnings-and-error-codes/error-codes/error-codes-for-shopper-apis/409-conflict) response contains specific information about what triggered the failure. In this instance, one of the currencies in the cart is not supported. {% code title="Error" %} ```json { "errors": { "error": [ { "relation": "https://developers.digitalriver.com/v1/shoppers/ShoppersResource", "code": "invalid-request", "description": "One or more sources in the cart does not support locale {Locale} and currency {Currency}." } ] } } ``` {% endcode %} * You can't use the store credit to buy subscription products, pre-order products, or products on backorder. Additionally, you can't link more than one store credit source to an order, as multiple secondary sources are not currently supported. ## Common Drop-in payment steps You must perform the following steps for any workflow that uses Drop-in payments, whether built for [purchases ](#purchase-flows)or [account management](/commerce-api/payments/building-your-workflows.md#account-management-flows).‌ 1. ​[Include DigitalRiver.js on your page](/commerce-api/payments/payments-solutions/drop-in/drop-in-integration-guide.md#step-1-include-digitalriver-js-on-your-page). 2. ​[Include the Drop-in payments CSS file](/commerce-api/payments/payments-solutions/drop-in/drop-in-integration-guide.md#step-2-include-the-hydrate-css-file). 3. [​Initialize DigitalRiver.js with your public key](/commerce-api/payments/payments-solutions/drop-in/drop-in-integration-guide.md#step-3-initialize-digitalriver-js-with-your-public-key). 4. [​Create a container for Drop-in payments](/commerce-api/payments/payments-solutions/drop-in/drop-in-integration-guide.md#step-4-create-a-drop-in-payments-container). Once you've completed these initial steps, you can perform those specific to your desired [purchase](#purchase-flows) or [account management](/commerce-api/payments/building-your-workflows.md#account-management-flows) scenario. ## Elements prerequisites You need to use payment sessions when using [DigitalRiver.js with elements](/commerce-api/payments/payments-solutions/digitalriver.js/quick-start.md) to build workflows. So ensure you've [completed the necessary migration](/commerce-api/shopper-apis/cart/payment-sessions.md#migrating-to-payment-sessions). We assume you are familiar with [creating and styling elements](/commerce-api/payments/payments-solutions/digitalriver.js/quick-start.md) and [capturing payment details](/commerce-api/resources/reference/digitalriver-object.md#digitalriver-createsource-element-sourcedata). Once you've completed these prerequisites, you can perform the steps specific to your desired [purchase ](#purchase-flows)or [account management](#account-management-flows) scenario. ## Purchase Flows For almost all [one-off](/commerce-api/payments/building-your-workflows.md#one-off), [subscription](/commerce-api/payments/building-your-workflows.md#subscription), and [mail-order/telephone-order (MOTO)](/commerce-api/shopper-apis/cart/submitting-a-cart/initiating-a-charge.md#mail-order-telephone-order) transactions, Digital River supports [SCA-compliant](/commerce-api/payments/psd2-and-sca.md) workflows using Drop-in payments or [DigitalRiver.js elements](/commerce-api/payments/payments-solutions/digitalriver.js.md).‌ ### One-off ‌You can develop workflows that allow customers to [enter](#credit-card-details-entered-by-customer-during-checkout), [save](#credit-card-details-saved-by-customer-during-checkout), and [retrieve ](#customer-selects-saved-credit-card-during-checkout)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 accounts. | SCA required? | Drop-in payments supported? | Elements supported? | | ------------- | --------------------------- | ------------------- | | Yes | Yes | Yes | {% tabs %} {% tab title="Drop-in payments" %} **Prerequisites**: Perform the [common Drop-in payments steps](#common-drop-in-steps). **Step one**: [Create a cart](/commerce-api/shopper-apis/cart/creating-or-updating-a-cart.md) with all tax, shipping, duty, and fee amounts in a final state and a [`chargeType` ](/commerce-api/shopper-apis/cart/submitting-a-cart/initiating-a-charge.md)that is `customer_initiated`. **Step two**: Retrieve the cart's [payment session identifier](/commerce-api/shopper-apis/cart/payment-sessions.md#enable-payment-sessions), and use it to set the sessionId in the Drop-in payments' [configuration object](/commerce-api/payments/payments-solutions/drop-in/drop-in-integration-guide.md#step-5-configure-hydrate). In [`options`](/commerce-api/payments/payments-solutions/drop-in/drop-in-integration-guide.md#drop-in-options), set `flow` to `checkout` and [`usage` ](/commerce-api/payments/payments-solutions/drop-in/drop-in-integration-guide.md#specifying-a-sources-future-use)to `convenience`, and (to prompt Drop-in payments to display the save payment option) [`showSavePaymentAgreement` ](https://docs.digitalriver.com/commerce-api/payments/pages/-M4QkPmjkcIVqKR6tT5J#optional.-allowing-the-customer-to-save-their-payment-details)to `true`. ```javascript let configuration = { sessionId: "d3941a36-6821-4d93-be23-6190226ae5f7", options: { flow: "checkout", usage: "convenience" } ... } ``` **Step three**: Use the configuration object to [instantiate Drop-in Payments](/commerce-api/payments/payments-solutions/drop-in/drop-in-integration-guide.md#step-6-allow-the-shopper-to-interact-with-hydrate). ```javascript let dropin = digitalriver.createDropin(configuration); ``` **Step four**: Specify[ a container to place Drop-in payments](/commerce-api/payments/payments-solutions/drop-in/drop-in-integration-guide.md#step-7-place-drop-in-payments-on-your-cart-or-shopper-page) on your cart page. Drop-in payments render in the specified container. ![](/files/-MIQBtmKnpAv1AHiqViS) Customers enter their credit card information and click the [configurable ](/commerce-api/payments/payments-solutions/drop-in/drop-in-integration-guide.md#customizing-the-text-of-the-drop-in-payments-button)Pay Now button**.** If the customer completes the [SCA](/commerce-api/payments/psd2-and-sca.md), then the [`onSuccess` metho](/commerce-api/payments/payments-solutions/drop-in/drop-in-integration-guide.md#onsuccess)d is called, and Digital River returns a unique source in a [chargeable state](/commerce-api/payments/sources.md#source-state). ```javascript ... onSuccess: function (data) { doSometingWithTheSource(data) }, ... ``` **Step five**: [Attach the source to the cart](/commerce-api/payments/sources.md#attaching-a-payment-method-to-an-order-or-cart). **Step six**: [Create the order by submitting the cart](/commerce-api/shopper-apis/cart/submitting-a-cart.md). {% endtab %} {% tab title="Elements" %} **Prerequisites**: Refer to the [Elements prerequisites](#elements-prerequisites) section. **Step one:** [Create a cart](/commerce-api/shopper-apis/cart/creating-or-updating-a-cart.md#creating-a-cart) with all tax, shipping, duty, and fee amounts in a final state and a [`chargeType` ](/commerce-api/shopper-apis/cart/submitting-a-cart/initiating-a-charge.md)that is `customer_initiated`. **Step two:** Retrieve the [payment session identifier](/commerce-api/shopper-apis/cart/payment-sessions.md#enable-payment-sessions) from the cart, and use it to configure the [`createSource()`](/commerce-api/resources/reference/digitalriver-object.md#createsource-element-sourcedata) method. The configuration object should also set `futureUse` to `false` and [`usage` ](/commerce-api/resources/reference/digitalriver-object.md#specifying-a-sources-future-use)to `convenience`. ```javascript 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(); } }); ``` \ A unique Source in a [chargeable state](/commerce-api/payments/sources.md#source-state) is returned once the method is called and the shopper provides the required SCA. **Step three:** [Attach the source to a cart](/commerce-api/payments/sources/using-the-source-identifier.md#attaching-sources-to-a-cart). **Step four**: [Create the order by submitting the cart](/commerce-api/shopper-apis/cart/submitting-a-cart.md). {% endtab %} {% endtabs %} #### 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 | {% tabs %} {% tab title="Drop-in payments" %} **Prerequisites**: Perform the [common Drop-in payments steps](#common-drop-in-steps). **Step one**: [Create a cart](/commerce-api/shopper-apis/cart/creating-or-updating-a-cart.md) with all tax, shipping, duty, and fee amounts in a final state. Set [`chargeType` ](/commerce-api/shopper-apis/cart/submitting-a-cart/initiating-a-charge.md)to `customer_initiated` and `autoRenewal` to `true`. **Step two**: Retrieve the cart's [payment session identifier](/commerce-api/shopper-apis/cart/payment-sessions.md#enable-payment-sessions), and use it to set the sessionId in the [Drop-in payments](/commerce-api/payments/payments-solutions/drop-in.md) configuration object. In the configuration [`options`](/commerce-api/payments/payments-solutions/drop-in/drop-in-integration-guide.md#drop-in-options), set `flow` to `checkout` and [`usage` ](/commerce-api/payments/payments-solutions/drop-in/drop-in-integration-guide.md#specifying-a-sources-future-use)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](/commerce-api/payments/payments-solutions/drop-in/drop-in-integration-guide.md#specifying-a-sources-future-use). ```javascript let configuration = { sessionId: "d3941a36-6821-4d93-be23-6190226ae5f7", options: { "showSavePaymentAgreement": true, "usage": "subscription" }, ... } let dropin = digitalriver.createDropIn(configuration); ``` **Step three**: Use the configuration object to [instantiate Drop-in payments](/commerce-api/payments/payments-solutions/drop-in/drop-in-integration-guide.md#step-6-allow-the-shopper-to-interact-with-hydrate). ```javascript let dropin = digitalriver.createDropIn(configuration); ``` **Step four**: [Specify a container to place Drop-in payments](/commerce-api/payments/payments-solutions/drop-in/drop-in-integration-guide.md#step-7-mount-drop-in-payments-on-your-cart-or-account-management-page) on your cart page. The modal renders in the specified container. ![](/files/-MIQH3GPgeWCdoUe7xHZ) Customers enter their credit card information, actively accept the save payment agreement, and click the [configurable](/commerce-api/payments/payments-solutions/drop-in/drop-in-integration-guide.md#customizing-the-text-of-the-drop-in-payments-button) Pay Now button. If the customer completes the SCA steps necessary to make the source chargeable, then the [`onSuccess` metho](/commerce-api/payments/payments-solutions/drop-in/drop-in-integration-guide.md#onsuccess)d is called, and Digital River returns a unique Source in a [chargeable state](/commerce-api/payments/sources.md#source-state). ```javascript ... onSuccess: function (data) { doSometingWithTheSource(data) }, ... ``` **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. {% endtab %} {% tab title="Elements" %} **Prerequisites**: Refer to the [Elements prerequisites](/commerce-api/payments/building-your-workflows.md#elements-prerequisites) section. Your flow must also display the storage terms and allow shoppers to save their payment information. **Step one:** [Create a cart](/commerce-api/shopper-apis/cart/creating-or-updating-a-cart.md#creating-a-cart) with all tax, shipping, duty, and fee amounts in a final state. **Step two:** Retrieve the [payment session identifier](/commerce-api/shopper-apis/cart/payment-sessions.md) and use it to configure the [`createSource()`](/commerce-api/resources/reference/digitalriver-object.md#creating-sources) method. The configuration object should also set `futureUse` to `true` and [`usage` ](/commerce-api/resources/reference/digitalriver-object.md#specifying-a-sources-future-use)to `convenience`. Use `mandate.terms` to pass the save payment agreement that the customer accepts. ```javascript 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 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](/commerce-api/payments/sources/using-the-source-identifier.md#attaching-sources-to-customers). **Step four:** [Attach the source to the cart](/commerce-api/payments/sources/using-the-source-identifier.md#attaching-sources-to-a-cart). **Step five**: [Create the order by submitting the cart](/commerce-api/shopper-apis/cart/submitting-a-cart.md). {% endtab %} {% endtabs %} #### Customers retrieve their payment information In this one-off purchase flow, the customers select a credit card they previously saved to their account. The key step is to call the [authenticate source method](/commerce-api/payments/sources/retrieving-sources.md#obtain-a-shoppers-sources). | SCA required? | Drop-in payments supported? | Elements supported? | | ------------- | --------------------------- | ------------------- | | Yes | No | Yes | {% tabs %} {% tab title="Drop-in payments" %} Drop-in payments do not currently support retrieving stored payment methods. To handle this flow, use [Elements](/commerce-api/resources/reference/elements.md). {% endtab %} {% tab title="Elements" %} **Prerequisites**: Refer to the [Elements prerequisites](/commerce-api/payments/building-your-workflows.md#elements-prerequisites) section. **Step one:** [Create a cart](/commerce-api/shopper-apis/cart/creating-or-updating-a-cart.md) with all tax, shipping, duty, and fee amounts in a final state. The [`chargeType` ](/commerce-api/shopper-apis/cart/submitting-a-cart/initiating-a-charge.md)should be `customer_initiated`. **Step two:** [Retrieve the customer's payment sources](/commerce-api/payments/sources/retrieving-sources.md#obtain-a-shoppers-sources) and display them to the shopper during checkout. **Step three**: If the shopper selects a saved payment method, you must determine whether SCA is required. To do this, configure and call the [`authenticateSource()`](/commerce-api/resources/reference/digitalriver-object.md#authenticating-sources) method. For details, refer to Authenticating sources on the DigitalRiver object ```javascript ... 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 cart](/commerce-api/payments/sources/using-the-source-identifier.md). **Step five:** [Create the order by submitting the cart](/commerce-api/shopper-apis/cart/submitting-a-cart.md). {% endtab %} {% endtabs %} ### Subscription You can create [SCA-compliant](/commerce-api/payments/psd2-and-sca.md) workflows allowing customers to [save](#customer-enters-credit-card-details-during-subscription-acquisition-checkout) or [retrieve](#customer-saves-credit-card-details-during-subscription-acquisition-checkout) a [recurring payment method](/commerce-api/payments/supported-payment-methods.md) during subscription acquisitions. You can also set up workflows for [merchant-initiated autorenewals](#merchant-initiated-auto-renewals). #### Shopper 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 | {% tabs %} {% tab title="Drop-in payments" %} **Prerequisites**: Perform the [common Drop-in payments steps](#common-drop-in-steps). **Step one**: [Create a cart](/commerce-api/shopper-apis/cart/creating-or-updating-a-cart.md#creating-a-cart) with an [authenticated customer](https://docs.digitalriver.com/commerce-api-references/commerce-api-reference-guide/api-structure/api-keys), and all tax, shipping, duty, and fee amounts are in a final state. Set [`chargeType` ](/commerce-api/shopper-apis/cart/submitting-a-cart/initiating-a-charge.md)to [`customer_initiate`](/commerce-api/shopper-apis/cart/submitting-a-cart/initiating-a-charge.md) and `autoRenewal` to `true`. **Step two**: Retrieve the [payment session identifier](/commerce-api/shopper-apis/cart/payment-sessions.md#enable-payment-sessions) from the cart, and use it to set the `sessionId` in the [Drop-in payments configuration object](/commerce-api/payments/payments-solutions/drop-in/drop-in-integration-guide.md#step-5-configure-hydrate). In [`options`](/commerce-api/payments/payments-solutions/drop-in/drop-in-integration-guide.md#drop-in-options), set `flow` to `checkout` and [`usage` ](/commerce-api/payments/payments-solutions/drop-in/drop-in-integration-guide.md#specifying-a-sources-future-use)to `convenience`, and (to prompt Drop-in payments to display the save payment option) [`showTermsOfSaleDisclosure` ](/commerce-api/payments/payments-solutions/drop-in/drop-in-integration-guide.md#show-terms-of-sale-disclosure)to `true`. ```javascript let configuration = { sessionId: "d3941a36-6821-4d93-be23-6190226ae5f7", options: { "flow": "checkout", "showTermsOfSaleDisclosure": true, "usage": "subscription" }, ... } ``` **Step three**: Use the configuration object to [instantiate Drop-in payments](/commerce-api/payments/payments-solutions/drop-in/drop-in-integration-guide.md#step-6-allow-the-shopper-to-interact-with-hydrate). ```javascript let dropin = digitalriver.createDropIn(configuration); ``` **Step four**: Specify[ a container to place Drop-in payments](/commerce-api/payments/payments-solutions/drop-in/drop-in-integration-guide.md#step-7-place-drop-in-payments-on-your-cart-or-shopper-page) on your cart page. Drop-in renders in the specified container.
Shoppers must enter their credit card information and click the [configurable](/commerce-api/payments/payments-solutions/drop-in/drop-in-integration-guide.md#customizing-the-drop-in-button-text) Pay Now button**.** If the shopper completes the necessary [SCA](/commerce-api/payments/psd2-and-sca.md) steps, then the [`onSucess` method](/commerce-api/payments/payments-solutions/drop-in/drop-in-integration-guide.md#the-onsuccess-event-returns-the-source) is called an,d Digital River returns a unique source in a [chargeable state](/commerce-api/payments/sources.md#source-state) that is [`readyForStorage`](/commerce-api/payments/payments-solutions/drop-in/drop-in-integration-guide.md#onsuccess). ```javascript ... onSuccess: function (data) { doSometingWithTheSource(data) }, ... ``` **Step five**: [Attach the source to the shopper](/commerce-api/payments/sources.md#attaching-a-payment-method-to-a-customer-or-payment-option). **Step six**: [Create the order by submitting the cart](/commerce-api/shopper-apis/cart/submitting-a-cart.md). {% endtab %} {% tab title="Elements" %} **Prerequisites**: Refer to the [Elements prerequisites](/commerce-api/payments/building-your-workflows.md#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**: [Create a cart](/commerce-api/shopper-apis/cart/creating-or-updating-a-cart.md#creating-a-cart) with an authenticated customer, and all tax, shipping, duty, and fee amounts are in a final state. Set `chargeType` to [`customer_initiate`](/commerce-api/shopper-apis/cart/submitting-a-cart/initiating-a-charge.md) 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](/commerce-api/shopper-apis/cart/payment-sessions.md#enable-payment-sessions), and use it to configure the [`createSource()`](/commerce-api/resources/reference/digitalriver-object.md#creating-sources) method. The configuration object should also set `futureUse` to `true` and [`usage` ](/commerce-api/payments/payments-solutions/drop-in/drop-in-integration-guide.md#specifying-a-sources-future-use)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](/commerce-api/payments/sources.md#source-state) is returned. ```javascript var payload = { "type": "creditCard", "sessionId": "ea03bf6f-84ef-4993-b1e7-b7d5ecf71d1f", "futureUse": true, "usage": "subscription", ... "mandate": { "terms": "Yes, 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 the source to back end sendToBackend(source); } }); ``` **Step three:** [Attach the source to the shopper](/commerce-api/payments/sources.md#attaching-a-source-to-a-payment-option). **Step four**: [Attach the shopper to the cart.](/commerce-api/payments/sources.md#attaching-source-to-a-customer) **Step five:** [Create the order by submitting the cart](/commerce-api/shopper-apis/cart/submitting-a-cart.md). {% endtab %} {% endtabs %} #### Shoppers retrieve saved payment during a subscription acquisition In this flow, shoppers 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 | {% tabs %} {% tab title="Drop-in payments" %} [Drop-in payments](/commerce-api/payments/payments-solutions/drop-in.md) does not currently support retrieving stored payment methods. To handle this flow, use [Elements](/commerce-api/resources/reference/elements.md). {% endtab %} {% tab title="Elements" %} **Prerequisites**: Refer to the [Elements prerequisites](/commerce-api/payments/building-your-workflows.md#elements-prerequisites) section. **Step one**: [Create a cart](/commerce-api/shopper-apis/cart/creating-or-updating-a-cart.md#creating-a-cart) with an [authenticated customer](https://docs.digitalriver.com/commerce-api-references/commerce-api-reference-guide/api-structure/api-keys), and all tax, shipping, duty, and fee amounts are in a final state. Set [`chargeType` ](/commerce-api/shopper-apis/cart/submitting-a-cart/initiating-a-charge.md)to [`customer_initiate`](/commerce-api/shopper-apis/cart/submitting-a-cart/initiating-a-charge.md) and `autoRenewal` to `true`. **Step two:** [Retrieve the shopper's payment sources](/commerce-api/payments/sources/retrieving-sources.md#obtain-a-shoppers-sources) and display them to the shopper during the checkout process. **Step three**: Configure and call the [`authenticateSource()`](/commerce-api/resources/reference/digitalriver-object.md#authenticating-sources) method if the shopper uses a saved payment method. For details, refer to [Authenticating sources](/commerce-api/resources/reference/digitalriver-object.md#authenticating-sources) on the [DigitalRiver object](/commerce-api/resources/reference/digitalriver-object.md) page. ```javascript ... 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 a cart](/commerce-api/payments/sources.md#attaching-a-payment-method-to-an-order-or-cart). **Step five:** [Create the order by submitting the cart](/commerce-api/shopper-apis/cart/submitting-a-cart.md). {% endtab %} {% endtabs %} #### 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 ](/commerce-api/payments/psd2-and-sca.md)is not required for transactions where shoppers provide payment details by mail, fax, or telephone. But both [Drop-in payments](/commerce-api/payments/payments-solutions/drop-in.md) and Elements support building workflows for [mail order and telephone order](/commerce-api/shopper-apis/cart/submitting-a-cart/initiating-a-charge.md#mail-order-telephone-order) (MOTO) transactions. | SCA required? | Drop-in payments supported? | Elements supported? | | ------------- | --------------------------- | ------------------- | | No | No | Yes | {% tabs %} {% tab title="Drop-in payments" %} **Prerequisites**: Perform the [common Drop-in payments steps](#common-drop-in-steps). **Step one**: [Create a cart](/commerce-api/shopper-apis/cart/creating-or-updating-a-cart.md#creating-a-cart) with a [`chargeType` ](/commerce-api/shopper-apis/cart/submitting-a-cart/initiating-a-charge.md)of [`moto` ](/commerce-api/shopper-apis/cart/submitting-a-cart/initiating-a-charge.md#merchant-initiated)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](/commerce-api/payments/payments-solutions/drop-in/drop-in-integration-guide.md#configuring-payment-methods-within-drop-in-payments). In `options`, set [`flow` ](#purchase-flows)to `checkout` and [`usage` ](/commerce-api/payments/payments-solutions/drop-in/drop-in-integration-guide.md#specifying-a-sources-future-use)to `convenience`. ```javascript let configuration = { sessionId: "d3941a36-6821-4d93-be23-6190226ae5f7", options: { flow: "checkout", usage: "convenience" } ... } ``` **Step three**: Use the configuration object to instantiate Drop-in payments. ```javascript let dropin = digitalriver.createDropin(configuration); ``` **Step four**: Specify[ a container to place Drop-in payments](/commerce-api/payments/payments-solutions/drop-in/drop-in-integration-guide.md#step-7-place-drop-in-payments-on-your-cart-or-shopper-page) on your checkout page. The modal window renders in the specified container.
The merchant's representative enters the customer's credit card information and clicks the [configurable ](/commerce-api/payments/payments-solutions/drop-in/drop-in-integration-guide.md#customizing-the-text-of-the-drop-in-payments-button)Pay Now button. If the payment is authorized, then the [`onSuccess` method](/commerce-api/payments/payments-solutions/drop-in/drop-in-integration-guide.md#onsuccess) is called, and Digital River returns a unique source in a [`chargeable` state](/commerce-api/payments/sources.md#source-state). ```javascript ... onSuccess: function (data) { doSometingWithTheSource(data) }, ... ``` **Step five**: [Attach the source to the cart](/commerce-api/payments/sources.md#attaching-a-payment-method-to-an-order-or-cart). **Step six**: [Create the order by submitting the cart](/commerce-api/shopper-apis/cart/submitting-a-cart.md). {% endtab %} {% tab title="Elements" %} **Prerequisites**: Refer to the [Elements prerequisites](/commerce-api/payments/building-your-workflows.md#elements-prerequisites) section. **Step one**: [Create a cart](/commerce-api/shopper-apis/cart/creating-or-updating-a-cart.md#creating-a-cart) with a [charge type](/commerce-api/shopper-apis/cart/submitting-a-cart/initiating-a-charge.md) 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()`](/commerce-api/resources/reference/digitalriver-object.md#creating-sources) method. The configuration object should also set `futureUse` to `false` and [`usage` ](/commerce-api/resources/reference/digitalriver-object.md#specifying-a-sources-future-use)to `convenience`. Once the method is invoked and payment is authorized, a unique Source is returned in a [`chargeable` state](/commerce-api/payments/sources.md#source-state). ```javascript 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(); } }); ``` **Step four:** [Attach the source to a cart](/commerce-api/payments/sources.md#attaching-a-payment-method-to-an-order-or-cart). **Step five:** [Create the order by submitting the cart](/commerce-api/shopper-apis/cart/submitting-a-cart.md). {% endtab %} {% endtabs %} ## Account management flows You can create flows that allow customers to manage [recurring payment methods](/commerce-api/payments/supported-payment-methods.md) through their account portal. In these account management flows you only need to adhere to [SCA regulations](/commerce-api/payments/psd2-and-sca.md) when [saving a customer's credit card for future use](#saving-a-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](#updating-a-credit-cards-billing-address). ### Saving a credit card C, customers can use their account portal to save credit card information for future transactions. | SCA required? | Drop-in payments supported? | Elements supported? | | | ------------- | --------------------------- | ------------------- | - | | Yes | Yes | Yes | | {% tabs %} {% tab title="Drop-in payments" %} **Drop-in paymentsPrerequisites**: Perform the [common Drop-in payments steps](#common-drop-in-steps). **Step one**: Go to a page in your integration where customers manage their payment methods. **Step two**: In the [configuration object's `options`](/commerce-api/payments/payments-solutions/drop-in/drop-in-integration-guide.md#configuring-payment-methods-within-drop-in-payments), set `flow` to `managePaymentMethods` and specify a value for [`usage`](/commerce-api/payments/payments-solutions/drop-in/drop-in-integration-guide.md#specifying-a-sources-future-use) that identifies the potential future use of the payment source. ```javascript let configuration = { options: { "flow": "managePaymentMethods", "usage": "subscription" }, ... } let dropin = digitalriverpayments.createDropIn(configuration); ``` **Step three**: Use the configuration object to [instantiate Drop-in payments](/commerce-api/payments/payments-solutions/drop-in/drop-in-integration-guide.md#using-drop-in-payments-within-your-cart-flow). **Step four**: Specify[ a container to place Drop-in payments](/commerce-api/payments/payments-solutions/drop-in/drop-in-integration-guide.md#step-7-place-drop-in-payments-on-your-cart-or-shopper-page) on the account management page. The modal window renders in the specified container. ![](/files/-MIQbDSvfXux9rmGOUr4) Shoppers enter their credit card information, select the save payment agreement option, and click the [configurable](/commerce-api/payments/payments-solutions/drop-in/drop-in-integration-guide.md#customizing-the-text-of-the-drop-in-payments-button) add payment method button. If the shopper completes the necessary [SCA](/commerce-api/payments/psd2-and-sca.md) steps, then the [`onSucess` method](/commerce-api/payments/payments-solutions/drop-in/drop-in-integration-guide.md#the-onsuccess-event-returns-the-source) is called, and Digital River returns a unique source in a [chargeable state](/commerce-api/payments/sources.md#source-state) that is [`readyForStorage`](/commerce-api/payments/payments-solutions/drop-in/drop-in-integration-guide.md#onsuccess). ```javascript ... onSuccess: function (data) { doSometingWithTheSource(data) }, ... ``` **Step six**: Attach the source to the shopper. {% endtab %} {% tab title="Elements" %} **Prerequisites**: Refer to the [Elements prerequisites](/commerce-api/payments/building-your-workflows.md#elements-prerequisites) section You also need to display the save payment agreement and acquire the customer's active acceptance. **Step one**: If 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` ](/commerce-api/payments/payments-solutions/drop-in/drop-in-integration-guide.md#specifying-a-sources-future-use)to identify the future use of the payment source and provide the `mandate.terms` that the customer agreed to on your storefront. ```javascript 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 shopper provides the required SCA, a Source in a [`chargeable` state](/commerce-api/payments/sources.md#source-state) is returned. **Step three:** [Attach the source to the shopper](/commerce-api/payments/sources.md#attaching-a-source-to-a-payment-option). {% endtab %} {% endtabs %} ### Updating a credit card's expiration date or billing address Customers use their account portal to update their saved credit card's expiration date or billing address in this flow. | SCA required? | Drop-in payments supported? | Elements supported? | | ------------- | --------------------------- | ------------------- | | No | No | Yes | {% tabs %} {% tab title="Drop-in payments" %} [Drop-in payments](#drop-in-payments) do not support interacting directly with saved payment methods.‌ {% endtab %} {% tab title="Elements" %} **Prerequisites**: Refer to the [Elements prerequisites](/commerce-api/payments/building-your-workflows.md#elements-prerequisites) section. **Step one:** [Retrieve the shopper's payment sources](/commerce-api/payments/sources/retrieving-sources.md#obtain-a-shoppers-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](/commerce-api/resources/reference/digitalriver-object.md#updating-sources). {% endtab %} {% endtabs %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.digitalriver.com/commerce-api/payments/building-your-workflows.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.