Providing subscription information
Learn how to provide the customer's subscription information that Digital River needs to process recurring payments.
Billing agreement identifier
As part of the PSD2 Strong Customer Authentication (SCA) initiative, payment processors require extra information when processing merchant-initiated credit card transactions. To ensure that you adhere to the new mandate, you'll need to make use of billing agreements.
A billing agreement consists of the terms customers agree to when they consent to have their credit card details applied to any type of recurring purchase. The identifier of the agreement is then referenced on subsequent renewals.
If you sell your product or service as part of a subscription and you want to use an external subscription engine to manage your subscriptions, you must :
- Create a product in Global Commerce without selecting the Subscription option and deploy the product.
- Include the
subscriptionInfohash table. As reseller of record, Digital River is required to collect the basic information contained in this data structure.
To add a subscription to a product for a customer, include
subscriptionInfo in the LineItem array. You can add subsciptionInfo to the POST/carts, POST /line-items, or POST /line-items/{lineItemsId} requests. The following POST/carts request includes the subscription parameters related to auto renewals, free trials, and the terms displayed to the customer. You can also provide the subscription and the billing agreement identifiers. cURL
1
curl --location --request POST 'https://api.digitalriver.com/v1/shoppers/me/carts/active' \
2
--header 'Content-Type: application/json' \
3
--header 'Authorization: Bearer {{Token}}' \
4
--data-raw '{
5
"cart": {
6
"ipAddress": "{{BrowserIP}}",
7
"lineItems": {
8
"lineItem": [
9
{
10
"quantity": 1,
11
"product": {
12
"id": "{{ExternalSubPID}}"
13
},
14
"subscriptionInfo": {
15
"autoRenewal": true,
16
"terms": "I agree to have client charge all my future bills on this card",
17
"freeTrial": false,
18
"billingAgreementId": null
19
}
20
}
21
]
22
}
23
}
24
}'
Copied!
The subscriptionInfo hash table appears in the following responses:
POST /carts/active, POST /line-items, POST /line-items/{lineItemsId}, and POST /submit-cart , and GET /orders (if available). To get the billingAgreementId, submit the cart.JSON
1
...
2
"lineItems": {
3
"lineItem": [
4
{
5
"id": "12151550082",
6
"quantity": "1",
7
"product": {...
8
},
9
"lineItemState": "Downloadable",
10
"lineItemStateDetails": {
11
"description": "Downloadable - 1",
12
"backOrdered": "0",
13
"shipped": "0",
14
"returned": "0",
15
"pendingReturn": "0"
16
},
17
"pricing": {...
18
},
19
"downloads": {
20
"downloadUri" : [
21
"http://wgtintot12.digitalriver.com/wgt/9B5A4FCEF11DA80C/171F14235882A3D3E56B5723F9D46513279A35381E6ECCFA38DC305C96D769173E906E98A04A2B5B3CFFB85C93D810E7B365B18617EBAE4682F5E46FAD1C55CE291C52E8142F3D624C7461A8833978160451C577DBEF2976/demosft1/software.zip"
22
]
23
},
24
"digitalRights": {},
25
"subscriptionInfo": {
26
"autoRenewal": "true",
27
"terms": "CAPI-395 Anonymous flow",
28
"freeTrial": "false",
29
"startTime": "2020-09-13T00:00:00.000z",
30
"endTime": "2021-09-13T00:00:00.000z",
31
"billingAgreementId": "c713ec4d-5fcf-4a3d-9a0c-bcb214480b8d"
32
}
33
}
34
},
35
...
Copied!
To create a merchant-initiated transaction (MIT) that charges on renewal of the subscription, include the
billingAgreementId and a chargeType of merchant_initiated in the POST /carts request. transaction (MIT) to add a subscription would look like this:cURL
1
curl --location --request POST 'https://api.digitalriver.com/v1/shoppers/me/carts/active' \
2
--header 'Content-Type: application/json' \
3
--header 'Authorization: Bearer {{Token}}' \
4
--data-raw '{
5
"cart": {
6
"ipAddress": "{{ServerIP}}",
7
"chargeType": "merchant_initiated",
8
"lineItems": {
9
"lineItem": [
10
{
11
"quantity": 1,
12
"product": {
13
"id": "{{RenewalPID}}"
14
},
15
"subscriptionInfo": {
16
"billingAgreementId": "{{billingAgreementId}}"
17
}
18
}
19
]
20
}
21
}
22
}'
Copied!
Auto renewal
cURL
1
curl --location --request POST 'https://api.digitalriver.com/v1/shoppers/me/carts/active' \
2
--header 'Content-Type: application/json' \
3
--header 'Authorization: Bearer {{Token}}' \
4
--data-raw '{
5
"cart": {
6
"ipAddress": "{{ServerIP}}",
7
"chargeType": "merchant_initiated",
8
"lineItems": {
9
"lineItem": [
10
{
11
"quantity": 1,
12
"product": {
13
"id": "{{RenewalPID}}"
14
},
15
"subscriptionInfo": {
16
"billingAgreementId": "{{billingAgreementId}}"
17
}
18
}
19
]
20
}
21
}
22
}'
Copied!
Use the
autoRenewal parameter to tell us whether the subscription is automatically or manually renewed. If true, customers must have agreed to have their card information stored on file and charged at the start of every billing cycle. To do this, you must, at a minimum, attach a Source to the payment option associated with the subscription and make sure the Source is reusable. If
false, then the customer needs to manually renew the subscription by resupplying payment date. You can facilitate this by creating a new instance of Drop-in to collect the payment source. Free trial
When you offer customers a free trial period to test run the membership, but you also collect their credit card information, ensure that you set the
freeTrial attribute to true. Digital River needs to know that credit card details are being collected, even when a charge does not occur.Terms
Use the
terms parameter to provide the subscription's auto renewal terms that are displayed to the customer at the point of acquisition.Subscription identifier
At the time of the acquisition, your subscription management system, not Digital River, assigns the
subscriptionId and passes the value in a POST/carts request. Whenever you process a renewal, give us the same
subscriptionId you provided at the point of acquisition. If the values don't match, we treat the request as a subscription acquisition rather than a renewal. In the next version of the Digital River API, the
subscriptionId attribute will be deprecated. For this reason, and to ensure you are PSD2 compliant, we recommend you use the billing agreement identifier to process subscription renewals. Creating a billing agreement
You'll first need to ensure that you've attached a source to the payment option associated with the subscription and that the source is reusable.
You'll then apply the shopper to a cart that includes
subscriptionInfo hash table in a POST/apply-shopper request and include billingAgreementId. After you submit the cart, Digital River generates a billing agreement and returns the
billingAgreementId in the POST /submit-cart response.A one-to-one relationship exists between a subscription item and a billing agreement. For example, if your
POST/submit-cart request contains two line items and both have a subscriptionInfo hash table, then Digital River creates two separate billing agreements and returns two billing agreement identifiers.For each subscription that you create, you should persist the
billingAgreementId that is returned in the response. This is so that you can later provide the value when renewing the subscription. Using the billing agreement identifier
When it's time to process a renewal, retrieve the
billingAgreementId you persisted with that subscription. Then, you should include the value in the subscriptionInfo hash table of a POST Cart request. You should submit the same
billingAgreementId when renewing the subscription, even if the customer is using a different credit card to pay for the transaction. Finally, pass the order identifier returned in the response to a create Cart request. Continue to persist the same
billingAgreementId for future renewals.Commitment price
The
commitmentPrice hash table appears when you get a product by identifier. A commitmentPrice is the committed purchase price for a loan or subscription. JSON
1
...
2
"pricing": {
3
"uri": "https://api.digitalriver.com/v1/shoppers/me/products/64578500/pricing",
4
"listPrice": {
5
"currency": "USD",
6
"value": "19.99"
7
},
8
"salePriceWithQuantity": {
9
"currency": "USD",
10
"value": "19.99"
11
},
12
"formattedListPrice": "$19.99",
13
"formattedSalePriceWithQuantity": "$17.99",
14
"msrpPrice": {
15
"currency": "USD",
16
"value": "19.99"
17
},
18
"formattedMsrpPrice": "$2.00",
19
"listPriceIncludesTax": "false",
20
"formattedCommitmentPrice": "$240.00",
21
"commitmentPrice": {
22
"currency": "USD",
23
"value": "240.00"
24
}
25
},
26
...
Copied!
A customer must provide a recurring payment method to pay for a commitment-based subscription. If a customer provides a non-recurring payment method, the following error appears.
JSON
1
{
2
"errors": {
3
"error": [
4
{
5
"relation": "https://api.digitalriver.com/v1/shoppers/CartsResoure",
6
"code": "invalid-payment-method",
7
"description": "Cannot use non-recurring payment method to purchase a commitment type subscription"
8
}
9
]
10
}
11
}
Copied!
Last modified 1yr ago