Expiring links

Expiring links are time-limited URLs for pages that display customer or order information (for example, invoices, renewals, and subscription actions). By expiring automatically, they reduce the risk of exposing personally identifiable information (PII) or payment details if a link is forwarded or intercepted.

Since June 2021, all new client accounts automatically use the expiring-link structure.

note

By default, expiring links generated by Cleverbridge are valid for 30 days from the creation date.
For links in notifications, the validity is set to 30 days from the time the notification is sent. If you need a different default, contact Client Experience.

Generate expiring links

When you generate expiring links for hosted self-service pages and other post-purchase resources, the validity period cannot exceed MaxLinkLifeTime, which is 99 days from the starttime you define.

Include the following query parameters:

Parameter	Data type	Description
&s=<starttime>	integer	Required. Unix timestamp when the link becomes active. See Unix time. Example: &s=1592309816
&e=<endtime>	integer	Required. Unix timestamp when the link expires. See Unix time. Example: &e=1607865416
&c=<HMAC-SHA1 checksum>	string	Required. HMAC-SHA1 of the string id:starttime-endtime computed with your static URL-protection seed: SHA1(id:starttime-endtime, SEED) The id is the identifier of the object the link targets: purchaseId, subscriptionId, or invoice number. For subscriptionId, use only the numeric part (for example, S12345678 → 12345678). You can find the SEED in Commerce Assistant under Setup > Account Setup > Additional Details. Example: &c=9d1f3806b94ceeac401d98fcb8ad9777caf0f2005dc630039e21d1d45dd547b5

Examples

These are some of the common cases, when one would need to use an expiring link:

• Change subscription payment (SCP): Allow your customers to update or change the payment method for a subscription.

    https://www.cleverbridge.com/<client_ID>/scp/S<subscription_ID>?s=<start_time>&e=<end_time>&c=<checksum>

• Confirmation page: Let your customers view purchase details after completing a transaction.

    https://www.cleverbridge.com/<client_ID>/p/<purchase_ID>?s=<start_time>&e=<end_time>&c=<checksum>

• Invoice (PDF): Provide access to an invoice PDF.

    https://www.cleverbridge.com/invoice/<invoice_number>.pdf?s=<start_time>&e=<end_time>&c=<checksum>&documentid=<document_ID>

• Update a subscription: Allow your customer to expand a subscription using an upgrade option.

    https://www.cleverbridge.com/<client_ID>/usi/S<subscription_ID>?s=<start_time>&e=<end_time>&c=<checksum>&subscriptionrunningno=<subscription_item_running_number>&cart=s<product_selection_ID>:<product_ID>

• Update recurring billing: Allow your customers to update recurring billing.

    https://www.cleverbridge.com/<client_ID>/urb/<purchase_ID>?s=<start_time>&e=<end_time>&c=<checksum>-<purchase_item_running_number>

• Change quote: Let your customers review quote-related purchase details and download documents.

    https://www.cleverbridge.com/<client_ID>/cq/<purchase_ID>?s=<start_time>&e=<end_time>&c=<checksum>

• Customer change payment: Let your customers change a saved payment option.

    https://www.cleverbridge.com/<client_ID>/ccp/c<customer_ID>?s=<start_time>&e=<end_time>&c=<checksum>

• Redo the purchase: Let your customers redo a purchase by requesting a quote or going directly to payment.

    https://www.cleverbridge.com/<client_ID>/redop/<purchase_ID>?s=<start_time>&e=<end_time>&c=<checksum>

What to keep in mind

You can choose any start and end time as long as:

• The end time is not in the past, and
• The total validity does not exceed 99 days from the start time.

Below are compliant examples that demonstrate different durations for the same invoice. Timestamps are illustrative. Replace with your own values and compute the checksum using your seed.

A link valid for 30 days

Start time (s)	End time (e)	Invoice number	Checksum (c)	Document ID	Link
1759492800	1762084800	ABC-123456789	<checksum>	223681701	https://www.cleverbridge.com/invoice/ABC-123456789.pdf?s=1759492800&e=1762084800&c=<checksum>&documentid=223681701

A link valid for 90 days

Start time (s)	End time (e)	Invoice number	Checksum (c)	Document ID	Link
1759492800	1767268800	ABC-123456789	<checksum>	223681701	https://www.cleverbridge.com/invoice/ABC-123456789.pdf?s=1759492800&e=1767268800&c=<checksum>&documentid=223681701

The checksum depends on your account’s seed. Compute SHA1(id:starttime-endtime, SEED) and insert the result where <checksum> appears.

Keeping purchase document history

The confirmation, cancellation, and change-payment links are stable per purchase in the Get Purchase API. The PDF link in API responses points to the latest invoice type only (purchase, partial refund, and so on).

To build links for the full document history, enable these notifications:

• Awaiting offline payment
• Paid
• Purchase order
• Refunded
• Partially refunded
• Chargeback
• Test order
• New quote
• Return direct debit
• VAT refunded

For details on setting up notifications, see Set up notifications.

Invoice type appears in notification fields such as Status and StatusId:

<?xml version="1.0" encoding="UTF-8"?>
<cbt:Status>Partial Refunded</cbt:Status>
<cbt:StatusId>PPR</cbt:StatusId>

Use the timestamps that best fit your needs (for example, CreationTime, PaymentArriveTime, ReimbursementTime, LastModificationTime):

<?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>

Relevant IDs are present in the notification payload:

<?xml version="1.0" encoding="UTF-8"?>
<cbt:RecurringBilling cbt:SubscriptionId="S49694473" cbt:SubscriptionItemRunningNo="1">
  <cbt:OriginalPurchaseId>366332011</cbt:OriginalPurchaseId>
</cbt:RecurringBilling>

From CustomerPdfDocumentUrl, parse:

• Invoice number: the value between /invoice/ and .pdf.
• Document ID: the value after documentid=.

Did you find this doc useful?