The Process Cart endpoint processes an order automatically. Cleverbridge uses the customer's most recent payment details to process the order.
If the order cannot be processed automatically, the API returns a unique URL that can be sent to the customer to complete the transaction on the Cleverbridge-hosted website.

Use Cases

The ProcessCart API endpoint handles several billing scenarios. Here are the most popular ones:

Proprietary Solution

1. You use proprietary subscription software and do not need to use the subscription options offered in the Cleverbridge platform.
2. A customer places a subscription order on your platform. The subscription details are stored in your platform and Cleverbridge treats it as a normal (non-subscription) purchase.
3. Rather than managing the details of the subscription, Cleverbridge handles only the billing and delivery details of every rebilling interval.

In-Application Ordering

You produce gaming applications with built-in order processing buttons, for example. There are two scenarios for this use case:

Update

1. A customer buys the game application.
2. After playing for several weeks, the customer clicks the update button. The application uses the ProcessCart API to provide information to Cleverbridge (for example customer ID, and product ID).

Free-to-Paid

1. A customer uses a free trial version of the game application.
2. After playing for several weeks, the customer clicks the buy button.
3. Cleverbridge has no records for this customer, so the ProcessCart API returns a link to your system that redirects the customer to the checkout page. This link can also be sent to the customer by email if you prefer.
4. The customer completes the order.

Technical Support Upgrade

1. A customer orders a technical support product based on the number of hours of support provided.
2. After two months, the customer would like more hours, so the customer goes to your website and purchases more technical support hours.
3. The ProcessCart API handles the upgrade as a one-off billing event.

You Handle Subscriptions

You manage subscription events using your own subscription platform with the contingency that you inform Cleverbridge in case rebilling is required.

📘

Note

Shopping carts can be submitted with multiple items and with items that are not part of an existing subscription.

👍

Tip

You should select to receive notifications to monitor events. For more information about event notifications, see Notification Guide.

Requirements

• Cleverbridge flags you as responsible for handling your own subscriptions.
• You must create and configure subscription products.
• The referenced subscription must have a status of "Handled by Client."

Scenario

1. A customer uses the Cleverbridge checkout process to place an initial subscription purchase. At the time of the initial purchase, Cleverbridge captures the payment information and creates a subscription with the status "Handled by Client."
2. You receive the paid order notification that contains the Cleverbridge subscription ID. You must save this ID into its own subscription system so that the ID is included in future rebilling requests, identifying the new purchases as part of that subscription.

❗️

Warning

If you do not include the ID with the request, a new subscription is created in the Cleverbridge database.

The subscription ID has the following structure in the JSON notification:

{
        "recurringBilling":
          {
            "subscriptionId": "S9073119"
            …
          }
        }

3. No further actions are taken by Cleverbridge; Cleverbridge waits for the next purchase, which must be initiated by you.

To trigger a rebilling, you must create an API call containing:

• Subscription ID
• Default language ID
• Product ID
• Quantity
• Additional name (optional)
• Dynamic product name (optional)
• Dynamic price (optional)

{
    "processCartRequest": 
      {
        "cart":
          ...
        "defaultCountryId": "String",
        "defaultLanguageId": "String",
        "extraParameters":
          ...
        "processCartMode": {},
          ...
        "subscription": {"subscriptionId": "S9073119"}
      }
    }

Important Parameters

The following parameters are the most important ones you should understand before using this API.

ProcessCartMode

You can control the behavior of the API (for example, how to handle errors like incomplete payment information). There are two modes:

Interactive (Default)

In the interactive mode, you can interact directly with the customer if any information is outdated, such as when the credit card expires or is invalid. This method returns a session URL that you can use to redirect the customer to the Cleverbridge checkout process. All available information, such as the first name and address, is included if it exists, and only the wrong or missing data needs to be changed by the customer. Incomplete or invalid payment information is the most common reason for an error.

With the interactive mode, Cleverbridge does not save the information or create a purchase in the database. The submitted information is temporarily stored for 72 hours and accessible through a session URL that is returned by the API.

If all required information is complete and valid, but the payment is declined, Cleverbridge creates the purchase and returns an existing reference ID and a URL for a page where the customer can change the payment details or select another payment type.

📘

Note

A session URL is only valid for 72 hours before it expires.

Non-Interactive

If you cannot ensure that the customer accesses the URL within 72 hours, the non-interactive mode is the best mode. In this mode, the purchase is saved, and the API returns a URL for the checkout process so that the customer can complete the information required to process the order.

ExtraParameterMode

With ExtraParameterMode, you can control whether the x-parameters are added to the initial purchase of the subscription (PurchaseOnly), all subsequent billing events (SubscriptionOnly), or both the initial purchase of the subscription and all subsequent billing events (Default). This parameter only lets you add x-parameters to subsequent billing events of new subscriptions. If you want to add x-parameters to subsequent billing events of an existing subscription, you must update the underlying subscription using POST /subscription/updatesubscriptionparameters.

ExtraParameters

You can add additional information to the purchase with the ProcessCart API by using x-parameters. X-parameters are components of the request, and they are used to pass information through the API, such as:

• Sources of revenue (revenue tracking)
• Customer information
• Affiliate and partner information
• Any other information you would like to pass

X-parameters are configured for attributes initiated outside the Cleverbridge platform. You create x-parameters based on an information need that is not inherently included in the Cleverbridge platform, such as a user ID number or the name of a campaign. X-parameters must begin with x-. X-parameters are included in Cleverbridge notifications.

You can submit more information using x-parameters on both the shopping cart and individual cart item levels. These x-parameters are received through notifications, which contain additional custom data, such as tracking and licensing information, for more detailed reporting.

Include an X-Parameter

To include x-parameters per cart item or per cart, you must add a list of key/value pairs to the request.

It is important that all keys begin with x- so that this information can be identified in the Cleverbridge system.

The submitted x-parameters are included in the notifications. For example, you can assign the purchase to a customer in your system.

Example

Below is an example of a request with x-parameters:

{
  "extraParameters": 
   {
     "extraParameter": 
       {
        "key": "x-customerid",
        "value": "51254"
       },    
  "extraParameter": 
    {
      "key": "x-vendors-subscription-id",
      "value": "544920"
    }
  }
}

Customer Identifiers (Ids)

To receive the required customer information, such as the payment information, it is required to submit an identifier so that Cleverbridge can find it. The API offers several ways to identify the customer:

• LogonPurchaseId — Former purchase ID of the customer.
• CustomerReferenceId — Client-unique identifier of the customer. You must submit this value by the first purchase or when the customer is created so that Cleverbridge can store the value.
• SubscriptionId — If you handle the subscription yourself, it is possible to identify the customer by the Cleverbridge subscription ID. This ID is reported with the notifications after the first purchase.

It is recommended that you use the LogonPurchaseId; or, if you handle the subscriptions yourself, use the SubscriptionId.

Status Codes

The following describes possible responses for the ProcessCart API resource:

Payment Information Considerations

Due to PCI compliance requirements, the ProcessCart API resource must not handle the transfer of payment information. Some clients send all their customers email messages containing a link that takes the customer to a pre-filled checkout form. Since email is inherently insecure, the checkout form cannot contain pre-filled payment information.

When you submit an order for a customer with no stored payment records, the API returns a unique URL that can be used to redirect the customer to a regular Cleverbridge checkout page where the customer enters payment information.

Payment Provider Errors

Cleverbridge works with several payment providers to process the different payment types; however, the error messages that might be returned from all of these payment providers are inconsistent. We include proprietary payment error codes to the ProcessCart API resource and notifications, and map all of the various payment provider error codes to Cleverbridge-specific counterparts, so that error messages are consistent, regardless of the payment provider. Some of these error messages include information on when a credit card has expired, the customer's credit limit has been reached, or a credit card was rejected for fraud. This information provides greater data detail for metrics and business intelligence purposes.

In some cases, online payments cannot be processed. We offer additional information for the reason payment was declined.

📘

Note

Depending on the issuing bank and the actual processing partner of Cleverbridge, this information is subject to availability.

Below is an extract of a sample payment provider error:

{
"error":
  {
    "code": "PAY_CLE",
    "message": "Credit card limit exceeded"
  }
}

The following payment provider error codes are supported:

Using IsPaymentRetryScheduled for Subscription Management

The IsPaymentRetryScheduled response field indicates whether a payment retry has been scheduled for a subscription because of a failed credit card payment. If you manage your own subscriptions, it is important to be aware of the following retry logic:
If the customer's credit card has expired and could not be extended using the Cleverbridge Account Updater, you receive a CCA_EXP status under PaymentResult.Code in the Process Cart response. If this is the case, Cleverbridge initiates an instant Expiration Date Checker call. If the Expiration Date Checker call is unsuccessful, IsPaymentRetryScheduled is set to true and a retry is scheduled to take place one hour later, using the expired expiration date. If the Expiration Date Checker call is successful, 'IsPaymentRetryScheduled' is set to true, and a retry is scheduled to take place one hour later, using the new, verified expiration date. For more information about our revenue retention tools, see Collect Failed Online Payments Automatically.

❗️

Warning

Frequently calling the /processcart resource can cause a lot of server traffic. Before using this resource, contact Client Experience for more information.