# Building payment workflows You can create Strong Customer Authentication (SCA) compliant workflows for [purchase transactions](#purchase-flows) and [account management](#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](https://docs.digitalriver.com/commerce-api/payments/payments-solutions/digitalriver.js), 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](https://docs.digitalriver.com/commerce-api/payments/payments-solutions/digitalriver.js), 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](https://docs.digitalriver.com/commerce-api/sources/using-the-source-identifier#secondary-payment-sources). Do not change the currency after you [apply the secondary source](https://docs.digitalriver.com/commerce-api/sources/using-the-source-identifier#creating-secondary-sources) to the cart.\ \ If you change the currency when calling `/v1/shoppers`, a [`409 Conflict`](https://app.gitbook.com/s/oUderMtztdH7OKDXmYbI/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](#account-management-flows).‌ 1. ​[Include DigitalRiver.js on your page](https://docs.digitalriver.com/commerce-api/payments-solutions/drop-in/drop-in-integration-guide#step-1-include-digitalriver-js-on-your-page). 2. ​[Include the Drop-in payments CSS file](https://docs.digitalriver.com/commerce-api/payments-solutions/drop-in/drop-in-integration-guide#step-2-include-the-hydrate-css-file). 3. [​Initialize DigitalRiver.js with your public key](https://docs.digitalriver.com/commerce-api/payments-solutions/drop-in/drop-in-integration-guide#step-3-initialize-digitalriver-js-with-your-public-key). 4. [​Create a container for Drop-in payments](https://docs.digitalriver.com/commerce-api/payments-solutions/drop-in/drop-in-integration-guide#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](#account-management-flows) scenario. ## Elements prerequisites You need to use payment sessions when using [DigitalRiver.js with elements](https://docs.digitalriver.com/commerce-api/payments/payments-solutions/digitalriver.js/quick-start) to build workflows. So ensure you've [completed the necessary migration](https://docs.digitalriver.com/commerce-api/shopper-apis/cart/payment-sessions#migrating-to-payment-sessions). We assume you are familiar with [creating and styling elements](https://docs.digitalriver.com/commerce-api/payments/payments-solutions/digitalriver.js/quick-start) and [capturing payment details](https://docs.digitalriver.com/commerce-api/resources/reference/digitalriver-object#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](#one-off), [subscription](#subscription), and [mail-order/telephone-order (MOTO)](https://docs.digitalriver.com/commerce-api/shopper-apis/cart/submitting-a-cart/initiating-a-charge#mail-order-telephone-order) transactions, Digital River supports [SCA-compliant](https://docs.digitalriver.com/commerce-api/payments/psd2-and-sca) workflows using Drop-in payments or [DigitalRiver.js elements](https://docs.digitalriver.com/commerce-api/payments/payments-solutions/digitalriver.js).‌ ### 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](https://docs.digitalriver.com/commerce-api/shopper-apis/cart/creating-or-updating-a-cart) with all tax, shipping, duty, and fee amounts in a final state and a [`chargeType` ](https://docs.digitalriver.com/commerce-api/shopper-apis/cart/submitting-a-cart/initiating-a-charge)that is `customer_initiated`. **Step two**: Retrieve the cart's [payment session identifier](https://docs.digitalriver.com/commerce-api/shopper-apis/cart/payment-sessions#enable-payment-sessions), and use it to set the sessionId in the Drop-in payments' [configuration object](https://docs.digitalriver.com/commerce-api/payments-solutions/drop-in/drop-in-integration-guide#step-5-configure-hydrate). In [`options`](https://docs.digitalriver.com/commerce-api/payments-solutions/drop-in/drop-in-integration-guide#drop-in-options), set `flow` to `checkout` and [`usage` ](https://docs.digitalriver.com/commerce-api/payments-solutions/drop-in/drop-in-integration-guide#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-solutions/drop-in/drop-in-integration-guide#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](https://docs.digitalriver.com/commerce-api/payments-solutions/drop-in/drop-in-integration-guide#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](https://docs.digitalriver.com/commerce-api/payments-solutions/drop-in/drop-in-integration-guide#step-7-place-drop-in-payments-on-your-cart-or-shopper-page) on your cart page. Drop-in payments render in the specified container. ![](https://2721412755-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzlYMEYC0GeLSgnsft6%2F-MIPzrS_3M4jRgxRngq0%2F-MIQBtmKnpAv1AHiqViS%2Fimage.png?alt=media\&token=b769c650-9b20-4bb3-b299-c4745169b953) Customers enter their credit card information and click the [configurable ](https://docs.digitalriver.com/commerce-api/payments-solutions/drop-in/drop-in-integration-guide#customizing-the-text-of-the-drop-in-payments-button)Pay Now button**.** If the customer completes the [SCA](https://docs.digitalriver.com/commerce-api/payments/psd2-and-sca), then the [`onSuccess` metho](https://docs.digitalriver.com/commerce-api/payments-solutions/drop-in/drop-in-integration-guide#onsuccess)d is called, and Digital River returns a unique source in a [chargeable state](https://docs.digitalriver.com/commerce-api/sources#source-state). ```javascript ... onSuccess: function (data) { doSometingWithTheSource(data) }, ... ``` **Step five**: [Attach the source to the cart](https://docs.digitalriver.com/commerce-api/sources#attaching-a-payment-method-to-an-order-or-cart). **Step six**: [Create the order by submitting the cart](https://docs.digitalriver.com/commerce-api/shopper-apis/cart/submitting-a-cart). {% endtab %} {% tab title="Elements" %} **Prerequisites**: Refer to the [Elements prerequisites](#elements-prerequisites) section. **Step one:** [Create a cart](https://docs.digitalriver.com/commerce-api/shopper-apis/cart/creating-or-updating-a-cart#creating-a-cart) with all tax, shipping, duty, and fee amounts in a final state and a [`chargeType` ](https://docs.digitalriver.com/commerce-api/shopper-apis/cart/submitting-a-cart/initiating-a-charge)that is `customer_initiated`. **Step two:** Retrieve the [payment session identifier](https://docs.digitalriver.com/commerce-api/shopper-apis/cart/payment-sessions#enable-payment-sessions) from the cart, and use it to configure the [`createSource()`](https://docs.digitalriver.com/commerce-api/resources/reference/digitalriver-object#createsource-element-sourcedata) method. The configuration object should also set `futureUse` to `false` and [`usage` ](https://docs.digitalriver.com/commerce-api/resources/reference/digitalriver-object#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](https://docs.digitalriver.com/commerce-api/sources#source-state) is returned once the method is called and the shopper provides the required SCA. **Step three:** [Attach the source to a cart](https://docs.digitalriver.com/commerce-api/sources/using-the-source-identifier#attaching-sources-to-a-cart). **Step four**: [Create the order by submitting the cart](https://docs.digitalriver.com/commerce-api/shopper-apis/cart/submitting-a-cart). {% 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](https://docs.digitalriver.com/commerce-api/shopper-apis/cart/creating-or-updating-a-cart) with all tax, shipping, duty, and fee amounts in a final state. Set [`chargeType` ](https://docs.digitalriver.com/commerce-api/shopper-apis/cart/submitting-a-cart/initiating-a-charge)to `customer_initiated` and `autoRenewal` to `true`. **Step two**: Retrieve the cart's [payment session identifier](https://docs.digitalriver.com/commerce-api/shopper-apis/cart/payment-sessions#enable-payment-sessions), and use it to set the sessionId in the [Drop-in payments](https://docs.digitalriver.com/commerce-api/payments/payments-solutions/drop-in) configuration object. In the configuration [`options`](https://docs.digitalriver.com/commerce-api/payments-solutions/drop-in/drop-in-integration-guide#drop-in-options), set `flow` to `checkout` and [`usage` ](https://docs.digitalriver.com/commerce-api/payments-solutions/drop-in/drop-in-integration-guide#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](https://docs.digitalriver.com/commerce-api/payments-solutions/drop-in/drop-in-integration-guide#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](https://docs.digitalriver.com/commerce-api/payments-solutions/drop-in/drop-in-integration-guide#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](https://docs.digitalriver.com/commerce-api/payments-solutions/drop-in/drop-in-integration-guide#step-7-mount-drop-in-payments-on-your-cart-or-account-management-page) on your cart page. The modal renders in the specified container. ![](https://2721412755-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzlYMEYC0GeLSgnsft6%2F-MIPzrS_3M4jRgxRngq0%2F-MIQH3GPgeWCdoUe7xHZ%2Fimage.png?alt=media\&token=6c46a41c-edcd-4ccf-89be-e6d354d34e3d) Customers enter their credit card information, actively accept the save payment agreement, and click the [configurable](https://docs.digitalriver.com/commerce-api/payments-solutions/drop-in/drop-in-integration-guide#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](https://docs.digitalriver.com/commerce-api/payments-solutions/drop-in/drop-in-integration-guide#onsuccess)d is called, and Digital River returns a unique Source in a [chargeable state](https://docs.digitalriver.com/commerce-api/sources#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](#elements-prerequisites) section. Your flow must also display the storage terms and allow shoppers to save their payment information. **Step one:** [Create a cart](https://docs.digitalriver.com/commerce-api/shopper-apis/cart/creating-or-updating-a-cart#creating-a-cart) with all tax, shipping, duty, and fee amounts in a final state. **Step two:** Retrieve the [payment session identifier](https://docs.digitalriver.com/commerce-api/shopper-apis/cart/payment-sessions) and use it to configure the [`createSource()`](https://docs.digitalriver.com/commerce-api/resources/reference/digitalriver-object#creating-sources) method. The configuration object should also set `futureUse` to `true` and [`usage` ](https://docs.digitalriver.com/commerce-api/resources/reference/digitalriver-object#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](https://docs.digitalriver.com/commerce-api/sources/using-the-source-identifier#attaching-sources-to-customers). **Step four:** [Attach the source to the cart](https://docs.digitalriver.com/commerce-api/sources/using-the-source-identifier#attaching-sources-to-a-cart). **Step five**: [Create the order by submitting the cart](https://docs.digitalriver.com/commerce-api/shopper-apis/cart/submitting-a-cart). {% 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](https://docs.digitalriver.com/commerce-api/sources/retrieving-sources#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](https://docs.digitalriver.com/commerce-api/resources/reference/elements). {% endtab %} {% tab title="Elements" %} **Prerequisites**: Refer to the [Elements prerequisites](#elements-prerequisites) section. **Step one:** [Create a cart](https://docs.digitalriver.com/commerce-api/shopper-apis/cart/creating-or-updating-a-cart) with all tax, shipping, duty, and fee amounts in a final state. The [`chargeType` ](https://docs.digitalriver.com/commerce-api/shopper-apis/cart/submitting-a-cart/initiating-a-charge)should be `customer_initiated`. **Step two:** [Retrieve the customer's payment sources](https://docs.digitalriver.com/commerce-api/sources/retrieving-sources#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()`](https://docs.digitalriver.com/commerce-api/resources/reference/digitalriver-object#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](https://docs.digitalriver.com/commerce-api/payments/sources/using-the-source-identifier). **Step five:** [Create the order by submitting the cart](https://docs.digitalriver.com/commerce-api/shopper-apis/cart/submitting-a-cart). {% endtab %} {% endtabs %} ### Subscription You can create [SCA-compliant](https://docs.digitalriver.com/commerce-api/payments/psd2-and-sca) 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](https://docs.digitalriver.com/commerce-api/payments/supported-payment-methods) 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](https://docs.digitalriver.com/commerce-api/shopper-apis/cart/creating-or-updating-a-cart#creating-a-cart) with an [authenticated customer](https://app.gitbook.com/s/oUderMtztdH7OKDXmYbI/commerce-api-reference-guide/api-structure/api-keys), and all tax, shipping, duty, and fee amounts are in a final state. Set [`chargeType` ](https://docs.digitalriver.com/commerce-api/shopper-apis/cart/submitting-a-cart/initiating-a-charge)to [`customer_initiate`](https://docs.digitalriver.com/commerce-api/shopper-apis/cart/submitting-a-cart/initiating-a-charge) and `autoRenewal` to `true`. **Step two**: Retrieve the [payment session identifier](https://docs.digitalriver.com/commerce-api/shopper-apis/cart/payment-sessions#enable-payment-sessions) from the cart, and use it to set the `sessionId` in the [Drop-in payments configuration object](https://docs.digitalriver.com/commerce-api/payments-solutions/drop-in/drop-in-integration-guide#step-5-configure-hydrate). In [`options`](https://docs.digitalriver.com/commerce-api/payments-solutions/drop-in/drop-in-integration-guide#drop-in-options), set `flow` to `checkout` and [`usage` ](https://docs.digitalriver.com/commerce-api/payments-solutions/drop-in/drop-in-integration-guide#specifying-a-sources-future-use)to `convenience`, and (to prompt Drop-in payments to display the save payment option) [`showTermsOfSaleDisclosure` ](https://docs.digitalriver.com/commerce-api/payments-solutions/drop-in/drop-in-integration-guide#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](https://docs.digitalriver.com/commerce-api/payments-solutions/drop-in/drop-in-integration-guide#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](https://docs.digitalriver.com/commerce-api/payments-solutions/drop-in/drop-in-integration-guide#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](https://docs.digitalriver.com/commerce-api/payments-solutions/drop-in/drop-in-integration-guide#customizing-the-drop-in-button-text) Pay Now button**.** If the shopper completes the necessary [SCA](https://docs.digitalriver.com/commerce-api/payments/psd2-and-sca) steps, then the [`onSucess` method](https://docs.digitalriver.com/commerce-api/payments-solutions/drop-in/drop-in-integration-guide#the-onsuccess-event-returns-the-source) is called an,d Digital River returns a unique source in a [chargeable state](https://docs.digitalriver.com/commerce-api/sources#source-state) that is [`readyForStorage`](https://docs.digitalriver.com/commerce-api/payments-solutions/drop-in/drop-in-integration-guide#onsuccess). ```javascript ... onSuccess: function (data) { doSometingWithTheSource(data) }, ... ``` **Step five**: [Attach the source to the shopper](https://docs.digitalriver.com/commerce-api/sources#attaching-a-payment-method-to-a-customer-or-payment-option). **Step six**: [Create the order by submitting the cart](https://docs.digitalriver.com/commerce-api/shopper-apis/cart/submitting-a-cart). {% endtab %} {% tab title="Elements" %} **Prerequisites**: Refer to the [Elements prerequisites](#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](https://docs.digitalriver.com/commerce-api/shopper-apis/cart/creating-or-updating-a-cart#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`](https://docs.digitalriver.com/commerce-api/shopper-apis/cart/submitting-a-cart/initiating-a-charge) 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](https://docs.digitalriver.com/commerce-api/shopper-apis/cart/payment-sessions#enable-payment-sessions), and use it to configure the [`createSource()`](https://docs.digitalriver.com/commerce-api/resources/reference/digitalriver-object#creating-sources) method. The configuration object should also set `futureUse` to `true` and [`usage` ](https://docs.digitalriver.com/commerce-api/payments-solutions/drop-in/drop-in-integration-guide#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](https://docs.digitalriver.com/commerce-api/sources#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](https://docs.digitalriver.com/commerce-api/sources#attaching-a-source-to-a-payment-option). **Step four**: [Attach the shopper to the cart.](https://docs.digitalriver.com/commerce-api/sources#attaching-source-to-a-customer) **Step five:** [Create the order by submitting the cart](https://docs.digitalriver.com/commerce-api/shopper-apis/cart/submitting-a-cart). {% 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](https://docs.digitalriver.com/commerce-api/payments/payments-solutions/drop-in) does not currently support retrieving stored payment methods. To handle this flow, use [Elements](https://docs.digitalriver.com/commerce-api/resources/reference/elements). {% endtab %} {% tab title="Elements" %} **Prerequisites**: Refer to the [Elements prerequisites](#elements-prerequisites) section. **Step one**: [Create a cart](https://docs.digitalriver.com/commerce-api/shopper-apis/cart/creating-or-updating-a-cart#creating-a-cart) with an [authenticated customer](https://app.gitbook.com/s/oUderMtztdH7OKDXmYbI/commerce-api-reference-guide/api-structure/api-keys), and all tax, shipping, duty, and fee amounts are in a final state. Set [`chargeType` ](https://docs.digitalriver.com/commerce-api/shopper-apis/cart/submitting-a-cart/initiating-a-charge)to [`customer_initiate`](https://docs.digitalriver.com/commerce-api/shopper-apis/cart/submitting-a-cart/initiating-a-charge) and `autoRenewal` to `true`. **Step two:** [Retrieve the shopper's payment sources](https://docs.digitalriver.com/commerce-api/sources/retrieving-sources#obtain-a-shoppers-sources) and display them to the shopper during the checkout process. **Step three**: Configure and call the [`authenticateSource()`](https://docs.digitalriver.com/commerce-api/resources/reference/digitalriver-object#authenticating-sources) method if the shopper uses a saved payment method. For details, refer to [Authenticating sources](https://docs.digitalriver.com/commerce-api/resources/reference/digitalriver-object#authenticating-sources) on the [DigitalRiver object](https://docs.digitalriver.com/commerce-api/resources/reference/digitalriver-object) 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](https://docs.digitalriver.com/commerce-api/sources#attaching-a-payment-method-to-an-order-or-cart). **Step five:** [Create the order by submitting the cart](https://docs.digitalriver.com/commerce-api/shopper-apis/cart/submitting-a-cart). {% 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 ](https://docs.digitalriver.com/commerce-api/payments/psd2-and-sca)is not required for transactions where shoppers provide payment details by mail, fax, or telephone. But both [Drop-in payments](https://docs.digitalriver.com/commerce-api/payments/payments-solutions/drop-in) and Elements support building workflows for [mail order and telephone order](https://docs.digitalriver.com/commerce-api/shopper-apis/cart/submitting-a-cart/initiating-a-charge#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](https://docs.digitalriver.com/commerce-api/shopper-apis/cart/creating-or-updating-a-cart#creating-a-cart) with a [`chargeType` ](https://docs.digitalriver.com/commerce-api/shopper-apis/cart/submitting-a-cart/initiating-a-charge)of [`moto` ](https://docs.digitalriver.com/commerce-api/shopper-apis/cart/submitting-a-cart/initiating-a-charge#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](https://docs.digitalriver.com/commerce-api/payments-solutions/drop-in/drop-in-integration-guide#configuring-payment-methods-within-drop-in-payments). In `options`, set [`flow` ](#purchase-flows)to `checkout` and [`usage` ](https://docs.digitalriver.com/commerce-api/payments-solutions/drop-in/drop-in-integration-guide#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](https://docs.digitalriver.com/commerce-api/payments-solutions/drop-in/drop-in-integration-guide#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 ](https://docs.digitalriver.com/commerce-api/payments-solutions/drop-in/drop-in-integration-guide#customizing-the-text-of-the-drop-in-payments-button)Pay Now button. If the payment is authorized, then the [`onSuccess` method](https://docs.digitalriver.com/commerce-api/payments-solutions/drop-in/drop-in-integration-guide#onsuccess) is called, and Digital River returns a unique source in a [`chargeable` state](https://docs.digitalriver.com/commerce-api/sources#source-state). ```javascript ... onSuccess: function (data) { doSometingWithTheSource(data) }, ... ``` **Step five**: [Attach the source to the cart](https://docs.digitalriver.com/commerce-api/sources#attaching-a-payment-method-to-an-order-or-cart). **Step six**: [Create the order by submitting the cart](https://docs.digitalriver.com/commerce-api/shopper-apis/cart/submitting-a-cart). {% endtab %} {% tab title="Elements" %} **Prerequisites**: Refer to the [Elements prerequisites](#elements-prerequisites) section. **Step one**: [Create a cart](https://docs.digitalriver.com/commerce-api/shopper-apis/cart/creating-or-updating-a-cart#creating-a-cart) with a [charge type](https://docs.digitalriver.com/commerce-api/shopper-apis/cart/submitting-a-cart/initiating-a-charge) 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()`](https://docs.digitalriver.com/commerce-api/resources/reference/digitalriver-object#creating-sources) method. The configuration object should also set `futureUse` to `false` and [`usage` ](https://docs.digitalriver.com/commerce-api/resources/reference/digitalriver-object#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](https://docs.digitalriver.com/commerce-api/sources#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](https://docs.digitalriver.com/commerce-api/sources#attaching-a-payment-method-to-an-order-or-cart). **Step five:** [Create the order by submitting the cart](https://docs.digitalriver.com/commerce-api/shopper-apis/cart/submitting-a-cart). {% endtab %} {% endtabs %} ## Account management flows You can create flows that allow customers to manage [recurring payment methods](https://docs.digitalriver.com/commerce-api/payments/supported-payment-methods) through their account portal. In these account management flows you only need to adhere to [SCA regulations](https://docs.digitalriver.com/commerce-api/payments/psd2-and-sca) 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`](https://docs.digitalriver.com/commerce-api/payments-solutions/drop-in/drop-in-integration-guide#configuring-payment-methods-within-drop-in-payments), set `flow` to `managePaymentMethods` and specify a value for [`usage`](https://docs.digitalriver.com/commerce-api/payments-solutions/drop-in/drop-in-integration-guide#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](https://docs.digitalriver.com/commerce-api/payments-solutions/drop-in/drop-in-integration-guide#using-drop-in-payments-within-your-cart-flow). **Step four**: Specify[ a container to place Drop-in payments](https://docs.digitalriver.com/commerce-api/payments-solutions/drop-in/drop-in-integration-guide#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. ![](https://2721412755-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzlYMEYC0GeLSgnsft6%2F-MIQ_oduue0fHFwxTaDP%2F-MIQbDSvfXux9rmGOUr4%2Fimage.png?alt=media\&token=87299f95-2b04-4434-91ee-b58c48d3e9d5) Shoppers enter their credit card information, select the save payment agreement option, and click the [configurable](https://docs.digitalriver.com/commerce-api/payments-solutions/drop-in/drop-in-integration-guide#customizing-the-text-of-the-drop-in-payments-button) add payment method button. If the shopper completes the necessary [SCA](https://docs.digitalriver.com/commerce-api/payments/psd2-and-sca) steps, then the [`onSucess` method](https://docs.digitalriver.com/commerce-api/payments-solutions/drop-in/drop-in-integration-guide#the-onsuccess-event-returns-the-source) is called, and Digital River returns a unique source in a [chargeable state](https://docs.digitalriver.com/commerce-api/sources#source-state) that is [`readyForStorage`](https://docs.digitalriver.com/commerce-api/payments-solutions/drop-in/drop-in-integration-guide#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](#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` ](https://docs.digitalriver.com/commerce-api/payments-solutions/drop-in/drop-in-integration-guide#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](https://docs.digitalriver.com/commerce-api/sources#source-state) is returned. **Step three:** [Attach the source to the shopper](https://docs.digitalriver.com/commerce-api/sources#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](#elements-prerequisites) section. **Step one:** [Retrieve the shopper's payment sources](https://docs.digitalriver.com/commerce-api/sources/retrieving-sources#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](https://docs.digitalriver.com/commerce-api/resources/reference/digitalriver-object#updating-sources). {% endtab %} {% endtabs %}