Subscription payments
Learn how to handle payments for auto-renewing subscriptions
Every auto-renewing subscription must be associated with a reusable payment source. So, during subscription acquisitions, make sure that you only display supported payment methods to the customer. As with most transactions, you can provide customers the option to create a new payment source or authenticate an existing payment source. Once that process is complete, attach the source to the customer and attach the source to the checkout.

Displaying supported payment methods

Auto-renewing subscriptions must be associated with a reusable payment source. As a result, all payment methods displayed to the customer need to support reusability. How you do this depends on whether you're using Drop-in or DigitalRiver.js.
Drop-in
DigitalRiver.js
The checkout's autoRenewal must be true before you call the createDropin() method. This prompts Drop-in to only display reusable payment methods.
Digital River's subscription service currently only supports credit card transactions. So, if you're using this service, you should also restrict enabledPaymentMethods to creditCard.
If you're using DigitalRiver.js to create or authenticate a subscription's payment source, autoRenewal must be set to true.
You can then configure retrieveAvailablePaymentMethods() with the checkout's currency , country, and payment session identifier, and set supportsRecurringto true. Once called, the method returns an array of applicable paymentMethods.
When customers elect to pay with a new payment method, you should only present them with options contained in this paymentMethods array.
If customers elect to set up a subscription with a saved payment method, use the type attribute contained within each element of the paymentMethods array to filter out unsupported types in the customer's saved sources. You can then use this filtered list to display applicable saved sources to customers in your UI and then authenticate their selection.

Creating and saving a subscription's payment source

During the acquisition process, you can use Drop-in or DigitalRiver.js to create a payment source. In either case, you must perform some specific, subscription-related configurations.
Drop-in
DigitalRiver.js
In the configuration options of the createDropIn() method , set flow to checkout and usage to subscription. You must also provide the transaction's payment session identifier and ensure that the Digital River compliance section is displayed.
1
let digitalriverpayments = new DigitalRiver("pk_hc_a209389e4588433bb6e00b32466b82c3", {
2
"locale": "en_US"
3
});
4
5
let configuration = {
6
"sessionId": "2bc96772-1142-4289-9d20-f6905591d7e4",
7
"options": {
8
"flow": "checkout",
9
"showComplianceSection": true,
10
"showSavePaymentAgreement": false,
11
"showTermsOfSaleDisclosure": true,
12
"usage": "subscription"
13
},
14
"billingAddress": {
15
...
16
},
17
onSuccess: function(data) {},
18
onError: function(data) {},
19
onReady: function(data) {},
20
onCancel: function(data) {}
21
}
22
23
let dropin = digitalriverpayments.createDropin(configuration);
24
dropin.mount("drop-in-container");
Copied!
Create and embed elements to collect sensitive credit card information on your payment form.
When configuring the createSource() method in DigitalRiver.js, set usage to subscription, futureUse to true, and provide the transaction's payment session identifier.
For additional details on how to perform these configurations, refer to the information on applying and saving a payment method during a subscription acquisition that resides on our building payment workflows page.
When correctly configured, both the DigitalRiver.js and Drop-in source creation methods return a primary source that is chargeable, supportsStorage and readyForStorage.
Your implementation should retrieve the unique id of this payment source and use that value to attach the source to the customer. Doing so makes the source reusable. This means it can be used in both the subscription's acquisition and as the designated source in renewals.
Source
1
{
2
"source": {
3
"clientId": "gc",
4
"channelId": "paylive",
5
"liveMode": false,
6
"id": "f82be808-b5b8-4403-bf56-8e83dfa21475",
7
"sessionId": "5b14dada-492b-450d-aa56-967fd45c89ed",
8
"clientSecret": "f82be808-b5b8-4403-bf56-8e83dfa21475_0452c5cd-cbc7-445d-bc34-eb700d49ee0c",
9
"type": "creditCard",
10
"reusable": false,
11
"owner": {
12
"firstName": "John",
13
"lastName": "Doe",
14
"email": "[email protected]",
15
"phoneNumber": "952-253-1234",
16
"organization": "Digital River",
17
"address": {
18
"line1": "10380 Bren Road W",
19
"city": "Minnetonka",
20
"state": "MN",
21
"country": "US",
22
"postalCode": "55343"
23
}
24
},
25
"amount": "521.04",
26
"currency": "USD",
27
"state": "chargeable",
28
"upstreamId": "C99AFF1F-9CDB-4EE1-AEA9-EEE20464802F",
29
"creationIp": "161.69.123.10",
30
"createdTime": "2021-05-27T22:09:28.453Z",
31
"updatedTime": "2021-05-27T22:09:28.453Z",
32
"flow": "standard",
33
"mandate": {
34
"terms": "I have read and agree to the terms and charges above.",
35
"signedTime": "2021-05-27T22:09:27.853Z"
36
},
37
"usage": "subscription",
38
"creditCard": {
39
"brand": "Visa",
40
"expirationMonth": 2,
41
"expirationYear": 2025,
42
"lastFourDigits": "1111"
43
}
44
},
45
"readyForStorage": true,
46
"supportsStorage": true
47
}
Copied!
Once the source is saved to the customer's account, your workflow should also attach the newly created source to the checkout.

Authenticating a saved payment source

If you allow customers to use a saved payment source to set up an auto-renewing subscription, you need to determine whether Strong Customer Authentication (SCA) is required. You do this by configuring and calling the DigitalRiver.js authenticate source method.
Drop-in does not currently support retrieving saved payment methods.
Once you display a customer's applicable saved sources, and the customer makes a selection, retrieve the source's identifier and clientSecret. Then pass those values (along with the checkout's payment session identifier) to authenticateSource().
Customer
Checkout
authenticateSource( )
1
{
2
"id": "533319260336",
3
...
4
"defaultSourceId": "5e359d60-1d23-4234-84ee-e1c9b3ed7edc",
5
"sources": [
6
{
7
"id": "5e359d60-1d23-4234-84ee-e1c9b3ed7edc",
8
...
9
"type": "creditCard",
10
"reusable": true,
11
"state": "chargeable",
12
"owner": {
13
...
14
},
15
"clientSecret": "5e359d60-1d23-4234-84ee-e1c9b3ed7edc_bf74c04c-8586-41e2-964a-f5e618d2b7e3",
16
...
17
}
18
],
19
...
20
}
Copied!
1
{
2
"id": "50a72152-4a61-4e4a-b9e1-2ab5db891105",
3
...
4
"items": [
5
{
6
"id": "afa1cb82-f672-40f6-8429-a522db45b4cb",
7
"skuId": "0181a7a9-610e-48c5-89e5-84ca06c69f03",
8
...
9
"subscriptionInfo": {
10
"autoRenewal": true,
11
"freeTrial": false,
12
"billingAgreementId": "c567f049-9ec4-4c63-829b-efe01427a8a9"
13
},
14
...
15
}
16
],
17
...
18
"chargeType": "merchant_initiated",
19
...
20
"payment": {
21
"session": {
22
"id": "f5dd814a-ecee-4f7e-bf7c-4635f0c19c91",
23
...
24
}
25
}
26
}
Copied!
1
...
2
digitalriver.authenticateSource({
3
"sessionId": "f5dd814a-ecee-4f7e-bf7c-4635f0c19c91",
4
"sourceId": "5e359d60-1d23-4234-84ee-e1c9b3ed7edc",
5
"sourceClientSecret": "5e359d60-1d23-4234-84ee-e1c9b3ed7edc_bf74c04c-8586-41e2-964a-f5e618d2b7e3",
6
"returnUrl": "https://mypage.com"
7
});
8
...
Copied!
After the customer completes the necessary authentication (or we determine that authentication isn't required), your integration should attach the authenticated source to the checkout.
For additional details, refer to the information on retrieving a saved payment source during a subscription acquisition that resides on our building payment workflows page.

Modifying subscription payments

Digital River's subscription service allows you to modify payment sources in active and activePendingInvoice subscriptions.
For more information, refer to the section on updating subscriptions.
Once customers go to their subscription management page, select an ongoing subscription, and then elect to modify its payment method, your UI can allow customers to:

Updating a subscription's payment source

If customers elect to update a subscription's payment source, make a GET/subscriptions/{subscriptionId} request. From the response, retrieve and save sourceId.
Send this value as a path parameter in a GET/sources/{sourceId} request. From the response, retrieve the values you want from owner and creditCard and display this information to the customer in your UI, along with the option to edit either their billing address information or credit card expiration date.
Source
1
{
2
"id": "83961238-27b5-4205-a43f-dfe06b872ec4",
3
"createdTime": "2021-09-01T15:23:04Z",
4
"type": "creditCard",
5
"reusable": true,
6
"state": "chargeable",
7
"customerId": "542920590336",
8
"owner": {
9
"firstName": "William",
10
"lastName": "Brown",
11
"email": "[email protected]",
12
"address": {
13
"line1": "10381 Bren Rd W",
14
"city": "Minnetonka",
15
"postalCode": "55343",
16
"state": "MN",
17
"country": "US"
18
}
19
},
20
"clientSecret": "83961238-27b5-4205-a43f-dfe06b872ec4_ea2b6e0a-2e9a-4ee2-bfc8-51d3fbc88c38",
21
"creditCard": {
22
"brand": "Visa",
23
"expirationMonth": 7,
24
"expirationYear": 2027,
25
"lastFourDigits": "1111"
26
},
27
"liveMode": false
28
}
Copied!

Billing address information

If customers elect to edit their billing information, present them with a form to provide their full name, email, and address (line 1, line 2, city, state, country, postal code) associated with the credit card.

Card expiration date

If customers elect to edit their credit card's expiration date, use a cardexpiration element to present them with an input field.

Configuring and calling the update source method

Once customers enter and save their changes, retrieve the submitted data. Depending on whether customers submit updated (a) billing address information, (b) card expiration information or (c) both, configure the appropriate version of updateSource() . In both versions, the source's id and clientSecret are needed to configure the method.
Once the method is invoked, use the response to verify that state is chargeable and reusable is true .

Updating a subscription with a new payment source

If customers elect to update their subscription with a new payment source, you need to use either Drop-in or DigitalRiver.js.
Since this is an account management flow, you don't need to send a payment session identifier in the source creation method.
Drop-in
DigitalRiver.js
In the configuration options of the createDropIn() method , set flow to managePaymentMethods and usage to subscription. You must also restrict the enabled payment methods to creditCard.
1
let configuration = {
2
"options": {
3
"usage": "subscription",
4
"flow": "managePaymentMethods",
5
"showComplianceSection": true,
6
"showTermsOfSaleDisclosure": false,
7
},
8
"billingAddress": {
9
...
10
},
11
"paymentMethodConfiguration": {
12
"enabledPaymentMethods": [
13
"creditCard"
14
]
15
},
16
onSuccess: function (data) { },
17
onCancel: function(data) { },
18
onError: function (data) { },
19
onReady: function(data) { }
20
};
Copied!
Once the createDropin() method is invoked, this configuration prompts Drop-in to display credit card input fields and the save payment agreement. If customers enter their information and click the configurable button without accepting the agreement, Drop-in blocks the workflow from proceeding.
Once customers consent and a source is successfully created, we send the onSuccess event to your front-end. In the event's payload, verify that the payment source is readyForStorage and in a chargeable state.
Create and embed elements to collect sensitive credit card information on your payment form.
Present our standardized save payment agreement by calling the get compliance details method, retrieving saveCardMandate.localizedText and then displaying that text with an appropriate acceptance control.
Your code should be written so that customers must accept these terms before proceeding. Use saveCardMandate.localizedText to set mandate.terms in the createSource() method's configuration object.
When configuring createSource(), you should also set type to creditCard, usage to subscription , and futureUse to true.
1
var payload = {
2
"type": "creditCard",
3
"futureUse": true,
4
"usage": "subscription",
5
...
6
"mandate": {
7
"terms": "Yes, please save this account and payment information for future purchases."
8
}
9
}
10
11
digitalriver.createSource(payload).then(function(result) {
12
if (result.error) {
13
//handle errors
14
} else {
15
var source = result.source;
16
//send source to back end
17
sendToBackend(source);
18
}
19
});
Copied!
Once the method is invoked, use the response to verify that the payment source is readyForStorage and in a chargeable state.
Send the source identifier, the customer identifier, and the subscription identifier to your back-end and save these values.
Then use a POST/customers/{customerId}/sources/{sourceId} to attach the source to the customer. In the response, verify that reusable is true.
To update the subscription, send the subscription identifier as a path parameter in a POST/subscriptions/{subscriptionId}. In the body of the request, specify the new sourceId.
1
curl --location --request POST 'https://api.digitalriver.com/subscriptions/b8dc06d6-941e-483c-89a1-263874bff3b4' \
2
...
3
--data-raw '{
4
"sourceId": "e4adbcac-1551-4743-9a3e-48dc3883241b"
5
}
Copied!
Once you receive a 200 OK, notify the customer that the subscription's payment source has been replaced.

Updating a subscription with a saved payment source

If customers elect to update a subscription with a saved payment source, retrieve the customer's identifier and send it as a path parameter in a GET/customers/{customerId} request.
From the response, retrieve all sources that have a type of creditCard. For each of these sources, get the values you want from the owner and creditCard blocks and display that information (along with a selection control such as radio buttons) to the customer on your front-end.
Customer
1
{
2
"id": "545144810336",
3
...
4
"sources": [
5
{
6
"id": "7f18e917-3277-4136-9c3d-0ac14b53ed7b",
7
"createdTime": "2021-09-21T19:16:11Z",
8
"type": "creditCard",
9
"reusable": true,
10
"state": "chargeable",
11
"owner": {
12
"firstName": "William",
13
"lastName": "Brown",
14
"email": "[email protected]",
15
"address": {
16
"line1": "10380 Bren Road West",
17
"city": "Minnetonka",
18
"postalCode": "55343",
19
"state": "MN",
20
"country": "US"
21
}
22
},
23
"clientSecret": "7f18e917-3277-4136-9c3d-0ac14b53ed7b_239e460c-5664-4f97-a19d-d053a241db2b",
24
"creditCard": {
25
"brand": "AmericanExpress",
26
"expirationMonth": 7,
27
"expirationYear": 2027,
28
"lastFourDigits": "341 "
29
}
30
},
31
{
32
"id": "64bbc8f3-e728-4c78-af8b-06184bacd957",
33
"createdTime": "2021-09-21T19:14:50Z",
34
"type": "creditCard",
35
"reusable": true,
36
"state": "chargeable",
37
"owner": {
38
"firstName": "William",
39
"lastName": "Brown",
40
"email": "[email protected]",
41
"address": {
42
"line1": "10381 Bren Rd W",
43
"city": "Minnetonka",
44
"postalCode": "55343",
45
"state": "MN",
46
"country": "US"
47
}
48
},
49
"clientSecret": "64bbc8f3-e728-4c78-af8b-06184bacd957_0e921b9b-5e63-4080-956a-2914305e78dc",
50
"creditCard": {
51
"brand": "Visa",
52
"expirationMonth": 7,
53
"expirationYear": 2027,
54
"lastFourDigits": "1111"
55
}
56
}
57
],
58
...
59
}
Copied!
Once the customer makes a selection, retrieve the source's unique identifier.
To update the subscription, send the subscription identifier as a path parameter in a POST/subscriptions/{subscriptionId}. In the body of the request, specify the new sourceId.
1
curl --location --request POST 'https://api.digitalriver.com/subscriptions/b8dc06d6-941e-483c-89a1-263874bff3b4' \
2
...
3
--data-raw '{
4
"sourceId": "e4adbcac-1551-4743-9a3e-48dc3883241b"
5
}
Copied!
Once you receive a 200 OK, notify the customer that the subscription's payment source has been replaced.
Last modified 3mo ago