# Building payment workflows Using [Drop-in payments](/digital-river-api/payments/payment-integrations-1/drop-in.md) or [Elements](https://github.com/DigitalRiver/GitBook/blob/Digital-River-API/payments/payment-integrations-1/digitalriver.js), you can create [Strong Customer Authentication (SCA)](/digital-river-api/payments/psd2-and-sca.md) compliant workflows for [purchase transactions](#purchase-flows) and [account management](#account-management-flows). Whatever payment solution you use, all SCA requirements are managed by Digital River. Two-factor authentication is handled by our [authenticate source method](/digital-river-api/developer-resources/reference/digitalriver-object.md#authenticating-sources). 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. ## 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](#one-off) in which customers [save a new payment source to their account](#credit-card-details-saved-by-customer-during-checkout), you should set the checkout's [`chargeType`](/digital-river-api/integration-options/checkouts/creating-checkouts/initiating-a-charge.md) to `customer_initiated`. If you're using [Drop-in payments](/digital-river-api/payments/payment-integrations-1/drop-in.md), use the [`createDropIn()`](/digital-river-api/developer-resources/reference/digitalriver-object.md#creating-an-instance-of-drop-in) method's [configurable `options`](/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide.md#drop-in-options-1) to set [`flow`](/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide.md#flow) to `checkout` and [`usage`](/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide.md#specifying-a-sources-future-use) to `convenience`. With [DigitalRiver.js with elements](/digital-river-api/payments/payment-integrations-1/digitalriver.js/quick-start.md), use the [`createSource()`](/digital-river-api/developer-resources/reference/digitalriver-object.md#creating-sources) method's configuration object to set `futureUse` to `true` and [`usage`](/digital-river-api/developer-resources/reference/digitalriver-object.md#specifying-a-sources-future-use) to `convenience`. * When customers are [acquiring an auto-renewing subscription](#subscription), and decide to [retrieve a payment source saved to their account](#customer-saves-credit-card-details-during-subscription-acquisition-checkout), set the checkout's `chargeType` to `customer_initiated` and [`autoRenewal`](/digital-river-api/integration-options/checkouts/subscriptions/subscription-information-1.md#auto-renewal) to `true`. In this flow type, [Drop-in payments](/digital-river-api/payments/payment-integrations-1/drop-in.md) is not supported. Instead, you'll need to use the [`authenticateSource()`](/digital-river-api/developer-resources/reference/digitalriver-object.md#authenticating-sources) method. ![Click to enlarge image](/files/-McP6d_LWh2uQ8OIoLBM) ## Common Drop-in payments steps For any workflow that uses [Drop-in payments](/digital-river-api/payments/payment-integrations-1/drop-in.md), whether it's intended to handle [purchases](#purchase-flows) or [account management](#account-management-flows), you first need to perform the following steps: 1. ​[Include DigitalRiver.js on your page](/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide.md#step-1-include-digitalriver-js-on-your-page). 2. ​[Include the Drop-in CSS file](/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide.md#step-2-include-the-hydrate-css-file). 3. ​[Initialize DigitalRiver.js with your public key](/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide.md#step-3-initialize-digitalriver-js-with-your-public-key). 4. ​[Create a container for Drop-in payments](/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide.md#step-4-create-a-container-for-drop-in). ## Elements prerequisites If you're using [Elements](/digital-river-api/payments/payment-integrations-1/digitalriver.js/quick-start.md) to build [purchase](#purchase-flows) workflows, [complete the necessary migration to payment sessions](/digital-river-api/integration-options/checkouts/creating-checkouts/payment-sessions.md#migrating-to-payment-sessions). We assume you are familiar with [creating and styling elements](/digital-river-api/developer-resources/reference/elements.md) and [capturing payment details](/digital-river-api/payments/payment-integrations-1/digitalriver.js/quick-start.md). ## Purchase flows For almost all [one-off](#one-off), [subscription](#subscription), and [mail-order/telephone-order (MOTO)](#mail-order-telephone-order) transactions, Digital River supports [SCA-compliant](/digital-river-api/payments/psd2-and-sca.md) workflows using [Drop-in payments](/digital-river-api/payments/payment-integrations-1/drop-in.md) or [Elements](/digital-river-api/payments/payment-integrations-1/digitalriver.js/quick-start.md).‌ ### One-off ‌One-off workflows 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-time purchases. #### Customers enter their payment information ‌In this [one-off](#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 | {% tabs %} {% tab title="Drop-in payments " %} **Prerequisites**: Perform the [common Drop-in payments steps](#common-drop-in-steps). **Step one**: [Build a checkout](/digital-river-api/integration-options/checkouts/creating-checkouts.md) with all tax, shipping, duty, and fee amounts in a final state and a [`chargeType`](/digital-river-api/integration-options/checkouts/creating-checkouts/initiating-a-charge.md) that is `customer_initiated`. **Step two**: Retrieve the checkout's [payment session identifier](/digital-river-api/integration-options/checkouts/creating-checkouts.md#payment-session-identifier), and use it to set [`sessionId`](/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide.md#drop-in-options) in the[ configuration object](/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide.md#configuring-drop-in-payments). In `options`, set [`flow`](/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide.md#flow) to `checkout` and [`usage`](/digital-river-api/payments/payment-integrations-1/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**: Pass the configuration object to the [create Drop-in method](/digital-river-api/developer-resources/reference/digitalriver-object.md#creating-an-instance-of-drop-in). ```javascript let dropin = digitalriver.createDropin(configuration); ``` **Step four**: Drop-in payments are rendered in the designated container on your checkout page. ![](/files/-MHXtYQUmXN_yNMcE6Go) Customers enter their payment information and click the [configurable](/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide.md#customizing-the-text-of-the-drop-in-button) pay now button. If customers complete any [SCA](/digital-river-api/payments/psd2-and-sca.md) that may be required, [`onSuccess` ](/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide.md#onsuccess)returns a [source](https://www.digitalriver.com/docs/digital-river-api-reference/#tag/Sources). ```javascript ... onSuccess: function (data) { doSometingWithTheSource(data) }, ... ``` **Step five**: [Attach the Source to the Checkout](/digital-river-api/payments/payment-sources/using-the-source-identifier.md#attaching-sources-to-checkouts). **Step six**: [Convert the Checkout to an Order](/digital-river-api/order-management/creating-and-updating-an-order.md#creating-an-order-with-the-checkout-identifier). {% endtab %} {% tab title="Elements" %} **Prerequisites**: Refer to the [Elements prerequisites](#elements-prerequisites) section. **Step one:** [Build a checkout](/digital-river-api/integration-options/checkouts/creating-checkouts.md) with all tax, shipping, duty, and fee amounts in a final state and a [`chargeType`](/digital-river-api/integration-options/checkouts/creating-checkouts/initiating-a-charge.md) that is `customer_initiated`. **Step two:** Retrieve the [payment session identifier ](/digital-river-api/integration-options/checkouts/creating-checkouts.md#payment-session-identifier)and assign it to `sessionId` in the [`createSource()`](/digital-river-api/developer-resources/reference/digitalriver-object.md#creating-sources) method's configuration object. You should also set `futureUse` to `false` and [`usage`](/digital-river-api/developer-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(); } }); ``` After the method is called and customers complete any required SCA, a unique [source](/digital-river-api/payments/payment-sources.md) is returned. **Step three:** [Attach the Source to the Checkout](/digital-river-api/payments/payment-sources/using-the-source-identifier.md#attaching-sources-to-checkouts). **Step four**: [Convert the Checkout to an Order](/digital-river-api/order-management/creating-and-updating-an-order.md#creating-an-order-with-the-checkout-identifier). {% endtab %} {% endtabs %} #### Customers save their payment information In this [one-off](#one-off) flow, customers enter payment information and save it to their account. | 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**: [Build a checkout](/digital-river-api/integration-options/checkouts/creating-checkouts.md) with a [registered customer](/digital-river-api/integration-options/checkouts/creating-checkouts/using-the-checkout-identifier.md#registered-checkouts-or-invoices) and all tax, shipping, duty and fee amounts in a final state. The [`chargeType`](/digital-river-api/integration-options/checkouts/creating-checkouts/initiating-a-charge.md) should be `customer_initiated`. **Step two**: Retrieve the checkout's [payment session identifier](/digital-river-api/integration-options/checkouts/creating-checkouts.md#payment-session-identifier) and use it to set [`sessionId`](/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide.md#drop-in-options) in the [Drop-in payments' configuration object](/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide.md#configuring-drop-in-payments). You should also use `options` to set [`flow`](/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide.md#flow) to `checkout`, [`usage`](/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide.md#specifying-a-sources-future-use) to `convenience`, and [`showSavePaymentAgreement`](/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide.md#show-save-payment-agreement) to `true`. ```javascript 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](/digital-river-api/developer-resources/reference/digitalriver-object.md#creating-an-instance-of-drop-in). ```javascript let dropin = digitalriver.createDropIn(configuration); ``` **Step four**: Drop-in payments are rendered in the designated container on your checkout page. ![](/files/-MHYNdRu6NN3PO_MQKsr) Customers enter their credit card information, actively accept the save payment agreement and click the [configurable](/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide.md#customizing-the-text-of-the-drop-in-button) pay now button. If customers complete any [SCA](/digital-river-api/payments/psd2-and-sca.md) that may be required, [`onSuccess` ](/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide.md#onsuccess)returns a [source](https://docs.digitalriver.com/digital-river-api-reference/2020-12-17/sources) that is [`readyForStorage`](/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide.md#onsuccess). ```javascript ... onSuccess: function (data) { doSometingWithTheSource(data) }, ... ``` **Step five**: [Attach the Source to the Customer](/digital-river-api/payments/payment-sources/using-the-source-identifier.md#attaching-sources-to-customers). **Step six**: [Attach the Source to the Checkout](/digital-river-api/payments/payment-sources/using-the-source-identifier.md#attaching-sources-to-checkouts). **Step seven**: [Convert the Checkout to an Order](/digital-river-api/order-management/creating-and-updating-an-order.md#creating-an-order-with-the-checkout-identifier). {% endtab %} {% tab title="Elements" %} **Prerequisites**: Refer to the [Elements prerequisites](#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](/digital-river-api/integration-options/checkouts/creating-checkouts.md) with a [registered customer](/digital-river-api/integration-options/checkouts/creating-checkouts/using-the-checkout-identifier.md#registered-checkouts-or-invoices) and all tax, shipping, duty and fee amounts in a final state. The [`chargeType`](/digital-river-api/integration-options/checkouts/creating-checkouts/initiating-a-charge.md) should be `customer_initiated`. **Step two:** Retrieve the [payment session identifier ](/digital-river-api/integration-options/checkouts/creating-checkouts.md#payment-session-identifier)and assign it to `sessionId` in the [`createSource()`](/digital-river-api/developer-resources/reference/digitalriver-object.md#creating-sources) method's configuration object. You should also set `futureUse` to `true` and [`usage`](/digital-river-api/developer-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); } }); ``` After the method is called and customers complete any required SCA, a unique [source](/digital-river-api/payments/payment-sources.md) is returned. **Step three:** [Attach the Source to the Customer](/digital-river-api/payments/payment-sources/using-the-source-identifier.md#attaching-sources-to-customers). **Step four**: [Attach the Source to the Checkout](/digital-river-api/payments/payment-sources/using-the-source-identifier.md#attaching-sources-to-checkouts). **Step five**: [Convert the Checkout to an Order](/digital-river-api/order-management/creating-and-updating-an-order.md#creating-an-order-with-the-checkout-identifier). {% endtab %} {% endtabs %} #### Customers retrieve their payment information In this [one-off purchase flow](#one-off), customers select a payment method they previously saved to their account. The key step is to call the [authenticate source method](/digital-river-api/developer-resources/reference/digitalriver-object.md#authenticating-sources). | SCA required? | Drop-in payments supported? | Elements supported? | | ------------- | --------------------------- | ------------------- | | Yes | No | Yes | {% tabs %} {% tab title="Drop-in payments" %} [Drop-in payments](/digital-river-api/payments/payment-integrations-1/drop-in.md) do not currently support retrieving saved payment methods. To handle this flow, use [Elements](/digital-river-api/developer-resources/reference/elements.md). {% endtab %} {% tab title="Elements" %} **Prerequisites**: Refer to the [Elements prerequisites](#elements-prerequisites) section. **Step one:** [Build a checkout](/digital-river-api/integration-options/checkouts/creating-checkouts.md) with a [registered customer](/digital-river-api/integration-options/checkouts/creating-checkouts/using-the-checkout-identifier.md#registered-checkouts-or-invoices) and all tax, shipping, duty and fee amounts in a final state. The [`chargeType`](/digital-river-api/integration-options/checkouts/creating-checkouts/initiating-a-charge.md) should be `customer_initiated`. **Step two:** [Retrieve the customer's payment sources](/digital-river-api/payments/payment-sources/retrieving-sources.md#obtain-a-customers-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()`](/digital-river-api/developer-resources/reference/digitalriver-object.md#authenticating-sources) method. For details, refer to [Authenticating sources](/digital-river-api/developer-resources/reference/digitalriver-object.md#authenticating-sources) on the [DigitalRiver object](/digital-river-api/developer-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 the Checkout](/digital-river-api/payments/payment-sources/using-the-source-identifier.md#attaching-a-source-to-a-customer). **Step five:** [Convert the Checkout to an Order](/digital-river-api/order-management/creating-and-updating-an-order.md#creating-an-order-with-the-checkout-identifier). {% endtab %} {% endtabs %} ### Subscription You can create [SCA-compliant](/digital-river-api/payments/psd2-and-sca.md) workflows that allow 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](/digital-river-api/payments/supported-payment-methods.md) during subscription acquisitions and set up workflows for [merchant-initiated autorenewals](#merchant-initiated-auto-renewals). {% hint style="warning" %} SCA is required for [subscription acquisitions](/digital-river-api/integration-options/checkouts/subscriptions/subscription-information-1.md#subscription-acquisition) but not [merchant-initiated](/digital-river-api/integration-options/checkouts/creating-checkouts/initiating-a-charge.md#merchant-initiated) auto-renewals. {% endhint %} #### 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 | {% tabs %} {% tab title="Drop-in payments" %} **Prerequisites**: Perform the [common drop-in steps](#common-drop-in-steps). **Step one**: [Build a checkout](/digital-river-api/integration-options/checkouts/creating-checkouts.md) with a [registered customer](/digital-river-api/integration-options/checkouts/creating-checkouts/using-the-checkout-identifier.md#registered-checkouts-or-invoices) and all tax, shipping, duty and fee amounts in a final state. Set [`chargeType`](/digital-river-api/integration-options/checkouts/creating-checkouts/initiating-a-charge.md) to `customer_initiated` and `autoRenewal` to `true`. **Step two**: Retrieve the checkout's [payment session identifier](/digital-river-api/integration-options/checkouts/creating-checkouts.md#payment-session-identifier), and use it to set [`sessionId`](/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide.md#drop-in-options) in the [configuration object](/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide.md#configuring-drop-in-payments). In [`options`](/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide.md#drop-in-options-1), set [`flow`](/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide.md#flow) to `checkout`, [`usage`](/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide.md#specifying-a-sources-future-use) to `subscription`, and [`showTermsOfSaleDisclosure`](/digital-river-api/payments/payment-integrations-1/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**: Pass the configuration object to the [create Drop-in method](/digital-river-api/developer-resources/reference/digitalriver-object.md#creating-an-instance-of-drop-in). ```javascript let dropin = digitalriver.createDropIn(configuration); ``` **Step four**: Drop-in payments are rendered in the designated container on your checkout page. ![](/files/-McQHV_b2KcnjKR6z-W7) Customers must enter their payment information, actively accept the terms and click the [configurable](/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide.md#customizing-the-text-of-the-drop-in-button) pay now button. If customers complete any [SCA](/digital-river-api/payments/psd2-and-sca.md) that may be required, [`onSuccess` ](/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide.md#onsuccess)returns a [source ](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/sources)that is [`readyForStorage`](/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide.md#onsuccess). ```javascript ... onSuccess: function (data) { doSometingWithTheSource(data) }, ... ``` **Step five:** [Attach the Source to the Customer](/digital-river-api/payments/payment-sources/using-the-source-identifier.md#attaching-sources-to-customers). **Step six**: [Attach the Source to the Checkout](/digital-river-api/payments/payment-sources/using-the-source-identifier.md#attaching-sources-to-checkouts). **Step seven**: [Convert the Checkout to an Order](/digital-river-api/order-management/creating-and-updating-an-order.md#creating-an-order-with-the-checkout-identifier). {% 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**: [Build a checkout](/digital-river-api/integration-options/checkouts/creating-checkouts.md) with a [registered customer](/digital-river-api/integration-options/checkouts/creating-checkouts/using-the-checkout-identifier.md#registered-checkouts-or-invoices) and all tax, shipping, duty and fee amounts in a final state. Set [`chargeType`](/digital-river-api/integration-options/checkouts/creating-checkouts/initiating-a-charge.md) 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 ](/digital-river-api/integration-options/checkouts/creating-checkouts.md#payment-session-identifier)and assign it to `sessionId` in the [`createSource()`](/digital-river-api/developer-resources/reference/digitalriver-object.md#creating-sources) method's configuration object. You should also set `futureUse` to `true` and [`usage`](/digital-river-api/developer-resources/reference/digitalriver-object.md#specifying-a-sources-future-use) to `subscription`. 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": "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](/digital-river-api/payments/payment-sources.md) is returned. **Step three:** [Attach the Source to the Customer](/digital-river-api/payments/payment-sources/using-the-source-identifier.md#attaching-sources-to-customers). **Step four:** [Attach the Source to the Checkout](/digital-river-api/payments/payment-sources/using-the-source-identifier.md#attaching-sources-to-checkouts). **Step five:** [Convert the Checkout to an Order](/digital-river-api/order-management/creating-and-updating-an-order.md#creating-an-order-with-the-checkout-identifier). {% endtab %} {% endtabs %} #### 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](/digital-river-api/developer-resources/reference/digitalriver-object.md#authenticating-sources). | SCA required? | Drop-in payments supported? | Elements supported? | | ------------- | --------------------------- | ------------------- | | Yes | No | Yes | {% tabs %} {% tab title="Drop-in payments" %} [Drop-in payments](/digital-river-api/payments/payment-integrations-1/drop-in.md) does not currently support retrieving stored payment methods. To handle this flow, use [Elements](/digital-river-api/developer-resources/reference/elements.md). {% endtab %} {% tab title="Elements" %} **Prerequisites**: Refer to the [Elements prerequisites](#elements-prerequisites) section. **Step one**: [Build a checkout](/digital-river-api/integration-options/checkouts/creating-checkouts.md) with a [registered customer](/digital-river-api/integration-options/checkouts/creating-checkouts/using-the-checkout-identifier.md#registered-checkouts-or-invoices) and all tax, shipping, duty and fee amounts in a final state. Set [`chargeType`](/digital-river-api/integration-options/checkouts/creating-checkouts/initiating-a-charge.md) to `customer_initiated` and `autoRenewal` to `true`. **Step two:** [Retrieve the customer's payment sources](/digital-river-api/payments/payment-sources/retrieving-sources.md#obtain-a-customers-sources) and display them to the customer during the checkout process. **Step three**: Configure and call the [`authenticateSource()`](/digital-river-api/developer-resources/reference/digitalriver-object.md#authenticating-sources) method if the customer uses a saved payment method. For details, refer to [Authenticating sources](/digital-river-api/developer-resources/reference/digitalriver-object.md#authenticating-sources) on the [DigitalRiver object](/digital-river-api/developer-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 the Checkout](/digital-river-api/payments/payment-sources/using-the-source-identifier.md#attaching-sources-to-checkouts). **Step five:** [Convert the Checkout to an Order](/digital-river-api/order-management/creating-and-updating-an-order.md#creating-an-order-with-the-checkout-identifier). {% endtab %} {% endtabs %} #### 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](/digital-river-api/payments/psd2-and-sca.md) 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](/digital-river-api/integration-options/checkouts/creating-checkouts/initiating-a-charge.md#mail-order-telephone-order) (MOTO) transactions. | SCA required? | Drop-in payments supported? | Elements supported? | | ------------- | --------------------------- | ------------------- | | No | Yes | Yes | {% tabs %} {% tab title="Drop-in payments" %} **Prerequisites**: Perform the [common Drop-in payments steps](#common-drop-in-steps). **Step one**: [Build a checkout](/digital-river-api/integration-options/checkouts/creating-checkouts.md) with a [`chargeType`](/digital-river-api/integration-options/checkouts/creating-checkouts/initiating-a-charge.md) of [`moto`](/digital-river-api/integration-options/checkouts/creating-checkouts/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](/digital-river-api/integration-options/checkouts/creating-checkouts.md#payment-session-identifier), and use it to set [`sessionId`](/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide.md#drop-in-options) in the [Drop-in payments' configuration object](/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide.md#configuring-drop-in-payments). In `options`, set [`flow`](/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide.md#flow) to `checkout` and [`usage`](/digital-river-api/payments/payment-integrations-1/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**: Pass the configuration object to the [create Drop-in method](/digital-river-api/developer-resources/reference/digitalriver-object.md#creating-an-instance-of-drop-in). ```javascript let dropin = digitalriver.createDropin(configuration); ``` **Step four**: Drop-in payments are rendered in the designated container on your checkout page. ![](/files/-McU7rOuiCu1kxWqKhiQ) The merchant's representative enters the customer's credit card information and clicks the [configurable](/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide.md#customizing-the-text-of-the-drop-in-button) pay now button. If the payment is authorized, then [`onSuccess` ](/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide.md#onsuccess)returns a unique [source ](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/sources)in a [`chargeable` state](/digital-river-api/payments/payment-sources.md#source-state). ```javascript ... onSuccess: function (data) { doSometingWithTheSource(data) }, ... ``` **Step five**: [Attach the Source to the Checkout](/digital-river-api/payments/payment-sources/using-the-source-identifier.md#attaching-sources-to-checkouts). **Step six**: [Convert the Checkout to an Order](/digital-river-api/order-management/creating-and-updating-an-order.md#creating-an-order-with-the-checkout-identifier). {% endtab %} {% tab title="Elements" %} **Prerequisites**: Refer to the [Elements prerequisites](#elements-prerequisites) section. **Step one**: [Build a checkout](/digital-river-api/integration-options/checkouts/creating-checkouts.md) with a [charge type](/digital-river-api/integration-options/checkouts/creating-checkouts/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 ](/digital-river-api/integration-options/checkouts/creating-checkouts.md#payment-session-identifier)and assign it to `sessionId` in the [`createSource()`](/digital-river-api/developer-resources/reference/digitalriver-object.md#creating-sources) method's configuration object. You should also set `futureUse` to `false` and [`usage`](/digital-river-api/developer-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(); } }); ``` After the method is called and customers complete any required SCA, a unique [source](/digital-river-api/payments/payment-sources.md) is returned. **Step three:** [Attach the Source to a Checkout](/digital-river-api/payments/payment-sources/using-the-source-identifier.md#attaching-sources-to-checkouts). **Step four**: [Convert the Checkout to an Order](/digital-river-api/order-management/creating-and-updating-an-order.md#creating-an-order-with-the-checkout-identifier). {% endtab %} {% endtabs %} ## Account management flows You can create flows that allow customers to manage [recurring payment methods](/digital-river-api/payments/supported-payment-methods.md) through their account portal. In these account management flows, you only need to adhere to [SCA regulations](/digital-river-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, 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](#updating-a-credit-cards-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 | {% tabs %} {% tab title="Drop-in payments" %} **Prerequisites**: Perform the [common drop-in steps](#common-drop-in-steps). **Step one**: On the page where customers manage their payment methods, use the [configuration object's](/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide.md#configuring-drop-in-payments) [`options`](/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide.md#drop-in-options-1) to set [`flow`](/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide.md#flow) to `managePaymentMethods` and specify a value for [`usage`](/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide.md#specifying-a-sources-future-use) 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`](/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide.md#show-save-payment-agreement) 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](/digital-river-api/integration-options/checkouts/creating-checkouts/payment-sessions.md) to reference, you shouldn't provide a [`sessionId`](/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide.md#drop-in-options). As a result, you'll need to pass the billing information you collect from customers in [`billingAddress`](/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide.md#billing-address).\\ **Step three**: Pass the configuration object to the [create Drop-in method](/digital-river-api/developer-resources/reference/digitalriver-object.md#creating-an-instance-of-drop-in). ```javascript let dropin = digitalriver.createDropIn(configuration); ``` **Step four**: Drop-in payments are rendered in the designated container on your checkout page. ![](/files/-MIKNQFD2v6t3f6YlDJJ) Customers enter their payment information, select the save payment agreement option and click the [configurable](/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide.md#customizing-the-text-of-the-drop-in-button) add payment method button. If customers complete any [SCA](/digital-river-api/payments/psd2-and-sca.md) that may be required, [`onSuccess` ](/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide.md#onsuccess)returns a [source](https://www.digitalriver.com/docs/digital-river-api-reference/#tag/Sources) that is [`readyForStorage`](/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide.md#onsuccess). ```javascript ... onSuccess: function (data) { doSometingWithTheSource(data) }, ... ``` **Step five**: [Attach the Source to the Customer](/digital-river-api/payments/payment-sources/using-the-source-identifier.md#attaching-sources-to-customers). {% endtab %} {% tab title="Elements" %} **Prerequisites**: Refer to the [Elements prerequisites](#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()`](/digital-river-api/developer-resources/reference/digitalriver-object.md#creating-sources) method's configuration object to set `futureUse` to `true`. Make sure you also assign a value to [`usage`](/digital-river-api/developer-resources/reference/digitalriver-object.md#specifying-a-sources-future-use) that identifies the future use of the payment source and passes 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 customer provides the required SCA, a Source in a [`chargeable` state](/digital-river-api/payments/payment-sources.md#source-state) is returned. **Step two:** [Attach the Source to the Customer](/digital-river-api/payments/payment-sources/using-the-source-identifier.md#attaching-sources-to-customers). {% endtab %} {% endtabs %} ### 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 | {% tabs %} {% tab title="Drop-in payments" %} [Drop-in payments](/digital-river-api/payments/payment-integrations-1/drop-in.md) 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 customer's payment sources](/digital-river-api/payments/payment-sources/retrieving-sources.md#obtain-a-customers-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](/digital-river-api/developer-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/digital-river-api/integration-options/checkouts/building-you-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.