Handling external subscription acquisitions

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

• Flag a subscription as 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

Before 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 actively participates 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": "[e-mail]",
    "billTo": {
        "address": {
            "line1": "10381 Bren Rd W",
            "city": "Minnetonka",
            "postalCode": "55343",
            "state": "MN",
            "country": "US"
        },
        "name": "William Brown",
        "email": "[e-mail]"
    },
    "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": "[e-mail]",
                    "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

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).

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, 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() 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

Customers can create a new source or authenticate a saved source to fund a recurring transaction.

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.‌

Next steps

For details on auto-renewals and updates, refer to Managing an external subscription.