The ProcessCart API resource provides a method for automatically submitting purchases to the cleverbridge platform that operates as an alternative to web browser-based orders. This API processes orders with little or no interaction from customers, provided that you submit a specific set of parameters to cleverbridge.
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.
There are important parameters that should be understood 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 typical 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 is 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 can't ensure that the customer will access the URL within 72 hours, the non interactive mode is best. 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 that is 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 that 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's 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:
Identifying the Customer
For receiving the required customer information, such as the payment information, it's 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's possible to identify the customer by the cleverbridge subscription ID. This ID is reported with the notifications after the first purchase.
It's 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.|
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:
Message>Credit card limit exceeded</Message>
The following payment provider error codes are supported:
||Credit card limit exceeded|
||Rejected by issuing bank|
||Rejected for fraud|
||Security code validation failed|
ProcessCart API resource handles several billing scenarios. This page describes the most popular scenarios:
- You use proprietary subscription software and do not need to use the subscription options offered in cleverbridge ecommerce 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, for example, gaming applications with built-in order processing buttons. 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 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 not part of an existing subscription.
You should elect 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 for inclusion 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):
- No further actions are taken by cleverbridge; cleverbridge waits for the next purchase that must be initiated by you.
To trigger a rebilling, you must create an API request containing:
- Subscription ID
- Default language ID
- Product ID
- Additional name (optional)
- Dynamic product name (optional)
- Dynamic price (optional)