The Cart API allows you to handle cart operations, such as automatically processing a customer's shopping cart.
In this guide, you can find information that will help you understand and integrate the following Cart API resources:
The Process Cart endpoint processes an order automatically. The customer does not need to use a browser, interact with cleverbridge, or enter new payment information. Instead, cleverbridge uses the customer's most recent payment details to process the order.
If the order cannot be processed automatically, the API will return a unique URL that can be sent to the customer in order to complete the transaction on the cleverbridge-hosted website.
ProcessCart API resource handles several billing scenarios. Here are the most popular scenarios:
- You use proprietary subscription software and do not need to use the subscription options offered on the cleverbridge subscription commerce platform.
- A customer places a subscription order on your platform. The subscription details are stored on your platform and cleverbridge treats it as a normal (non-subscription) purchase.
- Rather than managing the details of the subscription, cleverbridge handles only the billing and delivery details of every rebilling cycle.
You produce gaming applications with built-in order processing buttons, for example. There are two scenarios for this use case:
- A customer buys the game application.
- 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, product ID).
- A customer uses a free trial version of the game application.
- After playing for several weeks, the customer clicks the buy button.
- 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.
- The customer completes the order.
- A customer orders a technical support product based on the number of hours of support provided.
- After two months, the customer would like more hours, so the customer goes to your website and purchases more technical support hours.
- The ProcessCart API handles the upgrade as a once-only billing incident.
You manage subscription events using your own subscription platform with the contingency that you inform cleverbridge when rebilling is required.
Shopping carts can be submitted with multiple items and with items that are not part of an existing subscription.
You should select to receive notifications to monitor events. For more information about event notifications, see Notification Guide.
- 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.
- 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."
- 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.
If you do not include the ID with the request, a new subscription will be created in the cleverbridge database.
The subscription ID has the following structure in the notification (in this example, the notification type is XML):
<RecurringBilling SubscriptionId="S9073119"> … </RecurringBilling>
- 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
- Additional name (optional)
- Dynamic product name (optional)
- Dynamic price (optional)
<ProcessCartRequest xmlns="http://api.cleverbridge.com/datacontract"> <Cart> ... </Cart> <DefaultCountryId>String</DefaultCountryId> <DefaultLanguageId>String</DefaultLanguageId> <ExtraParameters> ... </ExtraParameters> <ProcessCartMode></ProcessCartMode> <Subscription> <SubscriptionId>S9073119</SubscriptionId> </Subscription> </ProcessCartRequest>
The following parameters are the most important ones you should understand before using this API.
You can control the behavior of the API (for example, how to handle errors like incomplete payment information). There are two modes:
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, will be 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.
A session URL is only valid for 72 hours before it expires.
If you cannot ensure that the customer will access 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, 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. For more information, see Update Subscription Parameters.
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.
Below is an example of a request with x-parameters:
<ExtraParameters> <ExtraParameter> <Key>x-customerid</Key> <Value>51254</Value> </ExtraParameter> <ExtraParameter> <Key>x-vendors-subscription-id</Key> <Value>544920</Value> </ExtraParameter> </ExtraParameters>
In order 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.
The following describes possible responses for the
ProcessCart API resource:
|HTTP Status Code||ResultMessage/Message||Reason|
||cleverbridge successfully processed the purchases. The purchase ID is included in the response.|
||cleverbridge successfully processed the purchases and is now waiting for payment.|
||The payment was declined. A URL is included in the response so that the customer can change the payment details or payment type to complete the order.|
||Some of the customer information is not valid or is incomplete, such as the payment details.|
||Your request is incorrect, possibly due to invalid elements.|
||An internal error occurred.|
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.
cleverbridge works with several payment providers in order 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 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 a payment was declined.
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 in XML:
<Error> <Code>PAY_CLE</Code> <Message>Credit card limit exceeded</Message> </Error>
The following payment provider error codes are supported:
||Credit card limit exceeded|
||Rejected by issuing bank|
||Rejected for fraud|
||Security code validation failed|
IsPaymentRetryScheduledfor Subscription Management
IsPaymentRetryScheduled response field indicates whether a payment retry has been scheduled for a subscription because of a failed credit card payment. When 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 via the cleverbridge Account Updater, you receive an
CCA_EXP status under
PaymentResult.Code in the Process Cart response. If this is the case, cleverbridge will initiate 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 Collecting Failed Online Payments (Automatic Collection).
Frequently calling the
/processcart resource can cause a lot of server traffic. Before using this resource, contact Client Experience for more information.
The Generate Cart Preview endpoint creates a cart preview that is populated with product and price information. It also allows you to obtain the cleverbridge cart as an XML file.
You can use this resource to access what customers see when they use a certain IP address or language. You can also use the response to populate your web page with product and pricing information stored in the cleverbridge platform. This circumvents the need to maintain duplicate product and pricing information in both your database and on the cleverbridge platform. Additionally, you have the option to display the information returned by this resource to the customer as either read-only or editable by the customer.
A client wants to populate a marketing landing page with product and price information for its gold subscription product.
- The client can use the GenerateCartPreview API resource in order to receive information on this product from customers and then transform this information into another format, such as HTML.
- A customer is directed to this page by an email and decides to purchase this product. The page enables the customer to change the number of users from 1 to 12.
- There are two cases which occur at this point, depending on whether this is a new customer or an
- In the case of a new customer that is unknown to the client, they are redirected to the web checkout process.
- In the case of an existing customer that is known to the client, the customer clicks “Buy Now”
and the client calls the
ProcessCartAPI in order to populate the customer and shopping cart data. Then cleverbridge processes this purchase.
To generate properly and fully-formed XML in the response, this API resource requires that all products be directly passed via Product ID in the
ShoppingCartUrl. This means, for example, that the following types of URL strings should not be passed:
MVTMultivariate testing (MVT) is a technique for testing two or more different variables in the checkout process to determine which variable creates more revenue or a higher conversion rate. campaign URLS, for example: https://store.cleverbridge.com/677/purl-buzzoffcleverbridge?scope=checkout
The GenerateCartPreview API resource cannot access product information that is hidden behind a protected URL.
URLs with product selections or recommendations; for example: https://store.cleverbridge.com/677/?scope=cart&cart=s3503
This URL can be resolved if copied and pasted into a web browser. However, if it was passed using the
ShoppingCartUrlrequest parameter, then only the default selected product would be returned in the response XML.
If you wanted to pass the same products contained in the product selection example above, then simply
take a URL that explicitly identifies the products using the
ShoppingCartUrl parameter, for example:
Frequently calling the
/generatecartpreview resource can cause a lot of server traffic. Before using this resource, contact Client Experience for more information.