Guides
GuidesAPI ReferenceNotificationsDiscussionsSupportStatus

Sign Up for a Paid Subscription (Known Customer)

Overview

This guide explains how to implement a paid subscription sign-up flow for a known customer.

A known customer is a customer who is already authenticated in your system and has a unique customer identifier. By including this identifier in the purchase link, you can associate the completed order with the correct customer record.

Implement a sign-up flow

Before you start

Make sure that you have:

  • A configured subscription product and cart.
  • Credentials for the URL Generator API.
  • A unique, non-sensitive customer identifier (UUID).
  • A notification endpoint configured to receive PaidOrderNotification.
  • A plan for validating and processing notifications securely.
    📘

    Note

    UUID: Use an opaque identifier that maps to the customer in your system. Do not include personal or sensitive customer information in the URL.

Step 1: Create a purchase link

Create a purchase link and add the following parameters for mapping and reporting purposes:

FieldDescription
internalcustomerSet this parameter to the customer’s unique identifier in your system so that you can associate the order with the correct customer record.
x-sourceAssign additional information to these x-parameters for reporting purposes
https://www.cleverbridge.com/864/?scope=checkout&cart=97771&internalcustomer=UUID-YOUR-UNIQUE-ID-1234-5678&language=en&currency=USD&x-source=website-visit-05.2019&x-device-id=UUID-asd89ad-asd89sd-asd89s0

📘

Tip

Because the customer is already authenticated, you can use single sign-on to prepopulate supported customer information during checkout. For more information, see Single Sign-On (SSO).

Step 2: Protect the purchase link

Call the Generate User Session URL API endpoint to protect the parameters in the TargetUrl.

curl --request POST \
  --url 'https://rest.cleverbridge.com/urlgenerator/generateusersessionurl' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'authorization: Basic YOUR_BASE64_ENCODED_CREDENTIALS' \
  --data '{
  "TargetUrl": "https://www.cleverbridge.com/864/?scope=checkout&cart=97771&internalcustomer=UUID-YOUR-UNIQUE-ID-1234-5678&language=en&currency=USD&x-source=website-visit-05.2019&x-device-id=UUID-asd89ad-asd89sd-asd89s0"
}'
import http.client
import json

conn = http.client.HTTPSConnection("rest.cleverbridge.com")

payload = json.dumps({
  "TargetUrl": "https://www.cleverbridge.com/864/?scope=checkout&cart=97771&internalcustomer=UUID-YOUR-UNIQUE-ID-1234-5678&language=en&currency=USD&x-source=website-visit-05.2019&x-device-id=UUID-asd89ad-asd89sd-asd89s0"
})

headers = {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Basic YOUR_BASE64_ENCODED_CREDENTIALS"
}

conn.request(
    "POST",
    "/urlgenerator/generateusersessionurl",
    body=payload,
    headers=headers
)

response = conn.getresponse()
print(response.read().decode("utf-8"))

conn.close()
const https = require('https');

const data = JSON.stringify({
  TargetUrl: "https://www.cleverbridge.com/864/?scope=checkout&cart=97771&internalcustomer=UUID-YOUR-UNIQUE-ID-1234-5678&language=en&currency=USD&x-source=website-visit-05.2019&x-device-id=UUID-asd89ad-asd89sd-asd89s0"
});

const options = {
  hostname: 'rest.cleverbridge.com',
  path: '/urlgenerator/generateusersessionurl',
  method: 'POST',
  headers: {
    'Accept': 'application/json',
    'Content-Type': 'application/json',
    'Authorization': 'Basic YOUR_BASE64_ENCODED_CREDENTIALS',
    'Content-Length': Buffer.byteLength(data)
  }
};

const req = https.request(options, (res) => {
  let body = '';

  res.on('data', (chunk) => {
    body += chunk;
  });

  res.on('end', () => {
    console.log(body);
  });
});

req.on('error', (err) => {
  console.error(err);
});

req.write(data);
req.end();
import java.io.InputStream;
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import java.nio.charset.StandardCharsets;

public class GenerateUserSessionUrl {

    public static void main(String[] args) throws Exception {

        URL url = new URL("https://rest.cleverbridge.com/urlgenerator/generateusersessionurl");
        HttpURLConnection conn = (HttpURLConnection) url.openConnection();

        conn.setRequestMethod("POST");
        conn.setRequestProperty("Accept", "application/json");
        conn.setRequestProperty("Content-Type", "application/json");
        conn.setRequestProperty("Authorization", "Basic YOUR_BASE64_ENCODED_CREDENTIALS");
        conn.setDoOutput(true);

        String json = """
        {
          "TargetUrl": "https://www.cleverbridge.com/864/?scope=checkout&cart=97771&internalcustomer=UUID-YOUR-UNIQUE-ID-1234-5678&language=en&currency=USD&x-source=website-visit-05.2019&x-device-id=UUID-asd89ad-asd89sd-asd89s0"
        }
        """;

        try (OutputStream os = conn.getOutputStream()) {
            byte[] input = json.getBytes(StandardCharsets.UTF_8);
            os.write(input);
        }

        try (InputStream is = conn.getInputStream()) {
            String response = new String(is.readAllBytes(), StandardCharsets.UTF_8);
            System.out.println(response);
        }

        conn.disconnect();
    }
}

Example response

{
    "Url": "https://www.cleverbridge.com/surl-SC7nfRWj8V",
    "ResultMessage": "OK"
}

Step 3: Redirect the customer to the protected checkout URL

Redirect the customer to the protected URL returned by the Generate User Session URL endpoint.

The customer completes the checkout, submits their payment information, and finalizes the purchase.

If the payment is successful, Cleverbridge displays an order confirmation together with the delivery details. If a license key generator is configured for your account, the generated license key is also included in the delivery details.


Step 4: Process the PaidOrderNotification

When Cleverbridge receives the payment for the order, it sends a PaidOrderNotification. Use the notification to create or update the customer record in your CRM, licensing system, ERP, or other internal systems.

Notification Parameters

The notification contains the following parameters:

FieldDescription
internalCustomerYour internal customer identifier.
items[].recurringBilling.subscriptionIdThe Cleverbridge subscription ID.
items[].recurringBilling.renewalTypeIndicates whether the subscription renews automatically or manually.
items[].recurringBilling.intervalNumberThe current recurring-billing interval number.
items[].recurringBilling.nextBillingDateThe next scheduled billing date.

Example PaidOrderNotification

The following example shows a trimmed PaidOrderNotification. For the complete payload, see the JSON reference.

{
  "internalCustomer": "UUID-YOUR-UNIQUE-ID-1234-5678",
  "items": [
    {
      "runningNumber": 1,
      "recurringBilling": {
        "subscriptionId": "S12345678",
        "intervalNumber": 0,
        "renewalType": "Automatic",
        "nextBillingDate": "2020-03-19T14:47:34.857671"
      }
    }
  ]
}

Step 5: Check the notification status

Before provisioning the subscription, verify that purchase status is Paid and statusId is PAY.

Handle test orders separately.

"status": "Paid",
"statusId": "PAY"

For more details, see the PaidOrderNotification reference documentation.

Updated 19 days ago

Did this page help you?