Providing subscription information

Learn how to provide the customer's subscription information that Digital River needs to process recurring payments.

Billing agreement identifier

A billing agreement identifier is an essential component in managing recurring payments for subscription-based services. It is a unique reference linking a customer's billing consent to regular payment transactions, thus ensuring seamless and secure automatic renewals. This identifier facilitates compliance with regulatory standards such as the PSD2 Strong Customer Authentication (SCA) requirements, providing additional security and verification for merchant-initiated transactions. Understanding and implementing billing agreement identifiers is crucial for any business offering subscription services.

A billing agreement identifier is a unique reference number assigned to a billing agreement. Customers use this identifier to consent to recurring charges on their credit cards. This identifier is vital for processing subsequent renewals and ensuring compliance with the PSD2 SCA requirements.

A billing agreement consists of the terms customers agree to when they consent to have their credit card details applied to any 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 subscriptionInfo hash table. Digital River, as the reseller of record, is required to collect the basic information in this data structure.

Adding a subscription to a product

To add a subscription to a product for a customer, include the subscriptionInfo hash table in the LineItem array. The subscriptionInfo can be added to the following requests:

• POST /v1/shoppers/me/carts/active

• POST /v1/shoppers/me/carts/active/line-items

• POST /v1/shoppers/me/carts/active/line-items/{lineItemsId}

The subscriptionInfo should include details about the subscription parameters, such as the billing agreement identifier, the subscription term, and any additional identifiers specific to the product display for the customer.

The following POST /v1/shoppers/me/carts/active 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

curl --location --request POST 'https://api.digitalriver.com/v1/shoppers/me/carts/active' \
--header 'Authorization: Bearer {Your_Acces_Token}' \
...
--data-raw '{
    "cart": {
        "ipAddress": "{{BrowserIP}}",
        "lineItems": {
            "lineItem": [
                {
                    "quantity": 1,
                    "product": {
                        "id": "{{ExternalSubPID}}"
                    },
                    "subscriptionInfo": {
                        "autoRenewal": true,
                        "terms": "I agree to have client charge all my future bills on this card",
                        "freeTrial": false,
                        "billingAgreementId": null
                    }
                }
            ]
        }
    }
}'

200 OK response

Getting a billing agreement

To get the billingAgreementId, send a POST v1/shopper/me/carts/active/submit-cart request to submit the cart. The following 200 OK response includes the billingAgreementId from the payment service.

cURL

curl --location --request POST 'https://api.digitalriver.com/v1/shoppers/me/carts/active/submit-cart' \
--header 'Authorization: Bearer {Your_Acces_Token}' \

200 OK response

Creating a renewable subscription

To create a transaction that charges on the renewal of a subscription, you need to include the billingAgreementId and set the chargeType to merchant_initiated in the POST /v1/shoppers/me/carts/active request. This ensures that the subscription is renewed automatically using previously obtained billing agreement details.

cURL

curl --location --request POST 'https://api.digitalriver.com/v1/shoppers/me/carts/active' \
--header 'Authorization: Bearer {{Token}}' \
...
--data-raw '{
    "cart": {
        "ipAddress": "{{ServerIP}}",
        "chargeType": "merchant_initiated",
        "lineItems": {
            "lineItem": [
                {
                    "quantity": 1,
                    "product": {
                        "id": "{{RenewalPID}}"
                    },
                    "subscriptionInfo": {
                        "billingAgreementId": "{{billingAgreementId}}"
                    }
                }
            ]
        }
    }
}'

Automatically renewing a subscription

To use the autoRenewal parameter, set it to true if you want the subscription to renew automatically. This requires customers' consent to store their card information for future billing cycles. Ensure you have obtained this agreement and associated the billing details with the subscription.

When you set autoRenewal to true, you must attach a Source to the payment option associated with the subscription and make sure the Source is reusable.

If you set autoRenewal to false, customers must manually renew the subscription by providing payment details again. Facilitate this process by prompting them to resubmit their payment information at the end of the billing cycle by creating a new instance of Drop-in to collect the payment source.

cURL

curl --location --request POST 'https://api.digitalriver.com/v1/shoppers/me/carts/active' \
--header 'Authorization: Bearer {{Token}}' \
...
--data-raw '{
    "cart": {
        "ipAddress": "{{ServerIP}}",
        "chargeType": "merchant_initiated",
        "lineItems": {
            "lineItem": [
                {
                    "quantity": 1,
                    "product": {
                        "id": "{{RenewalPID}}"
                    },
                    "subscriptionInfo": {
                        "billingAgreementId": "{{billingAgreementId}}"
                    }
                }
            ]
        }
    }
}'

Free trial

A free trial period allows customers to test their membership before committing to a paid subscription. During this period, set the freeTrial attribute to true in your API request. Collect customers' credit card information upfront, even though no charges will be made initially. Inform Digital River about the collection of credit card details to ensure compliance.

When you offer customers a free trial period to test run the membership and also collect their credit card information, ensure that you set the freeTrial attribute to true. Digital River must be informed of the collection of credit card details, even if no charge occurs.

Terms

The terms parameter is used to present the auto-renewal conditions of the subscription to the customer at the time of acquisition. This ensures transparency and complies with legal requirements by informing customers about their subscription renewal's ongoing nature and conditions.

Subscription identifier

The subscriptionId is a unique identifier assigned by your subscription management system during the initial subscription acquisition. This identifier is crucial for managing the subscription lifecycle, including renewals and cancellations. It must be included in a POST /carts request during the initial acquisition and consistently used in subsequent renewal requests. If the subscriptionId provided during a renewal does not match the original one, Digital River will treat the request as a new acquisition rather than a renewal.

Creating a billing agreement

Creating a billing agreement is a key step in managing subscriptions effectively. It ensures that the customer's payment method is securely stored and can be automatically charged for subscription renewals. This guide will walk you through establishing a billing agreement, including associating relevant information with the subscription and submitting the necessary requests to Digital River's API.

To create a billing agreement, follow these steps:

1. Ensure that you've attached a source to the payment option associated with the subscription and that the source is reusable.

2. Apply the shopper to the cart, including the subscriptionInfo hash table, using a POST /apply-shopper request, and include billingAgreementId.

3. Submit the cart using a POST /submit-cart request.

After submission, Digital River will generate a billing agreement and return the billingAgreementId in the 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 you create, you should persist the billingAgreementId that is returned in the response so 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 uses 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 encapsulates the committed purchase price for a loan or subscription. It appears during a product retrieval by identifier and includes details such as currency and value. This ensures transparency on the total amount a customer commits to for the duration of the subscription or loan.

200 OK response

...
    "pricing": {
      "uri": "https://api.digitalriver.com/v1/shoppers/me/products/64578500/pricing",
      "listPrice": {
        "currency": "USD",
        "value": "19.99"
      },
      "salePriceWithQuantity": {
        "currency": "USD",
        "value": "19.99"
      },
      "formattedListPrice": "$19.99",
      "formattedSalePriceWithQuantity": "$17.99",
      "msrpPrice": {
        "currency": "USD",
        "value": "19.99"
      },
      "formattedMsrpPrice": "$2.00",
      "listPriceIncludesTax": "false",
      "formattedCommitmentPrice": "$240.00",
      "commitmentPrice": {
        "currency": "USD",
        "value": "240.00"
      }
    },
...

A customer must provide a recurring payment method for a commitment-based subscription. When a customer provides a non-recurring payment method for a commitment-based subscription, the system will return the following error:

Error response

{
    "errors": {
        "error": [
            {
                "relation": "https://api.digitalriver.com/v1/shoppers/CartsResoure",
                "code": "invalid-payment-method",
                "description": "Cannot use non-recurring payment method to purchase a commitment type subscription"
            }
        ]
    }
}