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 :

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 --location --request POST 'https://api.digitalriver.com/v1/shoppers/me/carts/active' \
--header 'Authorization: Bearer {{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
                    }
                }
            ]
        }
    }
}'

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.

The following POST /submit-cart response includes the billingAgreementId from the payment service.

...
  "lineItems": {
    "lineItem": [
      {
        "id": "12151550082",
        "quantity": "1",
        "product": {...
        },
      "lineItemState": "Downloadable",
      "lineItemStateDetails": {
        "description": "Downloadable - 1",
        "backOrdered": "0",
        "shipped": "0",
        "returned": "0",
        "pendingReturn": "0"
      },
      "pricing": {...
      },
      "downloads": {
        "downloadUri" : [
          "http://wgtintot12.digitalriver.com/wgt/9B5A4FCEF11DA80C/171F14235882A3D3E56B5723F9D46513279A35381E6ECCFA38DC305C96D769173E906E98A04A2B5B3CFFB85C93D810E7B365B18617EBAE4682F5E46FAD1C55CE291C52E8142F3D624C7461A8833978160451C577DBEF2976/demosft1/software.zip"
        ]
      },
      "digitalRights": {},
      "subscriptionInfo": {
        "autoRenewal": "true",
        "terms": "CAPI-395 Anonymous flow",
        "freeTrial": "false",
        "startTime": "2020-09-13T00:00:00.000z",
        "endTime": "2021-09-13T00:00:00.000z",
        "billingAgreementId": "c713ec4d-5fcf-4a3d-9a0c-bcb214480b8d"
      }
    }
  },
...

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 --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}}"
                    }
                }
            ]
        }
    }
}'

Auto renewal

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. 

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

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. 

...
    "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 to pay for a commitment-based subscription. If a customer provides a non-recurring payment method, the following error appears. 

{
    "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"
            }
        ]
    }
}
PreviousManaging the shipping or billing addressNextManaging payment methods

Last updated