# Building payment workflows

Using [Drop-in payments](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in) or [Elements](https://github.com/DigitalRiver/GitBook/blob/Digital-River-API/payments/payment-integrations-1/digitalriver.js), you can create [Strong Customer Authentication (SCA)](https://docs.digitalriver.com/digital-river-api/payments/psd2-and-sca) 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](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/digitalriver-object#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 <a href="#key-settings-and-methods" id="key-settings-and-methods"></a>

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`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/initiating-a-charge) to `customer_initiated`. If you're using [Drop-in payments](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in), use the [`createDropIn()`](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/digitalriver-object#creating-an-instance-of-drop-in) method's [configurable `options`](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide#drop-in-options-1) to set [`flow`](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide#flow) to `checkout` and [`usage`](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide#specifying-a-sources-future-use) to `convenience`. With [DigitalRiver.js with elements](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/digitalriver.js/quick-start), use the [`createSource()`](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/digitalriver-object#creating-sources) method's configuration object to set `futureUse` to `true` and [`usage`](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/digitalriver-object#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`](https://docs.digitalriver.com/digital-river-api/integration-options/subscriptions/subscription-information-1#auto-renewal) to `true`. In this flow type, [Drop-in payments](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in) is not supported. Instead, you'll need to use the [`authenticateSource()`](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/digitalriver-object#authenticating-sources) method.

![Click to enlarge image](https://334437993-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LqH4RJfLVLuHPXuJyTZ%2F-McP3epKJsN0qxaCQq7F%2F-McP6d_LWh2uQ8OIoLBM%2Fflow%20configurations.png?alt=media\&token=253e1eb4-4e03-409b-a754-452f6021b673)

## Common Drop-in payments steps <a href="#common-drop-in-steps" id="common-drop-in-steps"></a>

For any workflow that uses [Drop-in payments](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in), 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](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide#step-1-include-digitalriver-js-on-your-page).
2. ​[Include the Drop-in CSS file](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/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/digital-river-api/payments/payment-integrations-1/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/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide#step-4-create-a-container-for-drop-in).

## Elements prerequisites

If you're using [Elements](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/digitalriver.js/quick-start) to build [purchase](#purchase-flows) workflows, [complete the necessary migration to payment sessions](https://docs.digitalriver.com/digital-river-api/integration-options/creating-checkouts/payment-sessions#migrating-to-payment-sessions). We assume you are familiar with [creating and styling elements](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/elements) and [capturing payment details](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/digitalriver.js/quick-start).

## Purchase flows <a href="#purchase-flows" id="purchase-flows"></a>

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](https://docs.digitalriver.com/digital-river-api/payments/psd2-and-sca) workflows using [Drop-in payments](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in) or [Elements](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/digitalriver.js/quick-start).‌

### One-off <a href="#one-off" id="one-off"></a>

‌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 <a href="#credit-card-details-entered-by-customer-during-checkout" id="credit-card-details-entered-by-customer-during-checkout"></a>

‌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](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts) with all tax, shipping, duty, and fee amounts in a final state and a [`chargeType`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/initiating-a-charge) that is `customer_initiated`.

**Step two**: Retrieve the checkout's [payment session identifier](https://docs.digitalriver.com/digital-river-api/integration-options/creating-checkouts#payment-session-identifier), and use it to set [`sessionId`](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide#drop-in-options) in the[ configuration object](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide#configuring-drop-in-payments). In `options`, set [`flow`](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide#flow) to `checkout` and [`usage`](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/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**: Pass the configuration object to the [create Drop-in method](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/digitalriver-object#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.

![](https://334437993-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LqH4RJfLVLuHPXuJyTZ%2F-MHXkC9aReDKnx8P18AO%2F-MHXtYQUmXN_yNMcE6Go%2Frendered%20drop-in.PNG?alt=media\&token=33148173-ab45-47f0-9646-93d1c8723168)

Customers enter their payment information and click the [configurable](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide#customizing-the-text-of-the-drop-in-button) pay now button.

If customers complete any [SCA](https://docs.digitalriver.com/digital-river-api/payments/psd2-and-sca) that may be required, [`onSuccess` ](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide#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](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/using-the-source-identifier#attaching-sources-to-checkouts).

**Step six**: [Convert the Checkout to an Order](https://docs.digitalriver.com/digital-river-api/order-management/creating-and-updating-an-order#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](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts) with all tax, shipping, duty, and fee amounts in a final state and a [`chargeType`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/initiating-a-charge) that is `customer_initiated`.

**Step two:** Retrieve the [payment session identifier ](https://docs.digitalriver.com/digital-river-api/integration-options/creating-checkouts#payment-session-identifier)and assign it to `sessionId` in the [`createSource()`](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/digitalriver-object#creating-sources) method's configuration object. You should also set `futureUse` to `false` and [`usage`](https://docs.digitalriver.com/digital-river-api/developer-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();
    }
});
```

After the method is called and customers complete any required SCA, a unique [source](https://docs.digitalriver.com/digital-river-api/payments/payment-sources) is returned.

**Step three:** [Attach the Source to the Checkout](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/using-the-source-identifier#attaching-sources-to-checkouts).

**Step four**: [Convert the Checkout to an Order](https://docs.digitalriver.com/digital-river-api/order-management/creating-and-updating-an-order#creating-an-order-with-the-checkout-identifier).
{% endtab %}
{% endtabs %}

#### Customers save their payment information <a href="#credit-card-details-saved-by-customer-during-checkout" id="credit-card-details-saved-by-customer-during-checkout"></a>

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](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts) with a [registered customer](https://docs.digitalriver.com/digital-river-api/integration-options/creating-checkouts/using-the-checkout-identifier#registered-checkouts-or-invoices) and all tax, shipping, duty and fee amounts in a final state. The [`chargeType`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/initiating-a-charge) should be `customer_initiated`.

**Step two**: Retrieve the checkout's [payment session identifier](https://docs.digitalriver.com/digital-river-api/integration-options/creating-checkouts#payment-session-identifier) and use it to set [`sessionId`](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide#drop-in-options) in the [Drop-in payments' configuration object](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide#configuring-drop-in-payments). You should also use `options` to set [`flow`](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide#flow) to `checkout`, [`usage`](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide#specifying-a-sources-future-use) to `convenience`, and [`showSavePaymentAgreement`](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide#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](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/digitalriver-object#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.

![](https://334437993-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LqH4RJfLVLuHPXuJyTZ%2F-MHYKwdoeI4ZfZoGoPm4%2F-MHYNdRu6NN3PO_MQKsr%2Frendered%20drop-in%20with%20saved%20payment%20method%20option.PNG?alt=media\&token=5f5240e8-1069-4671-8b50-1ab870ba9ce8)

Customers enter their credit card information, actively accept the save payment agreement and click the [configurable](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide#customizing-the-text-of-the-drop-in-button) pay now button.

If customers complete any [SCA](https://docs.digitalriver.com/digital-river-api/payments/psd2-and-sca) that may be required, [`onSuccess` ](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide#onsuccess)returns a [source](https://app.gitbook.com/s/ScJM6Hp95yBCPfU1nBSB/sources) that is [`readyForStorage`](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide#onsuccess).

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

**Step five**: [Attach the Source to the Customer](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/using-the-source-identifier#attaching-sources-to-customers).

**Step six**: [Attach the Source to the Checkout](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/using-the-source-identifier#attaching-sources-to-checkouts).

**Step seven**: [Convert the Checkout to an Order](https://docs.digitalriver.com/digital-river-api/order-management/creating-and-updating-an-order#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](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts) with a [registered customer](https://docs.digitalriver.com/digital-river-api/integration-options/creating-checkouts/using-the-checkout-identifier#registered-checkouts-or-invoices) and all tax, shipping, duty and fee amounts in a final state. The [`chargeType`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/initiating-a-charge) should be `customer_initiated`.

**Step two:** Retrieve the [payment session identifier ](https://docs.digitalriver.com/digital-river-api/integration-options/creating-checkouts#payment-session-identifier)and assign it to `sessionId` in the [`createSource()`](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/digitalriver-object#creating-sources) method's configuration object. You should also set `futureUse` to `true` and [`usage`](https://docs.digitalriver.com/digital-river-api/developer-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);
    }
});
```

After the method is called and customers complete any required SCA, a unique [source](https://docs.digitalriver.com/digital-river-api/payments/payment-sources) is returned.

**Step three:** [Attach the Source to the Customer](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/using-the-source-identifier#attaching-sources-to-customers).

**Step four**: [Attach the Source to the Checkout](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/using-the-source-identifier#attaching-sources-to-checkouts).

**Step five**: [Convert the Checkout to an Order](https://docs.digitalriver.com/digital-river-api/order-management/creating-and-updating-an-order#creating-an-order-with-the-checkout-identifier).
{% endtab %}
{% endtabs %}

#### Customers retrieve their payment information <a href="#customer-selects-saved-credit-card-during-checkout" id="customer-selects-saved-credit-card-during-checkout"></a>

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](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/digitalriver-object#authenticating-sources).

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

{% tabs %}
{% tab title="Drop-in payments" %}
[Drop-in payments](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in) do not currently support retrieving saved payment methods. To handle this flow, use [Elements](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/elements).
{% endtab %}

{% tab title="Elements" %}
**Prerequisites**: Refer to the [Elements prerequisites](#elements-prerequisites) section.

**Step one:** [Build a checkout](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts) with a [registered customer](https://docs.digitalriver.com/digital-river-api/integration-options/creating-checkouts/using-the-checkout-identifier#registered-checkouts-or-invoices) and all tax, shipping, duty and fee amounts in a final state. The [`chargeType`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/initiating-a-charge) should be `customer_initiated`.

**Step two:** [Retrieve the customer's payment sources](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/retrieving-sources#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()`](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/digitalriver-object#authenticating-sources) method. For details, refer to [Authenticating sources](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/digitalriver-object#authenticating-sources) on the [DigitalRiver object](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/digitalriver-object) page.&#x20;

```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](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/using-the-source-identifier#attaching-a-source-to-a-customer).

**Step five:** [Convert the Checkout to an Order](https://docs.digitalriver.com/digital-river-api/order-management/creating-and-updating-an-order#creating-an-order-with-the-checkout-identifier).
{% endtab %}
{% endtabs %}

### Subscription <a href="#subscription" id="subscription"></a>

You can create [SCA-compliant](https://docs.digitalriver.com/digital-river-api/payments/psd2-and-sca) 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](https://docs.digitalriver.com/digital-river-api/payments/supported-payment-methods) during subscription acquisitions and set up workflows for [merchant-initiated autorenewals](#merchant-initiated-auto-renewals).

{% hint style="warning" %}
SCA is required for [subscription acquisitions](https://docs.digitalriver.com/digital-river-api/integration-options/subscriptions/subscription-information-1#subscription-acquisition) but not [merchant-initiated](https://docs.digitalriver.com/digital-river-api/integration-options/creating-checkouts/initiating-a-charge#merchant-initiated) auto-renewals.
{% endhint %}

#### Customers enter and save their payment information during a subscription acquisition <a href="#customer-enters-credit-card-details-during-subscription-acquisition-checkout" id="customer-enters-credit-card-details-during-subscription-acquisition-checkout"></a>

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](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts) with a [registered customer](https://docs.digitalriver.com/digital-river-api/integration-options/creating-checkouts/using-the-checkout-identifier#registered-checkouts-or-invoices) and all tax, shipping, duty and fee amounts in a final state. Set [`chargeType`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/initiating-a-charge) to `customer_initiated` and `autoRenewal` to `true`.

**Step two**: Retrieve the checkout's [payment session identifier](https://docs.digitalriver.com/digital-river-api/integration-options/creating-checkouts#payment-session-identifier), and use it to set [`sessionId`](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide#drop-in-options) in the [configuration object](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide#configuring-drop-in-payments). In [`options`](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide#drop-in-options-1), set [`flow`](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide#flow) to `checkout`, [`usage`](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide#specifying-a-sources-future-use) to `subscription`, and [`showTermsOfSaleDisclosure`](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/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**: Pass the configuration object to the [create Drop-in method](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/digitalriver-object#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.

![](https://334437993-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LqH4RJfLVLuHPXuJyTZ%2F-McQGmM_U6zdcqg1Huj1%2F-McQHV_b2KcnjKR6z-W7%2Fsub%20terms.png?alt=media\&token=313e5395-1b3f-4905-932e-f61d572b71d2)

Customers must enter their payment information, actively accept the terms and click the [configurable](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide#customizing-the-text-of-the-drop-in-button) pay now button.

If customers complete any [SCA](https://docs.digitalriver.com/digital-river-api/payments/psd2-and-sca) that may be required, [`onSuccess` ](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide#onsuccess)returns a [source ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/sources)that is [`readyForStorage`](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide#onsuccess).

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

**Step five:** [Attach the Source to the Customer](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/using-the-source-identifier#attaching-sources-to-customers).

**Step six**: [Attach the Source to the Checkout](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/using-the-source-identifier#attaching-sources-to-checkouts).

**Step seven**: [Convert the Checkout to an Order](https://docs.digitalriver.com/digital-river-api/order-management/creating-and-updating-an-order#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](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts) with a [registered customer](https://docs.digitalriver.com/digital-river-api/integration-options/creating-checkouts/using-the-checkout-identifier#registered-checkouts-or-invoices) and all tax, shipping, duty and fee amounts in a final state. Set [`chargeType`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/initiating-a-charge) 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 ](https://docs.digitalriver.com/digital-river-api/integration-options/creating-checkouts#payment-session-identifier)and assign it to `sessionId` in the [`createSource()`](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/digitalriver-object#creating-sources) method's configuration object. You should also set `futureUse` to `true` and [`usage`](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/digitalriver-object#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](https://docs.digitalriver.com/digital-river-api/payments/payment-sources) is returned.

**Step three:** [Attach the Source to the Customer](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/using-the-source-identifier#attaching-sources-to-customers).

**Step four:** [Attach the Source to the Checkout](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/using-the-source-identifier#attaching-sources-to-checkouts).

**Step five:** [Convert the Checkout to an Order](https://docs.digitalriver.com/digital-river-api/order-management/creating-and-updating-an-order#creating-an-order-with-the-checkout-identifier).
{% endtab %}
{% endtabs %}

#### Customers retrieve saved payments during a subscription acquisition <a href="#customer-saves-credit-card-details-during-subscription-acquisition-checkout" id="customer-saves-credit-card-details-during-subscription-acquisition-checkout"></a>

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](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/digitalriver-object#authenticating-sources).

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

{% tabs %}
{% tab title="Drop-in payments" %}
[Drop-in payments](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in) does not currently support retrieving stored payment methods. To handle this flow, use [Elements](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/elements).
{% endtab %}

{% tab title="Elements" %}
**Prerequisites**: Refer to the [Elements prerequisites](#elements-prerequisites) section.

**Step one**: [Build a checkout](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts) with a [registered customer](https://docs.digitalriver.com/digital-river-api/integration-options/creating-checkouts/using-the-checkout-identifier#registered-checkouts-or-invoices) and all tax, shipping, duty and fee amounts in a final state. Set [`chargeType`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/initiating-a-charge) to `customer_initiated` and `autoRenewal` to `true`.

**Step two:** [Retrieve the customer's payment sources](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/retrieving-sources#obtain-a-customers-sources) and display them to the customer during the checkout process.

**Step three**: Configure and call the [`authenticateSource()`](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/digitalriver-object#authenticating-sources) method if the customer uses a saved payment method. For details, refer to [Authenticating sources](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/digitalriver-object#authenticating-sources) on the [DigitalRiver object](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/digitalriver-object) page.&#x20;

```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](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/using-the-source-identifier#attaching-sources-to-checkouts).

**Step five:** [Convert the Checkout to an Order](https://docs.digitalriver.com/digital-river-api/order-management/creating-and-updating-an-order#creating-an-order-with-the-checkout-identifier).
{% endtab %}
{% endtabs %}

#### Merchant-initiated auto-renewals <a href="#merchant-initiated-auto-renewals" id="merchant-initiated-auto-renewals"></a>

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 <a href="#mail-order-telephone-order" id="mail-order-telephone-order"></a>

[SCA](https://docs.digitalriver.com/digital-river-api/payments/psd2-and-sca) is not required for transactions where customers provide payment details by mail, fax, or telephone. However, both Drop-in payments and Elements support building workflows for [mail order and telephone order](https://docs.digitalriver.com/digital-river-api/integration-options/creating-checkouts/initiating-a-charge#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](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts) with a [`chargeType`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/initiating-a-charge) of [`moto`](https://docs.digitalriver.com/digital-river-api/integration-options/creating-checkouts/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](https://docs.digitalriver.com/digital-river-api/integration-options/creating-checkouts#payment-session-identifier), and use it to set [`sessionId`](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide#drop-in-options) in the [Drop-in payments' configuration object](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide#configuring-drop-in-payments). In `options`, set [`flow`](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide#flow) to `checkout` and [`usage`](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/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**: Pass the configuration object to the [create Drop-in method](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/digitalriver-object#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.

![](https://334437993-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LqH4RJfLVLuHPXuJyTZ%2F-McU6l3Dyb6qmjCmkH1M%2F-McU7rOuiCu1kxWqKhiQ%2FMOTO.png?alt=media\&token=5a76270e-3b1c-47a0-831b-783642ed4730)

The merchant's representative enters the customer's credit card information and clicks the [configurable](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide#customizing-the-text-of-the-drop-in-button) pay now button. If the payment is authorized, then [`onSuccess` ](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide#onsuccess)returns a unique [source ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/sources)in a [`chargeable` state](https://docs.digitalriver.com/digital-river-api/payments/payment-sources#source-state).

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

**Step five**: [Attach the Source to the Checkout](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/using-the-source-identifier#attaching-sources-to-checkouts).

**Step six**: [Convert the Checkout to an Order](https://docs.digitalriver.com/digital-river-api/order-management/creating-and-updating-an-order#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](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts) with a [charge type](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/initiating-a-charge) of `moto` and all tax, shipping, duty, and fee amounts in a final state.

**Step two:** Retrieve the [payment session identifier ](https://docs.digitalriver.com/digital-river-api/integration-options/creating-checkouts#payment-session-identifier)and assign it to `sessionId` in the [`createSource()`](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/digitalriver-object#creating-sources) method's configuration object. You should also set `futureUse` to `false` and [`usage`](https://docs.digitalriver.com/digital-river-api/developer-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();
    }
});
```

After the method is called and customers complete any required SCA, a unique [source](https://docs.digitalriver.com/digital-river-api/payments/payment-sources) is returned.

**Step three:** [Attach the Source to a Checkout](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/using-the-source-identifier#attaching-sources-to-checkouts).

**Step four**: [Convert the Checkout to an Order](https://docs.digitalriver.com/digital-river-api/order-management/creating-and-updating-an-order#creating-an-order-with-the-checkout-identifier).
{% endtab %}
{% endtabs %}

## Account management flows <a href="#account-management-flows" id="account-management-flows"></a>

You can create flows that allow customers to manage [recurring payment methods](https://docs.digitalriver.com/digital-river-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/digital-river-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, 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 <a href="#saving-a-credit-card-for-future-use" id="saving-a-credit-card-for-future-use"></a>

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](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide#configuring-drop-in-payments) [`options`](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide#drop-in-options-1) to set [`flow`](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide#flow) to `managePaymentMethods` and specify a value for [`usage`](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide#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`](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide#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](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/payment-sessions) to reference, you shouldn't provide a [`sessionId`](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide#drop-in-options). As a result, you'll need to pass the billing information you collect from customers in [`billingAddress`](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide#billing-address).\\

**Step three**: Pass the configuration object to the [create Drop-in method](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/digitalriver-object#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.

![](https://334437993-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LqH4RJfLVLuHPXuJyTZ%2F-MIKMy4-oivZLsELsdnT%2F-MIKNQFD2v6t3f6YlDJJ%2FAccount%20Management%20Flow.PNG?alt=media\&token=05350958-656d-4c6e-8efd-f119475ea019)

Customers enter their payment information, select the save payment agreement option and click the [configurable](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide#customizing-the-text-of-the-drop-in-button) add payment method button.

If customers complete any [SCA](https://docs.digitalriver.com/digital-river-api/payments/psd2-and-sca) that may be required, [`onSuccess` ](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide#onsuccess)returns a [source](https://www.digitalriver.com/docs/digital-river-api-reference/#tag/Sources) that is [`readyForStorage`](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide#onsuccess).

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

**Step five**: [Attach the Source to the Customer](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/using-the-source-identifier#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()`](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/digitalriver-object#creating-sources) method's configuration object to set `futureUse` to `true`.

Make sure you also assign a value to [`usage`](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/digitalriver-object#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](https://docs.digitalriver.com/digital-river-api/payments/payment-sources#source-state) is returned.

**Step two:** [Attach the Source to the Customer](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/using-the-source-identifier#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](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in) 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](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/retrieving-sources#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](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/digitalriver-object#updating-sources).
{% endtab %}
{% endtabs %}