Acquisitions with third party subscription services

Gain a better understanding of how to do acquisitions and manage recurring billing with a third-party subscription service

If you're not using our subscription service, you can still use the Digital River APIs and DigitalRiver.js to handle recurring billing, display and acquire acceptance of a subscription's terms, and comply with PSD2 and SCA mandates.
Integrations that use a third-party subscription service can:
Supply an upstream subscription identifier​
Use billing agreements to maintain SCA compliance
Indicate that the subscription is a free trial​
Use the auto renewal flag to ensure that appropriate payment methods are displayed
Persist a subscription's terms and conditions​
Specify a subscription's start time and end time.
Building a subscription acquisition
During subscription acquisitions, you need to:
​Configure the checkout​
​Acquire acceptance of the autorenewal terms​
​Handle the subscription's payment​
​Submit the payment authorization request​
​Notify customers of the acquisition​
Configure the checkout
Prior to order creation, a subscription acquisition checkout must contain:
A customerId that references an existing customer​
A primary payment sources[] that is reusable and saved to the referenced customer​
A chargeType that is customer_initiated, thereby indicating that the customer is an active participant in the acquisition process.
In addition, each items[] in the checkout that has subscriptionInfo: 
Can use SKUs or productDetails to represent a digital or physical product 
Must set autoRenewal to true
Must contain the subscription's terms​
Checkout
{
    "id": "7e5e832a-0c78-43e1-b136-ced8c156f5b8",
    "createdTime": "2022-04-07T20:49:49Z",
    "customerId": "533134230336",
    "currency": "USD",
    "email": "[email protected]",
    "billTo": {
        "address": {
            "line1": "10381 Bren Rd W",
            "city": "Minnetonka",
            "postalCode": "55343",
            "state": "MN",
            "country": "US"
        },
        "name": "William Brown",
        "email": "[email protected]"
    },
    "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": "[email protected]",
                    "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"
        }
    }
}
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 or DigitalRiver.js with Elements.
For more details on required disclosures, refer to the Subscriptions and Auto-Renewal Considerations article (refer to Learning tools for access information).
Drop-in payments
DigitalRiver.js
In checkouts, set each subscription line item's autoRenewal to true. In the createDropin() method's configuration options, set showTermsOfSaleDisclosure to true.
These settings prompt Drop-in payments to display the combined autorenewal and save payment agreement.
If customers click the configurable continue button without agreeing to the terms, Drop-in prevents the transaction from proceeding.
If the customer consents and a source is successfully created, then the onSuccess event's data contains the agreed-upon terms (mandate.terms) and the time the customer accepted those terms (mandate.signedTime).
If you're using DigitalRiver.js, you can present our standardized subscription terms and save payment agreement by calling the get compliance details method, retrieving autorenewalPlanTerms.localizedText and then displaying that text with an appropriate acceptance control. Your code should be written so that customers must accept these terms before the checkout can proceed.
You should then pass autorenewalPlanTerms.localizedText to mandate.terms in the createSource() method's configuration object.
If you configure your workflow correctly, then the customer accepted autorenewal terms are returned in the onSuccess event's data or the response to the createSource() method.
In either case, retrieve mandate.terms and use this value to set each of the checkout's items[].subscriptionInfo.terms. This ensures that the subscription's terms are added to the billing agreement.
Handling payments
To fund a recurring transaction, customers can either create a new source or authenticate a saved source.
For details, refer to the subscription section on the Building payments workflows page.
Submitting the acquisition authorization request
Once the checkout's payment.session.state is requires_confirmation, and all address requirements are met, submit the create order request. At that point, Digital River generates a billing agreement and returns its billingAgreementId in the response.
Order
{
    "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"
}
Notifying customers of a subscription acquisition
When the order's state is accepted, notify customers that their subscription acquisition has been successfully processed. In the Subscription Notifications article (refer to Learning tools for access information), you can find a complete list of what is required in this notification.‌
Auto-renewing a subscription
Prior to auto-renewing a subscription, you must send the customer a reminder. 
At the start of each new billing cycle, configure and submit the renewal request. 
Once the renewal is successfully processed, notify the customer.
Sending the renewal reminder
For auto-renewing subscriptions that have terms greater than 30 days, you must notify the subscriber of upcoming renewals 30 days prior to the renewal date. As the renewal date approaches, we recommend you provide additional notifications.
In the Subscription Notifications article (refer to Learning tools for access information), you can find a complete list of what is required in the renewal reminder.
Configuring the renewal request
At the start of each billing cycle, build a renewal checkout. Prior to order creation, a subscription renewal checkout must contain:
A customerId that references the same customer contained in the acquisition order​
A sources[] that is reusable, saved to the referenced customer, and has the same id as the primary source in the acquisition order​
A chargeType set to merchant_initiated, thereby instructing Digital River to notify payment processors that the client's server auto-generated the authorization request
For manual renewals, set chargeType to customer_initiated and autoRenewal to false. This is because customers are actively involved in these types of transactions.
In addition, each items[] in the renewal checkout:
Must set subscriptionInfo.autoRenewal to true
Should have a subscriptionInfo.billingAgreementId that matches the identifier of the corresponding items[] in the acquisition order​
Unless a change event requires the creation of a new billing agreement, you should use this identifier throughout a subscription's lifecycle.‌
If an acquisition order contains multiple items[] with subscriptionInfo, and each have the same terms, then you can process all of their renewals in the same checkout. If the terms are different however, then you should create unique checkouts to handle each renewal.
Since customers accept a subscription's terms during acquisitions, and therefore they've already been added to the billing agreement, it's not necessary to pass terms in the renewal request.
To authorize payment on the subscription renewal, convert the checkout to an order. A 201 Created response returns the same billingAgreementId that you passed in the request.
Checkout
{
    "id": "d229fc76-3398-4038-bd90-2e152769bef0",
    "createdTime": "2022-04-07T21:42:48Z",
    "customerId": "533134230336",
    "currency": "USD",
    "email": "[email protected]",
    "billTo": {
        "address": {
            "line1": "10381 Bren Rd W",
            "city": "Minnetonka",
            "postalCode": "55343",
            "state": "MN",
            "country": "US"
        },
        "name": "William Brown",
        "email": "[email protected]"
    },
    "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": "39153fb7-e5d5-498f-9465-005560ba268e",
            "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": {
                "autoRenewal": true,
                "freeTrial": false,
                "billingAgreementId": "c567f049-9ec4-4c63-829b-efe01427a8a9"
            },
            "fees": {
                "amount": 0.0,
                "taxAmount": 0.0
            }
        }
    ],
    "updatedTime": "2022-04-07T21:42:48Z",
    "locale": "en_US",
    "customerType": "individual",
    "chargeType": "merchant_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": "[email protected]",
                    "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": "e007a135-07ea-4cc8-897e-9081f3f7d9d9",
            "amountContributed": 10.0,
            "amountRemainingToBeContributed": 0.0,
            "state": "requires_confirmation",
            "clientSecret": "e007a135-07ea-4cc8-897e-9081f3f7d9d9_51266228-527e-4add-a4e8-bac1b141ff46"
        }
    }
}
Notifying customers of a subscription's renewal
Once you either synchronously or asynchronously receive an order in an accepted state, you can fulfill the subscription's products, and then capture payment. Upon receipt of the order.charge.capture.complete, notify end customers within 24 hours that the subscription has been renewed.
In the Subscription Notifications article (refer to Learning tools for access information), you can find a comprehensive list of the information you're required to include in this notification.
Handling subscription updates
After most subscription change events, you can continue processing renewals using the same billingAgreementId generated during the acquisition.‌
In other scenarios, when the underlying subscription is modified, we recommend that you generate a new billing agreement.
As a rule of thumb, you should create a new billing agreement whenever the scope of a subscription update is not defined in the autorenewal terms.‌
The following provides some common subscription change scenarios and indicates whether a new billing agreement is recommended.
Scenario
Details
Same or new billingAgreementId?
Modifying payment methods
The payment method is updated mid-term or the customer supplies a new payment method. Two common examples are when the customer performs a mid-term update of a credit card's expiration date or, during a manual renewal, the
customer provides a credit card that is different from the one used when acquiring the subscription.
Same
Metered billing
Some subscriptions use a metered approach to billing. For example, an API subscription service might allow only a certain number of requests per month. When customers exceed that pre-defined threshold, they are charged on a per request basis, potentially causing their monthly bills to fluctuate.
Same
Free trials
After a designated period of time, it's common for free trials to convert to paid subscriptions. Unless a customer actively cancels the trial, these conversions are typically automatic.

As long as the acquisition agreement specifies this condition, you should continue using the same billing agreement in all post-conversion transactions.
Same
Upgrades
When you receive a customer-initiated request to upgrade the subscription to a higher service level, we recommend you generate a new billing agreement. For example, a customer currently enrolled in a $100/month plan might request an upgrade to a $200/month plan.
New
Modifying a subscription's billing cycle or duration
A customer requests a modification to a subscription's billing cycle or duration. For example, the customer might want to switch from monthly to annual billing.
New
Updating a subscription's quantity
This describes a customer-initiated change to the quantity of a subscription line item.
​
In this scenario, since Digital River's standardized autorenewal terms do not stipulate that the customer's saved payment information can be used for quantity modifications, you need to generate a new billing agreement.
New
Adding a new subscription
A customer purchases an add-on subscription product or service and the add-on requires creating a unique line item with subscription information.
New

Handling subscription acquisitions

Subscription information

Last modified 24d ago

Scenario	Details	Same or new `billingAgreementId`?
Modifying payment methods	The payment method is updated mid-term or the customer supplies a new payment method. Two common examples are when the customer performs a mid-term update of a credit card's expiration date or, during a manual renewal, the customer provides a credit card that is different from the one used when acquiring the subscription.	Same
Metered billing	Some subscriptions use a metered approach to billing. For example, an API subscription service might allow only a certain number of requests per month. When customers exceed that pre-defined threshold, they are charged on a per request basis, potentially causing their monthly bills to fluctuate.	Same
Free trials	After a designated period of time, it's common for free trials to convert to paid subscriptions. Unless a customer actively cancels the trial, these conversions are typically automatic. As long as the acquisition agreement specifies this condition, you should continue using the same billing agreement in all post-conversion transactions.	Same
Upgrades	When you receive a customer-initiated request to upgrade the subscription to a higher service level, we recommend you generate a new billing agreement. For example, a customer currently enrolled in a $100/month plan might request an upgrade to a $200/month plan.	New
Modifying a subscription's billing cycle or duration	A customer requests a modification to a subscription's billing cycle or duration. For example, the customer might want to switch from monthly to annual billing.	New
Updating a subscription's quantity	This describes a customer-initiated change to the `quantity` of a subscription line item. In this scenario, since Digital River's standardized autorenewal terms do not stipulate that the customer's saved payment information can be used for quantity modifications, you need to generate a new billing agreement.	New
Adding a new subscription	A customer purchases an add-on subscription product or service and the add-on requires creating a unique line item with subscription information.	New