# Handling external subscription acquisitions If you're not using [our subscription service](https://docs.digitalriver.com/digital-river-api/using-our-services/subscriptions), you can still use the Digital River APIs and [DigitalRiver.js](https://docs.digitalriver.com/digital-river-api/developer-resources/reference) to handle recurring billing, display and acquire acceptance of a subscription's terms, and comply with [PSD2 and SCA](https://docs.digitalriver.com/digital-river-api/payments/psd2-and-sca) mandates. Integrations that use a third-party subscription service can: * Supply an upstream [subscription identifier](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/subscription-information-1#subscription-identifier) * Use [billing agreements](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/subscription-information-1#billing-agreements) to maintain SCA compliance * Flag a subscription as a [free trial](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/subscription-information-1#free-trial) * Use the [auto renewal flag](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/subscription-information-1#auto-renewal) to ensure that appropriate payment methods are displayed * Persist a subscription's [terms and conditions](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/subscription-information-1#terms) * Specify a subscription's [start time and end time](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/subscription-information-1#start-and-end-time). ## Building a subscription acquisition During subscription acquisitions, you need to: * [Configure the checkout](#configure-the-checkout) * [Acquire acceptance of the autorenewal terms](#handling-the-autorenewal-terms) * [Handle the subscription's payment](#handling-payments) * [Submit the payment authorization request](#submitting-the-acquisition-authorization-request) * [Notify customers of the acquisition](#notifying-customers-of-a-subscription-acquisition) ### Configure the checkout Before [order creation](https://docs.digitalriver.com/digital-river-api/order-management/creating-and-updating-an-order#creating-an-order-with-the-checkout-identifier), a subscription acquisition [checkout ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts)must contain: * A `customerId` that references an existing [customer](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/customers). * A [primary payment `sources[]`](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/using-the-source-identifier#primary-payment-sources) that is [reusable ](https://docs.digitalriver.com/digital-river-api/payments/payment-sources#reusable-or-single-use)and saved to the referenced [customer](https://app.gitbook.com/s/nfnsRxm5nOCJKXwnr6Qv/customers). * A [`chargeType`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/initiating-a-charge) that is [`customer_initiated`](https://docs.digitalriver.com/digital-river-api/integration-options/creating-checkouts/initiating-a-charge#customer-initiated), thereby indicating that the customer actively participates in the acquisition process. In addition, each [`items[]`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/describing-the-items) in the [checkout](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts) that has [`subscriptionInfo`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/subscriptions/subscription-information-1): * Can use [SKUs](https://docs.digitalriver.com/digital-river-api/product-management/skus#skus) or [`productDetails`](https://docs.digitalriver.com/digital-river-api/product-management/skus#product-details) to represent a [digital or physical product](https://docs.digitalriver.com/digital-river-api/product-management/skus#how-products-are-classified-as-physical-or-digital) * Must set [`autoRenewal`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/subscription-information-1#auto-renewal) to `true` * Must contain the subscription's [`terms`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/subscription-information-1#terms) {% tabs %} {% tab title="Checkout" %} ``` { "id": "7e5e832a-0c78-43e1-b136-ced8c156f5b8", "createdTime": "2022-04-07T20:49:49Z", "customerId": "533134230336", "currency": "USD", "email": "anyemail@digitalriver.com", "billTo": { "address": { "line1": "10381 Bren Rd W", "city": "Minnetonka", "postalCode": "55343", "state": "MN", "country": "US" }, "name": "William Brown", "email": "null@digitalriver.com" }, "totalAmount": 10.0, "subtotal": 10.0, "totalFees": 0.0, "totalTax": 0.0, "totalImporterTax": 0.0, "totalDuty": 0.0, "totalDiscount": 0.0, "totalShipping": 0.0, "items": [ { "id": "e782d614-1444-4e37-a103-d9726288e0ce", "skuId": "0181a7a9-610e-48c5-89e5-84ca06c69f03", "amount": 10.0, "quantity": 1, "tax": { "rate": 0.0, "amount": 0.0 }, "importerTax": { "amount": 0.0 }, "duties": { "amount": 0.0 }, "subscriptionInfo": { "terms": "Subscription terms accepted by the customer", "autoRenewal": true, "freeTrial": false }, "fees": { "amount": 0.0, "taxAmount": 0.0 } } ], "updatedTime": "2022-04-07T20:49:49Z", "locale": "en_US", "customerType": "individual", "chargeType": "customer_initiated", "sellingEntity": { "id": "C5_INC-ENTITY", "name": "DR globalTech Inc." }, "liveMode": false, "payment": { "sources": [ { "id": "5e359d60-1d23-4234-84ee-e1c9b3ed7edc", "type": "creditCard", "amount": 10.0, "owner": { "firstName": "William", "lastName": "Brown", "email": "null@digitalriver.com", "address": { "line1": "10381 Bren Rd W", "city": "Minnetonka", "postalCode": "55343", "state": "MN", "country": "US" } }, "creditCard": { "brand": "Visa", "expirationMonth": 7, "expirationYear": 2027, "lastFourDigits": "1111" } } ], "session": { "id": "965db940-51f6-4f53-bc07-1052ef0d4c32", "amountContributed": 10.0, "amountRemainingToBeContributed": 0.0, "state": "requires_confirmation", "clientSecret": "965db940-51f6-4f53-bc07-1052ef0d4c32_f9eae301-588a-409c-9d29-3358f19dca4f" } } } ``` {% endtab %} {% endtabs %} ### Acquiring acceptance of the autorenewal terms 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're using [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="info" %} For more details on required disclosures, refer to 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" %} In [checkouts](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts), set each subscription line item's [`autoRenewal`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/subscription-information-1#auto-renewal) to `true`. In the [`createDropin()`](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/digitalriver-object#creating-an-instance-of-drop-in) method's configuration [`options`](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide#drop-in-options-1), set [`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`. These settings prompt [Drop-in payments](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in) to display the combined autorenewal and save payment agreement. 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-legacy-files/o/assets%2F-LqH4RJfLVLuHPXuJyTZ%2F-MeW5S0_rYt2K_UOflq4%2F-MeW6yKOUz4vFyzg5xkb%2Fimage.png?alt=media\&token=c4de5e1b-80df-4ec1-b550-0c7116416bcc) If the customer consents and a [source](https://docs.digitalriver.com/digital-river-api/payments/payment-sources) is successfully created, then the [`onSuccess`](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide#onsuccess) event's `data` contains the agreed-upon terms (`mandate.terms`) and the time the customer accepted those terms (`mandate.signedTime`). {% endtab %} {% tab title="DigitalRiver.js" %} If you're using DigitalRiver.js, you can 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. Your code should be written so customers can accept these terms before the checkout can proceed. You should then pass `autorenewalPlanTerms.localizedText` to `mandate.terms` in the [`createSource()`](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/digitalriver-object#creating-sources) method's configuration object. {% endtab %} {% endtabs %} If you configure your workflow correctly, then the customer-accepted autorenewal terms are returned in the [`onSuccess`](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide#onsuccess) event's `data` or the response to the [`createSource()`](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/digitalriver-object#creating-sources) method. In either case, retrieve `mandate.terms` and use this value to set each of the [checkout's ](https://app.gitbook.com/s/ScJM6Hp95yBCPfU1nBSB/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-agreement-identifier). ### Handling payments Customers can create a new source or authenticate a saved source to fund a recurring transaction. For details, refer to the [subscription section](https://docs.digitalriver.com/digital-river-api/integration-options/building-you-workflows#subscription) on the[ Building payments workflows](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/building-you-workflows) page. ### Submitting the acquisition authorization request Once the checkout's [`payment.session.state`](https://docs.digitalriver.com/digital-river-api/integration-options/creating-checkouts/payment-sessions#session-state) is [`requires_confirmation`](https://docs.digitalriver.com/digital-river-api/integration-options/creating-checkouts/payment-sessions#requires_confirmation), and all [address requirements](https://docs.digitalriver.com/digital-river-api/integration-options/creating-checkouts/providing-address-information#address-requirements-and-validations) are met, [submit the create order request](https://docs.digitalriver.com/digital-river-api/order-management/creating-and-updating-an-order#creating-an-order-with-the-checkout-identifier). At that point, Digital River generates a [billing agreement](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/subscription-information-1#billing-agreement-identifier) and returns its `billingAgreementId` in the response. {% tabs %} {% tab title="Order" %} ```javascript { "id": "188817490336", "customerId": "533134230336", ... "items": [ { "id": "110359190336", "skuId": "0181a7a9-610e-48c5-89e5-84ca06c69f03", ... "subscriptionInfo": { "terms": "Subscription terms accepted by the customer", "autoRenewal": true, "freeTrial": false, "billingAgreementId": "c567f049-9ec4-4c63-829b-efe01427a8a9" }, ... } ], ... "state": "accepted", ... "checkoutId": "50a72152-4a61-4e4a-b9e1-2ab5db891105" } ``` {% endtab %} {% endtabs %} ### Notifying customers of a subscription acquisition When the [order's ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders)[`state` ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders/order-basics#order-states-and-events)is [`accepted`](https://docs.digitalriver.com/digital-river-api/order-management/creating-and-updating-an-order#handling-accepted-orders), notify customers that their subscription acquisition has been successfully processed. In the [Subscription Notifications](https://digitalriver.service-now.com/kb?id=kb_article_view\&sysparm_article=KB0012073) 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*), you can find a complete list of what is required in this notification.‌ ## Next steps For details on auto-renewals and updates, refer to [Managing an external subscription](https://docs.digitalriver.com/digital-river-api/subscription-management/managing-an-external-subscription).