Expiring links
Cleverbridge enables you to create time-limited links that automatically expire after a specified duration. These expiring links help prevent third-party tools from accessing or collecting sensitive information, such as personally identifiable information (PII) or payment data, from your customers. Additionally, they ensure that your online storefront, email communications, and self-service pages remain compliant with GDPR regulations.
Getting started
By default, expiring links generated by Cleverbridge remain valid for 30 days from the date of creation. The links included in notifications stay valid for 30 days from the date the notification is sent. Contact Client Experience if you need to use a different validity period.
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 MaxLinkLifeTime specified in the Cleverbridge system. The MaxLinkLifeTime value is set to 99 days from the starttime defined during link generation. Apart from that, you must use the &s=<starttime> , &e=<endtime>, and &c=,HMAC-SHA1 checksum parameters:
| Parameter | Data type | Description |
|---|---|---|
&s=<starttime> | integer | Unix timestamp corresponding with the date and time in which the link should activate. For more information, see Unix time. note The Example
|
&e=<endtime> | integer | Unix timestamp corresponding with the date and time in which the link should expire. For more information, see Unix time. note The Example
|
&c=<HMAC-SHA1 checksum> | string | The checksum for link protection is an HMAC-SHA1 hash based on the following string:
note The Example
note This is only for document links. For purchase or subscription-related links, you can use the purchase ID or subscription ID instead of the invoice number:
|
Example links
The following examples present links that use the expiration logic:
Change subscription payment (SCP)
Use the following link to allow a customer to update, change, or manage their payment method preferences for a subscription.
https://www.cleverbridge.com/<client_ID>/scp/S<subscription_ID>?s=<start_time>&e=<end_time>&c=<checksum>
Confirmation page
Use the following link to allow a customer to see the details of their purchase after completing a transaction.
https://www.cleverbridge.com/<client_ID>/p/<purchase_ID>?s=<start_time>&e=<end_time>&c=<checksum>
Invoice
Use the following link to give customers access to their invoice.
https://www.cleverbridge.com/invoice/<invoice_number>.pdf?s=<start_time>&e=<end_time>&c=<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): ABC-123456789
Update a subscription (USI)
Use the following link to allow a customer to expand the subscription by using one of the available upgrade options.
https://www.cleverbridge.com/<client_ID>/usi/S<subscription_ID>?s=<start_time>&e=<end_time>&c=<hash>&subscriptionrunningno=<subscription_item_running_number>&cart=s<product_selection_ID>:<product_ID>
Update recurring billing (URB)
Use the following link to allow a customer to update their recurring billing.
https://www.cleverbridge.com/<client_ID>/urb/<purchase_ID>?s=<start_time>&e=<end_time>&c=<hash>-<purchase_item_running_number>
Cancel recurring billing (CRB)
Use the following link (available only on Subscription Management 1.0) to allow a customer to cancel their recurring billing. The customer needs to turn off the automatic extension using the toggle button.
https://www.cleverbridge.com/<client_ID>/crb/<purchase_ID>?s=<start_time>&e=<end_time>&c=<hash>&purchaseitemrunningno=<purchase_item_running_number>
If a subscription self-service is activated, any access through CRB, CSI, and RSI links gets automatically redirected to the self-service page. In such a case, within the link, the page identifier is changed to "s".
Change quote (CQ)
Use the following link to allow a customer to see the details of their quote-related purchase and download order documents.
https://www.cleverbridge.com/<client_ID>/cq/<purchase_ID>?s=<start_time>&e=<end_time>&c=<hash>
Customer change payment (CCP)
Use the following link to allow a customer to change the payment option.
https://www.cleverbridge.com/<client_ID>/ccp/c<customer_ID>?s=<start_time>&e=<end_time>&c=<hash>
New cart from purchase (LCP)
Use the following link to allow a customer to request a quote from a purchase or to go directly to the express payment.
https://www.cleverbridge.com/<client_ID>/lcp/<purchase_ID>?s=<start_time>&e=<end_time>&c=<hash>&cart=<product_ID>&purchaseitemrunningno=<purchase_item_running_number>
Within the LCP link, the purchase item running number is optional/situational.
Redo the purchase (REDOP)
Use the following link to allow a customer to redo the purchase by either requesting a quote or going directly to the payment.
https://www.cleverbridge.com/<client_ID>/redop/<purchase_ID>?s=<start_time>&e=<end_time>&c=<hash>
Delivery confirmation (PD)
Use the following link to allow a customer to view the confirmation of their purchase.
https://www.cleverbridge.com/<client_ID>/pd/<purchase_ID>?s=<start_time>&e=<end_time>&c=<hash>
What to keep in mind
When generating expiring links, you can 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
| Start time | End time | Invoice number | Hash | Document ID | Link |
| 1668514748 | 1700050748 | 366334488R8644019 | 219032fd5373d70a04aaf873d8519a9497a8da60 | 223681701 | https://www.cleverbridge.com/invoice/366334488R8644019.pdf?s=1668514748&e=1700050748&c=219032fd5373d70a04aaf873 d8519a9497a8da60&documentid=223681701 |
A link valid for 10 years
| Start time | End time | Invoice number | Hash | Document ID | Link |
| 1668514748 | 1984137692 | 366334488R8644019 | 366334488R8644019 | 223681701 | https://www.cleverbridge.com/invoice/366334488R8644019.pdf?s=1668514748&e=1984137692&c=879958eb637ed6fad9d0dc24 fea7beea68e426d0&documentid=223681701 |
Keeping purchase document history
Every API response or notification contains these four links:
- CustomerConfirmationPageUrl
- CustomerPdfDocumentUrl
- CancellationUrl
- ChangePaymentSubscriptionUrl
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, and so on).
To create links for the full document history, you need to activate the following notifications:
- Awaiting offline payment
- Paid
- Purchase order
- Refunded
- Partially refunded
- Chargeback
- Test order
- New quote
- Return direct debit
- VAT refunded
For further details on how to set up notifications in the Cleverbridge platform, see Set Up Notifications for subscription-metrics.
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>
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: Number found between
/invoice/and.pdfin the link. - Document ID: ID found at the end after
documentid=.