Cleverbridge generates links that are invalid after a set amount of time. These expiring links make it difficult for third-party tools to fetch and collect personally identifiable information (PII) or payment data from your customers. They also ensure that your online storefront, email communication, and self-service pages are GDPR-compliant.
Since June 2021 all new client accounts automatically receive the new and improved expiring link structure. If you have been using the Cleverbridge platform longer than that and would like to use this new link structure as well, contact Client Experience.
To start using expiring links, complete the following steps:
- Contact Client Experience and inform them that you would like to start using expiring links instead of the default static links that were set up for your account. In this communication, you should clarify how long you would like the links to be valid if they are to be generated by Cleverbridge.
- Generate links for your hosted self-services pages and other online resources. When you generate expiring links, you must keep in mind that they cannot remain valid longer than the value of
MaxLinkLifeTimespecified in the Cleverbridge system. The
MaxLinkLifeTimevalue is set to 99 days from the
starttimedefined during link generation.
Apart from that, you must use the following parameters:
Parameter Data Type Description
Unix timestamp corresponding with the date and time in which the link should activate. For more information, see Unix time.
&sparameter is mandatory. If the
&sparameter is missing, the URL won't work.
Parameter Data Type Description
Unix timestamp corresponding with the date and time in which the link should expire. For more information, see Unix time.
&eparameter is mandatory. If the
&eparameter is missing or expired, the URL will not work.
Parameter Data Type Description
The checksum for link protection is an HMAC-SHA1 hash based on the following string:
In this string, the
idcorresponds to the
subscriptionId, etc. of the object being tracked.
In order to calculate the checksum, you must encrypt the string with SHA1 using the Seed for static URL protection:
You can find this seed in the Commerce Assistant under Account Settings > Additional Details.
&cparameter is mandatory. If any of the parameters used for the HMAC calculation are altered in the URL, the URL will not work.
This is only for document links. For purchase/subscription-related links, you can use the purchase ID or subscription ID instead of the invoice number:
SHA1(<invoice number>:<start time>-<end time>, <seed>)
The expiring links generated by Cleverbridge are valid for 30 days from the creation date. The validity of links in notifications is 30 days upon dispatch of the notification.
The following examples present links that use the expiration logic:
Change Subscription Payment (Subscription ID)
Use the following "change payment link" to allow a customer to update, change, or manage their payment method preferences for a subscription.
Use the following link to allow a customer to see the details of their purchase after completing a transaction.
Use the following link to give customers access to their invoice.
All document links follow the same recipe:
https://www.cleverbridge.com/invoice/<Invoice number>.pdf?s=<start time>&e=<end time>&c=<hash/checksum>&documentid=<Document ID>
For test orders, the invoice number is generally the same as the purchase ID. For actual orders, the invoice number has the following format (Letters-Numbers):
Links Valid for Defined Time Period
When generating expiring links, it's possible to choose any start and end time (as long as it doesn't expire in the past) and calculate the hash based on those times. The two following examples show two expiring links to the same refund document. One link is valid for a year from today, the other for 10 years.A Link Valid for 1 Year
Keeping Purchase Document History
Every API response or notification contains these four links:
The confirmation/cancellation/change payment links are the same in every Get Purchase API response per purchase. However, the PDF link in the API responses only shows the latest invoice type (purchase, partial refund, etc.).
In order to create links for the full document history, you need to activate the following notifications:
- Awaiting offline payment Offline payment stands for a group of payment options. With the order confirmation, the customer receives a link with information on how to make the payment. Ordered products are delivered as soon as Cleverbridge receives a payment confirmation from the payment provider.
- Purchase order
- Partially refunded
- Test order
- New quote
- Return direct debit
- VAT refunded
For further details on how to set up notifications in the Cleverbridge platform, see Manage Notifications > Set Up Notifications for Subscriptions.
The description of the invoice type is in the notification, for instance in the 'Status' and 'StatusID' tags:
<?xml version="1.0" encoding="UTF-8"?> <cbt:Status>Partial Refunded</cbt:Status> <cbt:StatusId>PPR</cbt:StatusId>
In the case of an XML notification, it is near the top of the document. For JSON notifications, it is near the bottom.
From the available timestamps in the notifications, use the ones that best suit your case, depending on how much granularity you need.
Example of a PaidOrderNotification:
<?xml version="1.0" encoding="UTF-8"?> <cbt:CreationTime>2022-11-16T12:37:41.429317Z</cbt:CreationTime> <cbt:PaymentArriveTime>2022-11-16T12:37:41.666145Z</cbt:PaymentArriveTime> <cbt:LastModificationTime>2022-11-16T12:37:42.081264Z</cbt:LastModificationTime>
Example of a PartialRefundNotification:
<?xml version="1.0" encoding="UTF-8"?> <cbt:CreationTime>2022-11-16T12:37:41.429317Z</cbt:CreationTime> <cbt:PaymentArriveTime>2022-11-16T12:37:41.666145Z</cbt:PaymentArriveTime> <cbt:ReimbursementTime>2022-11-16T12:46:06.349784Z</cbt:ReimbursementTime> <cbt:LastModificationTime>2022-11-16T12:46:06.417129Z</cbt:LastModificationTime>
The relevant subscription ID and purchase ID will be under the following tags:
<?xml version="1.0" encoding="UTF-8"?> <cbt:RecurringBilling cbt:SubscriptionId="S49694473" cbt:SubscriptionItemRunningNo="1"> <cbt:OriginalPurchaseId>366332011</cbt:OriginalPurchaseId>
Parse the following data from CustomerPdfDocumentUrl you get with every notification:
- Invoice number: found between '/invoice/' and '.pdf' in the link
- Document ID: found at the end after 'documentid='