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 subscriptionInfo hash 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
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.
JSON
...
  "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
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
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.  
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 to pay for a commitment-based subscription. If a customer provides a non-recurring payment method, the following error appears. 
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"
            }
        ]
    }
}
Managing the shipping or billing address
Managing payment methods
Last modified 2mo ago