# Handling subscription acquisitions

If you're pairing the [Direct Integrations](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts) checkout solution with [Digital River's subscription service](https://docs.digitalriver.com/digital-river-api/using-our-services/subscriptions), this page explains how to process it:

* [Standard subscription acquisitions](#building-acquisitions)
* [Free trial subscription acquisitions](#managing-trial-subscription-acquisitions)

Once you [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), you must activate the subscription, fulfill the goods, and manage renewals. Refer to the [Managing a subscription](https://docs.digitalriver.com/digital-river-api/subscription-management/managing-a-subscription) page for details on handling these and other processes.

## Subscription acquisitions <a href="#building-acquisitions" id="building-acquisitions"></a>

During subscription acquisitions, you must:

* [Create a subscription](#creating-a-subscription) and [handle the response](#handling-the-response)
* [Display terms and acquire consent](#displaying-terms-and-acquiring-consent)
* [Obtain payment information](#acquiring-payment)

### Creating a subscription

In [checkouts](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts), you define subscriptions in `items[]`. Checkouts can contain either a single `items[]` with [`subscriptionInfo`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/subscriptions/subscription-information-1) or[ multiple subscription line items](#subscriptions-with-multiple-line-items). We also support [mixed cart checkouts](#mixed-carts).

For each `items[].subscriptionInfo` in the request:

* Use `planId` to associate the subscription with a plan. For details, refer to [Defining a business model](https://docs.digitalriver.com/digital-river-api/using-our-services/subscriptions#defining-a-business-model).
* Pass `terms`. To do this, make a [`GET /plans/{planId}`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/plans#plans-id-1) request. From the response, retrieve the [plan's ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/plans/plan-basics)`terms` and use that value to set the line item's `terms`. If you don't send `terms`, a `400 Bad Request` with a `code` of `missing_parameter` is thrown.

{% hint style="success" %}
For details, refer to [Displaying terms and acquiring consent](#displaying-terms-and-acquiring-consent).
{% endhint %}

* Set [`autoRenewal`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/subscription-information-1#auto-renewal) to `true` or omit the value. If you set `autoRenewal` to `false`, you receive a `400 Bad Request` with a `code` of `invalid_parameter`.
* Use `freeTrial` to set up trial periods. For details, refer to [Trial subscription acquisitions](#managing-trial-subscription-acquisitions).
* If you don't provide a unique `subscriptionId`, we generate one for you.

In subscription acquisitions, make sure you also set the checkout's [`chargeType`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/initiating-a-charge) to `customer_initiated`.

{% tabs %}
{% tab title="POST /checkouts" %}

```
curl --location --request POST 'https://api.digitalriver.com/checkouts' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API_key>' \
...
--data-raw '{
	"customerId": "0aa4bb94-2995-4689-9b57-f11d1beb18c9",
	"sourceId": "586ffca0-ca4f-4d87-a933-192afa36cc6b",
	"locale": "en_US",
	"email": "jsmith123@digitalriver.com",
	"currency": "USD",
	"items": [{
			"skuId": "d273122b-e78d-4fcb-a1ab-10c07c871ee7",
			"quantity": 5,
			"price": 5.01,
			...
			"subscriptionInfo": {
				"planId": "460d1943-5ac1-48b8-98e8-237c6e3019a7",
				"terms": "These are the terms...."
			},
			"metadata": {
				"key1_ItemLevel": "tets"
			}
	}],
	...
}'
```

{% endtab %}
{% endtabs %}

#### Checkouts with multiple subscriptions <a href="#subscriptions-with-multiple-line-items" id="subscriptions-with-multiple-line-items"></a>

[Checkouts ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts)can contain multiple [`items[]`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/describing-the-items) with [`subscriptionInfo`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/subscriptions/subscription-information-1). All the recurring items, however, must share the same `planId` and (if you set the value) `subscriptionId`. Once you submit the request, Digital River adds these line items to a single subscription.

If you attempt to [create checkouts](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts#checkouts-1) with multiple `items[]` that reference different plans, then the following error is returned:

{% tabs %}
{% tab title="409 Conflict" %}

```javascript
{
    "type": "conflict",
    "errors": [
        {
            "code": "plan_limit_reached",
            "parameter": "planId",
            "message": "Only one unique subscription plan can be supported in a checkout"
        }
    ]
}
```

{% endtab %}
{% endtabs %}

#### Checkouts with subscription and non-subscription items <a href="#mixed-carts" id="mixed-carts"></a>

Digital River's subscription service supports building checkouts containing subscription and non-subscription line items and successfully [converting those checkouts to orders](https://docs.digitalriver.com/digital-river-api/order-management/creating-and-updating-an-order#creating-an-order-with-the-checkout-identifier). However, the subscription line items must all [reference the same plan](#subscriptions-with-multiple-line-items).

A common use case for these mixed checkouts is to process transactions that combine a one-time physical product with a digital subscription service.

### Handling the acquisition checkout response <a href="#handling-the-response" id="handling-the-response"></a>

After you submit the [`POST/ checkouts`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts#checkouts-1) request, Digital River creates a [subscription](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions), sets it to `state` to `draft` and then generates an [event ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/events)with a [`type`](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/events-1#event-types) of [`subscription.created`](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/events-1/event-types#subscription.created).

In the response's body and the event's `data.object`, the [`subscriptionId`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/subscription-information-1#subscription-identifier) uniquely identifies that subscription. At a minimum, make sure you persist this value.

At this point, no additional subscription line items can be added to the checkout. Furthermore, you're restricted to [what product information can be updated](https://docs.digitalriver.com/digital-river-api/integration-options/creating-checkouts/describing-the-items#updating-items).

Since Digital River's subscription service doesn't support manual renewals, [`autoRenewal`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/subscription-information-1#auto-renewal) always returns `true` .

{% hint style="success" %}
Refer to the [Third party subscription services](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/subscriptions/third-party-coordinated-subscriptions) page for details on how to handle manual renewals, where you invite customers to actively renew subscriptions at a designated time.
{% endhint %}

{% tabs %}
{% tab title="Checkout with subscription line item" %}

```javascript
{
    "id": "88aaf811-a8a8-4b7a-9a23-5bc0241e039a",
    "createdTime": "2021-08-11T20:06:32Z",
    "customerId": "0aa4bb94-2995-4689-9b57-f11d1beb18c9",
    "currency": "USD",
    "email": "jsmith123@digitalriver.com",
    "billTo": {
        "address": {
            "line1": "10380 Bren Road West",
            "city": "Minnetonka",
            "postalCode": "55343",
            "state": "MN",
            "country": "US"
        },
        "name": "Digital Development",
        "email": "testdummy@digitalriver.com",
        "organization": "DR",
        "additionalAddressInfo": {
            "neighborhood": "Centro"
        }
    },
    "totalAmount": 26.9,
    "subtotal": 25.05,
    "totalFees": 0.0,
    "totalTax": 1.85,
    "totalImporterTax": 0.0,
    "totalDuty": 0.0,
    "totalDiscount": 0.0,
    "totalShipping": 0.0,
    "items": [
        {
            "id": "b0ae5bf9-6df7-4185-91f2-7e2589acbe8d",
            "skuId": "d273122b-e78d-4fcb-a1ab-10c07c871ee7",
            "amount": 25.05,
            "quantity": 5,
            "metadata": {
                "key1_ItemLevel": "tets"
            },
            "tax": {
                "rate": 0.07375,
                "amount": 1.85
            },
            "importerTax": {
                "amount": 0.0
            },
            "duties": {
                "amount": 0.0
            },
            "subscriptionInfo": {
                "subscriptionId": "192a2549-8b16-482e-b1bb-b4a64cd6a0c0",
                "planId": "460d1943-5ac1-48b8-98e8-237c6e3019a7",
                "terms": "Please accept terms",
                "autoRenewal": true,
                "freeTrial": false
            },
            "fees": {
                "amount": 0.0,
                "taxAmount": 0.0
            }
        }
    ],
    "updatedTime": "2021-08-11T20:06:32Z",
    "locale": "en_US",
    "customerType": "individual",
    "sellingEntity": {
        "id": "C5_INC-ENTITY",
        "name": "DR globalTech Inc."
    },
    "liveMode": false,
    "payment": {
        "sources": [
            {
                "id": "586ffca0-ca4f-4d87-a933-192afa36cc6b",
                "type": "creditCard",
                "amount": 26.9,
                "owner": {
                    "firstName": "Digital",
                    "lastName": "Development",
                    "email": "testdummy@digitalriver.com",
                    "address": {
                        "line1": "10380 Bren Road West",
                        "city": "Minnetonka",
                        "postalCode": "55343",
                        "state": "MN",
                        "country": "US"
                    },
                    "organization": "DR",
                    "additionalAddressInfo": {
                        "neighborhood": "Centro"
                    }
                },
                "creditCard": {
                    "brand": "Visa",
                    "expirationMonth": 7,
                    "expirationYear": 2027,
                    "lastFourDigits": "1111"
                }
            }
        ],
        "session": {
            "id": "9fb4036f-5051-4255-9189-16e449d69ca6",
            "amountContributed": 26.9,
            "amountRemainingToBeContributed": 0.0,
            "state": "requires_confirmation",
            "clientSecret": "9fb4036f-5051-4255-9189-16e449d69ca6_3c6275e8-e065-4bb9-b75a-829f62b78c2c"
        }
    }
}
```

{% endtab %}
{% endtabs %}

If you [retrieve the subscription](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions#subscriptions-id), you'll notice that key fields have yet to be populated at this stage of the acquisition process. This is because the subscription's `state` is still `draft` and the `contractBindingUntil`, `nextReminderDate`, `currentPeriodEndDate`, and `nextInvoiceDate` are generated when you [activate the subscription](https://docs.digitalriver.com/digital-river-api/subscription-management/managing-a-subscription#activating-a-subscription).

{% tabs %}
{% tab title="Subscription prior to activation" %}

```javascript
{
    "id": "7f784dd8-a76f-4d3a-84e1-abdc9c7ac3b9",
    "createdTime": "2022-02-07T14:02:46Z",
    "updatedTime": "2022-02-07T14:02:46Z",
    "stateTransitions": {},
    "taxInclusive": false,
    "currency": "USD",
    "planId": "82cbf763-fa27-401a-aa69-5e6640539ce7",
    "state": "draft",
    "items": [
        {
            "price": 100.0,
            "skuId": "bd933514-43fa-40d3-863c-8ff6fce0db76",
            "quantity": 1
        }
    ],
    "liveMode": false
}
```

{% endtab %}
{% endtabs %}

### Displaying terms and acquiring consent

During acquisitions, you must disclose a subscription's terms and then acquire the customer's active acceptance of them. How you do this depends on whether you use [Drop-in payments](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in) or [DigitalRiver.js with elements](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/digitalriver.js/quick-start). In either case, the [plan's ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/plans)[`terms` ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/plans/plan-basics#terms)should match those displayed to customers.

{% hint style="info" %}
For required disclosures, see the [Subscriptions and Auto-Renewal Considerations](https://digitalriver.service-now.com/kb?id=kb_article_view\&sysparm_article=KB0010508) article (*refer to* [*Learning tools*](https://docs.digitalriver.com/digital-river-api/general-resources/standards-and-certifications/compliance-requirements#accessing-the-learning-tools) *for access information*).
{% endhint %}

{% tabs %}
{% tab title="Drop-in payments" %}
A subscription's terms are displayed in the modal window if you're using [Drop-in payments](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in). For details, see the [Acquiring payment section](#acquiring-payment) on this page.
{% endtab %}

{% tab title="Elements" %}
If you're using [DigitalRiver.js with elements](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/digitalriver.js/quick-start), present our standardized subscription terms and save the payment agreement by calling the [get compliance details method](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/digitalriver-object#digitalriver.compliance.getdetails-businessentitycode-locale), retrieving `autorenewalPlanTerms.localizedText` and then displaying that text with an appropriate acceptance control.

![](https://334437993-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LqH4RJfLVLuHPXuJyTZ%2F-MgqwZvOr5WQLj7Zs4pV%2F-MgqytQx8uYIhFhy-YXc%2FDR%20js%20terms.png?alt=media\&token=9a81a9de-9a22-46c5-bd70-1fec88f6ca78)

Your code should be written so customers can accept these terms before the checkout can proceed. You can then use `autorenewalPlanTerms.localizedText` to set `mandate.terms` in the [`createSource()`](#creating-a-new-payment-source) method's configuration object.
{% endtab %}
{% endtabs %}

After you [convert an acquisition 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), the subscription's terms are stored in the [billing agreement](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/subscription-information-1#billing-agreements).

### Acquiring payment

During acquisition checkouts, you can give customers the option to:

* [Create a new payment source](#creating-a-new-payment-source) or
* [Authenticate a saved payment source](#authenticating-a-saved-payment-source)

#### Creating a new payment source

How you create a payment [source ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders)to fund a recurring transaction depends on whether your integration uses [Drop-in payments](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in) or [DigitalRiver.js with elements](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/digitalriver.js/quick-start).

{% hint style="success" %}
For more details, refer to the [subscriptions section](https://docs.digitalriver.com/digital-river-api/integration-options/building-you-workflows#subscription) on the [Building payment workflows](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/building-you-workflows) page.
{% endhint %}

{% tabs %}
{% tab title="Drop-in payments" %}
After [building a checkout with subscription information](#creating-a-subscription), configure [`createDropin()`](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide#step-5-configure-hydrate):

* Use the checkout's [payment session identifier](https://docs.digitalriver.com/digital-river-api/integration-options/creating-checkouts#payment-session-identifier) to set `sessionId`
* If your integration sends the customer's billing information in the [checkout's ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts)`billTo`, then it's not necessary to pass `billingAddress`
* 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`
  * [`showComplianceSection`](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide#show-compliance-section) to `true`
  * [`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`
  * [`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` and [`showSavePaymentAgreement`](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide#show-save-payment-agreement) to `false`. These two settings (along with the [checkout's](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts) [`autoRenewal`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/subscription-information-1#auto-renewal) value of `true`), prompt Drop-in payments to display the combined autorenewal and save payment agreement.

```javascript
let digitalriverpayments = new DigitalRiver("pk_hc_a209389e4588433bb6e00b32466b82c3", {
    "locale": "en_US"
});

let configuration = { 
    "sessionId": "2bc96772-1142-4289-9d20-f6905591d7e4",
    "options": {
        "flow": "checkout",
        "showComplianceSection": true,
        "showSavePaymentAgreement": false,
        "showTermsOfSaleDisclosure": true,
        "usage": "subscription"
    }
    ...
}

let dropin = digitalriverpayments.createDropin(configuration);
dropin.mount("drop-in-container");
```

Pass the configuration object to `createDropin()`and [mount Drop-in payments](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide#step-7-mount-drop-in-payments-on-a-checkout-or-account-management-page) in the appropriate container. If the request is successful, [`onReady`](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide#drop-in-events) returns the transaction's eligible payment methods:

```javascript
{
    "paymentMethodTypes": [
        "creditCard",
        "payPalBilling",
        "googlePay",
        "klarnaCreditRecurring",
        "msts"
    ]
}
```

Each payment method, accompanied by the subscription's terms and conditions, is displayed in the modal window.

If customers click the [configurable continue button](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) without agreeing to the terms, Drop-in prevents the transaction from proceeding.

![](https://334437993-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LqH4RJfLVLuHPXuJyTZ%2Fuploads%2FW1QyNveCNQP0tsjqQ5Wh%2Fimage.png?alt=media\&token=732edb11-fca7-41db-b255-878d79c4d46b)

If customers consent to the terms and submit their payment information and the resulting create source request is successful, then the [`onSuccess`](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide#drop-in-events) event's `data` contains 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) and [`chargeable`](https://docs.digitalriver.com/digital-river-api/payments/payment-sources#source-state). The object also contains the agreed-upon terms (`mandate.terms`) and the time the customer accepted those terms (`mandate.signedTime`).

For details, refer to the [Drop-in payments integration guide](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide) and the [Drop-in payments builder tool](https://drapi.io/drop-in-builder/).
{% endtab %}

{% tab title="Elements" %}
After [building a checkout with subscription information](#creating-a-subscription), send the checkout's [payment session identifier](https://docs.digitalriver.com/digital-river-api/integration-options/creating-checkouts#payment-session-identifier) to your front end and use it to set `sessionId` in the configuration object of [`retrieveAvailablePaymentMethods()`](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/digitalriver-object#digitalriverjs-retrieveavailablepaymentmethodsresponsewithusingfilters).

```javascript
...
digitalRiver.retrieveAvailablePaymentMethods({
    "sessionId": "1c86a97f-45ea-4d73-8c99-ca533e392ab1"
}).then(function(result) {
    //do something with the result
    console.log(result)
});
...
```

If the request is successful, the response contains the payment methods that apply to the transaction.

{% code title="Available payment methods" %}

```javascript
[
    {
        "type": "creditCard",
        "flow": "standard",
        "supportsRecurring": true,
        "supportsFreeTrial": true,
        "images": {
            "iconImage": "https://ui1.img.digitalrivercontent.net/Storefront/images/paymentMethodLogos/creditcard.png"
        },
        "supportsStorage": true,
        "defaultMandate": {
            "terms": "I agree that Digital River may store my payment information for future purchases including the processing of any subsequent subscription renewals which may occur at a future date."
        },
        "displayName": "Credit Card",
        "localizedDisplayName": "Credit Card"
    },
    {
        "type": "payPalBilling",
        "flow": "redirect",
        "supportsRecurring": true,
        "supportsFreeTrial": true,
        "images": {
            "iconImage": "https://ui1.img.digitalrivercontent.net/Storefront/images/paymentMethodLogos/paypalBilling.png"
        },
        "supportsStorage": true,
        "defaultMandate": {
            "terms": "I agree that Digital River may store my payment information for future purchases including the processing of any subsequent subscription renewals which may occur at a future date."
        },
        "displayName": "PayPal Billing",
        "localizedDisplayName": "PayPal"
    },
    {
        "type": "googlePay",
        "flow": "standard",
        "supportsRecurring": true,
        "supportsFreeTrial": true,
        "images": {
            "iconImage": "https://ui1.img.digitalrivercontent.net/Storefront/images/paymentMethodLogos/googlepay.png"
        },
        "supportsStorage": true,
        "defaultMandate": {
            "terms": "I agree that Digital River may store my payment information for future purchases including the processing of any subsequent subscription renewals which may occur at a future date."
        },
        "displayName": "Google Pay",
        "localizedDisplayName": "Google Pay"
    }
]
```

{% endcode %}

Based on these payment methods, [create the appropriate elements](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/digitalriver-object#creating-elements) to collect the customer's sensitive payment information.

After customers select a payment method, [accept the terms](#displaying-terms-and-acquiring-consent), and submit their payment information, configure [`createSource()`](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/digitalriver-object#creating-sources):

* Set `type` to the payment method selected by the customer
* Use the checkout's [payment session identifier](https://docs.digitalriver.com/digital-river-api/integration-options/creating-checkouts#payment-session-identifier) to set `sessionId`.
* Set [`usage`](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/digitalriver-object#specifying-a-sources-future-use) to `subscription` and `futureUse` to `true`
* Use the [agreed-upon terms](#displaying-terms-and-acquiring-consent) to set `mandate.terms`
* If your integration passes a customer's billing information in the [checkout's ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts)`billTo`, then it's not necessary to send `billingAddress`

```javascript
var payload = {
    "type": "creditCard",
    "sessionId": "1c86a97f-45ea-4d73-8c99-ca533e392ab1",
    "futureUse": true,
    "usage": "subscription",
    ...
    "mandate": {
        "terms": "By checking the box below and completing your purchase..."
    }
}

digitalriver.createSource(payload).then(function(result) {
    if (result.error) {
        //handle errors
    } else {
        var source = result.source;
        //send source to back end
        sendToBackend(source);
    }
});
```

If the create source request is successful, the response contains 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) and [`chargeable`](https://docs.digitalriver.com/digital-river-api/payments/payment-sources#source-state).

For more information, refer to the [Elements integration guide](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/digitalriver.js/quick-start).
{% endtab %}
{% endtabs %}

Next, send the [customer ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/customers)identifier and [source ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/sources)to your backend.

Submit a `POST /customers/{customerId}/sources/{sourceId}` to attach the source to the customer. This flips the source's [`reusable`](https://docs.digitalriver.com/digital-river-api/payments/payment-sources#reusable-or-single-use) attribute to `true You can use`the object in both the subscription's acquisition and as the designated source in renewals.

Once saved to the customer, your integration should [attach the source to the checkout](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/using-the-source-identifier#attaching-sources-to-checkouts).

You should also retrieve `mandate.terms` from the source and use this value to set each of the [checkout's ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts)[`items[].subscriptionInfo.terms`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/subscription-information-1#terms). This ensures that the subscription's terms are added to the [billing agreement](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/subscription-information-1#billing-agreements).

#### Authenticating a saved payment source

{% hint style="warning" %}
[Drop-in payments](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in) do not currently support retrieving saved payment methods.
{% endhint %}

If you give customers the option to select a saved payment source during subscription acquisitions, then after [building a checkout with subscription information](#creating-a-subscription), send the [payment session identifier](https://docs.digitalriver.com/digital-river-api/integration-options/creating-checkouts#payment-session-identifier) to your front end and use it to set `sessionId` in the configuration object of [`retrieveAvailablePaymentMethods()`](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/digitalriver-object#digitalriverjs-retrieveavailablepaymentmethodsresponsewithusingfilters).

{% tabs %}
{% tab title="Request" %}

```javascript
...
digitalRiver.retrieveAvailablePaymentMethods({
    "sessionId": "1c86a97f-45ea-4d73-8c99-ca533e392ab1"
}).then(function(result) {
    //do something with the result
    console.log(result)
});
...
```

{% endtab %}

{% tab title="Response" %}
{% code title="Available payment methods" %}

```javascript
[
    {
        "type": "creditCard",
        "flow": "standard",
        "supportsRecurring": true,
        "supportsFreeTrial": true,
        "images": {
            "iconImage": "https://ui1.img.digitalrivercontent.net/Storefront/images/paymentMethodLogos/creditcard.png"
        },
        "supportsStorage": true,
        "defaultMandate": {
            "terms": "I agree that Digital River may store my payment information for future purchases including the processing of any subsequent subscription renewals which may occur at a future date."
        },
        "displayName": "Credit Card",
        "localizedDisplayName": "Credit Card"
    },
    {
        "type": "payPalBilling",
        "flow": "redirect",
        "supportsRecurring": true,
        "supportsFreeTrial": true,
        "images": {
            "iconImage": "https://ui1.img.digitalrivercontent.net/Storefront/images/paymentMethodLogos/paypalBilling.png"
        },
        "supportsStorage": true,
        "defaultMandate": {
            "terms": "I agree that Digital River may store my payment information for future purchases including the processing of any subsequent subscription renewals which may occur at a future date."
        },
        "displayName": "PayPal Billing",
        "localizedDisplayName": "PayPal"
    },
    {
        "type": "googlePay",
        "flow": "standard",
        "supportsRecurring": true,
        "supportsFreeTrial": true,
        "images": {
            "iconImage": "https://ui1.img.digitalrivercontent.net/Storefront/images/paymentMethodLogos/googlepay.png"
        },
        "supportsStorage": true,
        "defaultMandate": {
            "terms": "I agree that Digital River may store my payment information for future purchases including the processing of any subsequent subscription renewals which may occur at a future date."
        },
        "displayName": "Google Pay",
        "localizedDisplayName": "Google Pay"
    }
]
```

{% endcode %}
{% endtab %}
{% endtabs %}

For each payment method contained in the response, determine if its `type` matches the `type` of one or more of the [customer's ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/customers)`sources[]`. If it does, you can retrieve those saved `sources[]` from the [customer ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/customers)and display them as options on your payments page.

If the customer selects a saved source, passes its `sources[].id` and `sources[].clientSecret` (along with the checkout's [payment session identifier](https://docs.digitalriver.com/digital-river-api/integration-options/creating-checkouts#payment-session-identifier)) to [`authenticateSource()`](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/digitalriver-object#authenticating-sources). This method determines whether [strong customer authentication](https://docs.digitalriver.com/digital-river-api/payments/psd2-and-sca) is required.

{% tabs %}
{% tab title="Customer" %}

```javascript
{
    "id": "533319260336",
    ...
    "sources": [
        {
            "id": "5e359d60-1d23-4234-84ee-e1c9b3ed7edc",
            ...
            "type": "creditCard",
            "reusable": true,
            "state": "chargeable",
            ...
            "clientSecret": "5e359d60-1d23-4234-84ee-e1c9b3ed7edc_bf74c04c-8586-41e2-964a-f5e618d2b7e3",
            ...
        },
        {
            "id": "19f47eba-418f-41b3-882c-462e335770e7",
            ...
            "type": "payPalBilling",
            "reusable": true,
            "state": "chargeable",
            ...
            "clientSecret": "19f47eba-418f-41b3-882c-462e335770e7_cc871d23-474d-4a3f-9803-4e98fa39f2ee",
            ...
        }
    ],
    ...
}
```

{% endtab %}

{% tab title="Checkout" %}

```javascript
{
    "id": "50a72152-4a61-4e4a-b9e1-2ab5db891105",
    ...
    "payment": {
        "session": {
            "id": "f5dd814a-ecee-4f7e-bf7c-4635f0c19c91",
            ...
        }
    }
}
```

{% endtab %}

{% tab title="authenticateSource( )" %}

```javascript
...
digitalriver.authenticateSource({
    "sessionId": "f5dd814a-ecee-4f7e-bf7c-4635f0c19c91",
    "sourceId": "5e359d60-1d23-4234-84ee-e1c9b3ed7edc",
    "sourceClientSecret": "5e359d60-1d23-4234-84ee-e1c9b3ed7edc_bf74c04c-8586-41e2-964a-f5e618d2b7e3",
    "returnUrl": "https://mypage.com"
});
...
```

{% endtab %}
{% endtabs %}

If the response `status` is `complete` or `authentication_not_required`, the method resolves, allowing your integration to [attach the authenticated source to the checkout](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/using-the-source-identifier#attaching-sources-to-checkouts).

{% hint style="success" %}
For additional details, refer to the section on [retrieving saved payment sources during subscription acquisitions](https://docs.digitalriver.com/digital-river-api/integration-options/building-you-workflows#customer-saves-credit-card-details-during-subscription-acquisition-checkout) on the [Building payment workflows](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/building-you-workflows) page.
{% endhint %}

### Managing subscriptions after acquisition

After you [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), you'll need to activate the subscription and process renewals. To learn more, refer to the [Managing a subscription](https://docs.digitalriver.com/digital-river-api/subscription-management/managing-a-subscription) page.

## Trial subscription acquisitions <a href="#managing-trial-subscription-acquisitions" id="managing-trial-subscription-acquisitions"></a>

You handle free-trial subscription acquisitions in much the same way as [standard acquisitions](#building-acquisitions).

In [free trials](https://docs.digitalriver.com/digital-river-api/using-our-services/subscriptions#setting-up-free-trials), however, you must configure the checkout slightly differently.

Once customers initiate checkout, determine whether their cart contains trial-based subscription products. If it does, use `items[].subscriptionInfo` to describe those products in your [`POST /checkouts`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts).

{% hint style="info" %}
You can also add non-trial subscription products, as well as non-subscription products, to the same checkout. All the subscription line items, however, must reference the same plan. For details, refer to [Checkouts with multiple subscriptions](#subscriptions-with-multiple-line-items).
{% endhint %}

Each trial-based subscription line item in the request must specify a `price` of `0.0`, set `freeTrial` to `true`, and pass a `planId` that references a [trial period plan](https://docs.digitalriver.com/digital-river-api/using-our-services/subscriptions#trial-period-plans).

{% code title="POST /checkouts" %}

```javascript
curl --location --request POST 'https://api.digitalriver.com/checkouts' \
--header 'Content-Type: application/json' \
...
--data-raw '{
    "customerId": "563089630336",
    "sourceId": "8687447b-a04d-4838-af6c-0de0810f23a7",
    "locale": "en_US",
    "email": "jdoe@digitalriver.com",
    "currency": "USD",
    "items": [
        {
            "skuId": "sku_3e5ab173-d52e-4d9e-8888-2a00f6bb188e",
            "quantity": 2,
            "price": 0.0,
            "subscriptionInfo": {
                "planId": "186cf07e-a1ea-4ec0-9d9a-8aa93b3af43a",
                "terms": "The terms of the subscription",
                "autoRenewal": true,
                "freeTrial": true
            }
        }       
    ]
}'
```

{% endcode %}

If you create or update a checkout and (1) `freeTrial` is `true` and `price` or `aggregatePrice` contain a value that's greater than `0.0` or (2) `freeTrial` is `false` and `price` or `aggregatePrice` are `0.0`, then the following error is thrown:

{% code title="400 Bad Request" %}

```javascript
{
    "type": "bad_request",
    "errors": [
        {
            "code": "invalid_parameter",
            "parameter": "items",
            "message": "The value of the Free Trial flag is not consistent with the item price or the aggregate price."
        }
    ]
}
```

{% endcode %}

### Managing trial subscriptions after acquisition

Refer to [Trial subscription management](https://docs.digitalriver.com/digital-river-api/subscription-management/managing-a-subscription#trial-subscription-management) on the [Managing a subscription](https://docs.digitalriver.com/digital-river-api/subscription-management/managing-a-subscription) page for details on how to process a trial subscription after you [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).


---

# 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/subscriptions/digital-river-coordinated-subscriptions.md?ask=<question>
```

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.