If you're pairing the checkout solution with , this page explains how to process it:
Once you , you must activate the subscription, fulfill the goods, and manage renewals. Refer to the page for details on handling these and other processes.
Subscription acquisitions
During subscription acquisitions, you must:
and
Creating a subscription
In , you define subscriptions in items[]. Checkouts can contain either a single items[] with or. We also support .
For each items[].subscriptionInfo in the request:
Use planId to associate the subscription with a plan. For details, refer to .
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 .
Set 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 .
If you don't provide a unique subscriptionId, we generate one for you.
Checkouts with multiple subscriptions
Checkouts with subscription and non-subscription 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
Displaying terms and acquiring consent
Acquiring payment
During acquisition checkouts, you can give customers the option to:
Creating a new payment source
Each payment method, accompanied by the subscription's terms and conditions, is displayed in the modal window.
If the request is successful, the response contains the payment methods that apply to the transaction.
Set type to the payment method selected by the customer
Authenticating a saved payment source
Managing subscriptions after acquisition
Trial subscription acquisitions
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:
Managing trial subscriptions after acquisition
In subscription acquisitions, make sure you also set the checkout's to customer_initiated.
can contain multiple with . 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:
Digital River's subscription service supports building checkouts containing subscription and non-subscription line items and successfully . However, the subscription line items must all .
After you submit the request, Digital River creates a , sets it to state to draft and then generates an with a of .
In the response's body and the event's data.object, the 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 .
Since Digital River's subscription service doesn't support manual renewals, always returns true .
Refer to the page for details on how to handle manual renewals, where you invite customers to actively renew subscriptions at a designated time.
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 .
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 or . In either case, the should match those displayed to customers.
For required disclosures, see the article (refer tofor access information).
A subscription's terms are displayed in the modal window if you're using . For details, see the on this page.
If you're using , present our standardized subscription terms and save the payment agreement by calling the , 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 can then use autorenewalPlanTerms.localizedText to set mandate.terms in the method's configuration object.
After you , the subscription's terms are stored in the .
or
How you create a payment to fund a recurring transaction depends on whether your integration uses or .
For more details, refer to the on the page.
After , configure :
Use the checkout's to set sessionId
If your integration sends the customer's billing information in the billTo, then it's not necessary to pass billingAddress
In , set:
to checkout
to true
to subscription
to true and to false. These two settings (along with the value of true), prompt Drop-in payments to display the combined autorenewal and save payment agreement.
Pass the configuration object to createDropin()and in the appropriate container. If the request is successful, returns the transaction's eligible payment methods:
If customers click the without agreeing to the terms, Drop-in prevents the transaction from proceeding.
If customers consent to the terms and submit their payment information and the resulting create source request is successful, then the event's data contains a that is and . 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 and the .
After , send the checkout's to your front end and use it to set sessionId in the configuration object of .
Based on these payment methods, to collect the customer's sensitive payment information.
After customers select a payment method, , and submit their payment information, configure :
Use the checkout's to set sessionId.
Set to subscription and futureUse to true
Use the to set mandate.terms
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 and .
For more information, refer to the .
Next, send the identifier and to your backend.
Submit a POST /customers/{customerId}/sources/{sourceId} to attach the source to the customer. This flips the source's 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 .
You should also retrieve mandate.terms from the source and use this value to set each of the . This ensures that the subscription's terms are added to the .
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 , send the to your front end and use it to set sessionId in the configuration object of .
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.
If the customer selects a saved source, passes its sources[].id and sources[].clientSecret (along with the checkout's ) to . This method determines whether is required.
If the response status is complete or authentication_not_required, the method resolves, allowing your integration to .
For additional details, refer to the section on on the page.
After you , you'll need to activate the subscription and process renewals. To learn more, refer to the page.
You handle free-trial subscription acquisitions in much the same way as .
In , 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 .
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 .
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 .
Refer to on the page for details on how to process a trial subscription after you .
{
"type": "conflict",
"errors": [
{
"code": "plan_limit_reached",
"parameter": "planId",
"message": "Only one unique subscription plan can be supported in a checkout"
}
]
}
...
digitalRiver.retrieveAvailablePaymentMethods({
"sessionId": "1c86a97f-45ea-4d73-8c99-ca533e392ab1"
}).then(function(result) {
//do something with the result
console.log(result)
});
...
Available payment methods
[
{
"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"
}
]
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);
}
});
...
digitalRiver.retrieveAvailablePaymentMethods({
"sessionId": "1c86a97f-45ea-4d73-8c99-ca533e392ab1"
}).then(function(result) {
//do something with the result
console.log(result)
});
...
Available payment methods
[
{
"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"
}
]
{
"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."
}
]
}
Handling subscription acquisitions
If you're pairing the Direct Integration solution with Digital River's subscription service, learn how to handle acquisitions.
