Subscription information
Learn about a checkout's subscription information
As reseller of record, Digital River is required to collect basic subscription data. As a result, all checkouts that contain recurring products or services must have subscriptionInfo.
A checkout's subscriptionInfo can be used to hold data on:
You'll use this data, along with the charge type, to set up and renew subscriptions.
We manage most of this data if you're using Digital River's subscription service. For integrations that use third party subscription services, you must supply these details in both acquisition and renewal checkouts.
{
"id": "192498520336",
...
"items": [
{
"id": "114400500336",
...
"subscriptionInfo": {
"subscriptionId": "acf73606-a8f1-4126-8156-0467e73ae4ae",
"terms": "Subscription terms accepted by the customer",
"autoRenewal": true,
"freeTrial": false,
"billingAgreementId": "0555aec0-2c75-4306-aa2b-4d102233f1f0",
"startTime": "2021-07-07T13:47:13Z",
"endTime": "2022-07-07T13:47:13Z"
},
...
}
],
...
}For server-initiated auto-renewals, the required subscriptionInfo configurations are autoRenewal set to true, the subscriptionId that you may have provided during the acquisition and the billingAgreementId from the acquisition order. You should also set the checkout's chargeType to merchant_initiated.
Auto renewal
The checkout's autoRenewal indicates whether subscriptions renew automatically or manually. Customers need to actively consent to automatic recurring billing during the acquisition of auto-renewing subscriptions. So, when autorenewal is true, customers must agree to have their payment information stored on file and then charged at the start of every billing cycle.
This setting is also necessary to display only reusable payment methods to customers.
For manual renewals, customers must be actively involved in the acquisition and renewal process. This means that customers supply payment information at the point of sale, which you use to either create a new source or authenticate an existing source.
Free trial
When you offer customers a free trial period to evaluate a subscription, and you also collect their payment information, make sure that you set the checkout's freeTrial to true. To satisfy our reseller of record requirements, Digital River needs to know that payment details are being collected, even when no charge authorization occurs.
If you're using Digital River's subscription service and you want to offer no-charge trial subscriptions, freeTrial also need to be true. For details, refer to Trial subscription acquisitions.
Terms
The checkout's terms hold the subscription's contractual agreement. These should be the Digital River-approved terms displayed to customers during acquisitions. Before creating a subscription, your integration must acquire the customer's active acceptance of them. They define the subscription, provide links to Digital River's terms of sale and privacy policy, and stipulate that the customer agrees to store their payment information for use in renewals.
Billing agreements
As part of the PSD2 Strong Customer Authentication (SCA) initiative, payment processors require extra information when handling merchant-initiated credit card transactions. To comply with this mandate, we make use of billing agreements.
A billing agreement contains, among other things, the terms and conditions agreed to by the customer during a subscription's acquisition. This agreement demonstrates that the customer consented to have their payment information saved and then used in recurring transactions.
By connecting the customer-initiated subscription acquisition with merchant-initiated autorenewals, you comply with relevant PSD2 SCA mandates, and we can make payment authorization requests that are more likely to succeed.
When you convert a checkout to an order, and that checkout contains a line item with subscriptionInfo, we create a billing agreement and return its billingAgreementId in the POST /orders response.
If you're using Digital River's subscription service, we associate the billing agreement with the subscription and make sure billingAgreementId is sent in all renewal requests. For those using a third-party subscription service, you must retrieve billingAgreementId from the acquisition order and pass it in all renewal requests.
Subscription identifier
The checkout's subscriptionId field identifies a subscription.
If you're using Digital River's subscription service, you can pass your own subscriptionId. If you don't, we generate an identifier for you. In either case, the value uniquely identifies the subscription in our system.
If you're using a third-party subscription service, Digital River doesn't generate a subscriptionId. You must send your own value during the checkout process. In this case, whenever you process a renewal, it's best practice to provide us with the same subscriptionId information you sent during the acquisition.
Start and end time
To create an auto-renewing subscription using Klarna, you must provide both a startTime and endTime. This data helps Klarna's risk engine accurately assess a transaction's validity, improving conversion and acceptance rates.
When defining startTime and endTime, make sure you adhere to the date/time standard in the Digital River APIs. If either value is improperly formatted, you receive a 400 Bad Request with an error code of invalid_parameter.
{
"type": "bad_request",
"errors": [
{
"code": "invalid_parameter",
"parameter": "endTime",
"message": "2021-06-07T13:47:13Zxyxy is not a valid timestamp."
}
]
}During acquisitions, specify startTime as the current date. The endTime should be the startTime + the subscription duration, also known as the payment schedule. The payment schedule is how often customers pay for their subscriptions. For example, customers might have a year-long subscription that they pay monthly. We treat the subscription duration and payment schedule as equivalent.
For example, if the startTime of an annually billed subscription is 2021-07-07T13:47:13Z then set endTime to 2022-07-07T13:47:12Z. For a monthly recurring subscription with the same startTime, you would set endTime to 2021-08-07T13:47:12Z.
To renew an open-ended subscription that bills monthly, build a checkout, and convert that checkout to an order every month, updating startDate and endDate in each request until the customer cancels.
Last updated