Expiring Links

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 Exchange of money for goods and services in an acceptable amount to the customer where the payment amount has been agreed upon in advance. The customer can only pay with an accepted payment method. Each payment has an individual payment cost. data from your customers. They also ensure that your online storefront, email communication, and self-service pages are GDPR-compliant.

Getting Started

To start using expiring links, complete the following steps:

1. 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.
   

Note

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.

2. 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 following parameters:

   &s=<start time>

   Parameter	Data Type	Description
   <starttime>	integer	Unix timestamp corresponding with the date and time in which the link should activate. For more information, see Unix time. Note The &s parameter is mandatory. If the &s parameter is missing, the URL won't work. Example &s=1592309816

   &e=<endtime>

   Parameter	Data Type	Description
   <endtime>	integer	Unix timestamp corresponding with the date and time in which the link should expire. For more information, see Unix time. Note The &e parameter is mandatory. If the &e parameter is missing or expired, the URL will not work. Example &e=1607865416

   &c=<HMAC-SHA1 checksum>

   Parameter	Data Type	Description
   <HMAC-SHA1 checksum>	string	The checksum for link protection is an HMAC-SHA1 hash based on the following string: id:starttime-endtime In this string, the id corresponds to the purchaseId, subscriptionId, invoice number, etc. of the object being tracked. For the subscription ID only the numerical value is accepted, without the initial letter "S". For example, for subscriptionId=S12345678, include only the numbers "12345678" into the calculation to obtain a correct checksum: 12345678:1683635441-1684585841 For the purchase An order made by a customer and the records associated with it. ID and invoice number no modifications are needed. To calculate the checksum, you must encrypt the string with SHA1 using the Seed for static URL protection: SHA1(id:starttime-endtime, SEED) You can find this seed in Commerce Assistant under Setup > Account Setup > Additional Details. Note The &c parameter is mandatory. If any of the parameters used for the HMAC calculation are altered in the URL, the URL will not work. Example &c=9d1f3806b94ceeac401d98fcb8ad9777caf0f2005dc630039e21d1d45dd547b5 Note 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>)

Example Links

The following examples present links that use the expiration logic:

Change Subscription Payment (SCP)

Use the following link to allow a customer An individual or business purchasing your product or service by placing an order through Cleverbridge. The customer is the end user of this product, as they are not allowed to resell the purchased products or services. ​ A customer is unique per client. If a customer purchases products or services from two different clients, there are 2 separate records of said customer.​ to update, change, or manage their payment method Describes the actual payment method used by the customer to complete the purchase, for example, Visa, wire transfer, or SEPA Direct Debit. 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>

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 An agreement between a seller and a buyer to exchange goods and/or services for money. An order can: - contain multiple products and quantities; - have multiple financial transactions. A preorder authorization is considered an 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 Set of payment choices displayed to the customer on the checkout page. Available payment options are based on the customer's GeoIP location and include different payment methods and types, for example: a Purchase order (PO) is a payment option we offer our B2B customers. POs are usually paid via the payment method of wire transfer..

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

A Link Valid for 10 Years

Keeping Purchase Document History

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.).

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 that do not involve online transactions like direct debit, wire transfers, and checks. 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 payment confirmation from the payment provider.
• Paid
• Purchase order A B2B payment option in which software is delivered either immediately without the upfront collection of payment or after prepayment with proforma invoice.
• Refunded
• Partially refunded
• Chargeback A credit card chargeback, typically referred to as chargeback, occurs when a customer successfully disputes a transaction on their bank report. Unlike a refund, where Cleverbridge proactively returns the amount to the customer, a chargeback involves the customer's bank automatically withdrawing the amount from Cleverbridge's account. Cleverbridge can contest illegitimate claims, but the card organization makes the final decision. Successfully contested chargebacks still contribute to the chargeback ratio.
• 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 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>

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='