Handling subscription acquisitions
If you're pairing the Direct Integration solution with Digital River's subscription service, learn how to handle acquisitions.
Last updated
If you're pairing the Direct Integration solution with Digital River's subscription service, learn how to handle acquisitions.
Last updated
If you're pairing the Direct Integrations checkout solution with Digital River's subscription service, this page explains how to process it:
Once you convert the checkout to an order, you must activate the subscription, fulfill the goods, and manage renewals. Refer to the Managing a subscription page for details on handling these and other processes.
During subscription acquisitions, you must:
In , you define subscriptions in items[]. Checkouts can contain either a single items[] with subscriptionInfo or multiple subscription line items. We also support mixed cart checkouts.
For each items[].subscriptionInfo in the request:
Use planId to associate the subscription with a plan. For details, refer to Defining a business model.
Pass terms. To do this, make a request. From the response, retrieve the 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.
For details, refer to Displaying terms and acquiring consent.
Set autoRenewal 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.
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 to customer_initiated.
Digital River's subscription service supports building checkouts containing subscription and non-subscription line items and successfully converting those checkouts to orders. However, the subscription line items must all reference the same plan.
A common use case for these mixed checkouts is to process transactions that combine a one-time physical product with a digital subscription service.
In the response's body and the event's data.object, the subscriptionId 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.
Since Digital River's subscription service doesn't support manual renewals, autoRenewal always returns true .
Refer to the Third party subscription services page for details on how to handle manual renewals, where you invite customers to actively renew subscriptions at a designated time.
A subscription's terms are displayed in the modal window if you're using Drop-in payments. For details, see the Acquiring payment section on this page.
After you convert an acquisition checkout to an order, the subscription's terms are stored in the billing agreement.
During acquisition checkouts, you can give customers the option to:
For more details, refer to the subscriptions section on the Building payment workflows page.
After building a checkout with subscription information, configure createDropin():
Use the checkout's payment session identifier to set sessionId
In options, set:
flow to checkout
showComplianceSection to true
usage to subscription
Pass the configuration object to createDropin()and mount Drop-in payments in the appropriate container. If the request is successful, onReady returns the transaction's eligible payment methods:
Each payment method, accompanied by the subscription's terms and conditions, is displayed in the modal window.
If customers click the configurable continue button without agreeing to the terms, Drop-in prevents the transaction from proceeding.
For details, refer to the Drop-in payments integration guide and the Drop-in payments builder tool.
Submit a POST /customers/{customerId}/sources/{sourceId} to attach the source to the customer. This flips the source's reusable attribute to true You can usethe 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.
Drop-in payments do not currently support retrieving saved payment methods.
If you give customers the option to select a saved payment source during subscription acquisitions, then after building a checkout with subscription information, send the payment session identifier to your front end and use it to set sessionId in the configuration object of retrieveAvailablePaymentMethods().
If the customer selects a saved source, passes its sources[].id and sources[].clientSecret (along with the checkout's payment session identifier) to authenticateSource(). This method determines whether strong customer authentication is required.
If the response status is complete or authentication_not_required, the method resolves, allowing your integration to attach the authenticated source to the checkout.
For additional details, refer to the section on retrieving saved payment sources during subscription acquisitions on the Building payment workflows page.
After you convert the checkout to an order, you'll need to activate the subscription and process renewals. To learn more, refer to the Managing a subscription page.
You handle free-trial subscription acquisitions in much the same way as standard acquisitions.
In free trials, however, you must configure the checkout slightly differently.
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.
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:
Refer to Trial subscription management on the Managing a subscription page for details on how to process a trial subscription after you convert the checkout to an order.
can contain multiple items[] with subscriptionInfo. 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 with multiple items[] that reference different plans, then the following error is returned:
After you submit the request, Digital River creates a , sets it to state to draft and then generates an with a type of subscription.created.
If you , 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.
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 or DigitalRiver.js with elements. In either case, the should match those displayed to customers.
How you create a payment to fund a recurring transaction depends on whether your integration uses Drop-in payments or DigitalRiver.js with elements.
If your integration sends the customer's billing information in the billTo, then it's not necessary to pass billingAddress
showTermsOfSaleDisclosure to true and showSavePaymentAgreement to false. These two settings (along with the autoRenewal value of true), prompt Drop-in payments to display the combined autorenewal and save payment agreement.
If customers consent to the terms and submit their payment information and the resulting create source request is successful, then the onSuccess event's data contains a that is readyForStorage and chargeable. The object also contains the agreed-upon terms (mandate.terms) and the time the customer accepted those terms (mandate.signedTime).
If your integration passes a customer's billing information in the billTo, then it's not necessary to send billingAddress
If the create source request is successful, the response contains a that is readyForStorage and chargeable.
Next, send the identifier and to your backend.
You should also retrieve mandate.terms from the source and use this value to set each of the items[].subscriptionInfo.terms. This ensures that the subscription's terms are added to the billing agreement.
For each payment method contained in the response, determine if its type matches the type of one or more of the sources[]. If it does, you can retrieve those saved sources[] from the and display them as options on your payments page.
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 .
