ClearSale API - Moving from Sandbox to Production
Revisions
Version |
Date |
Author |
Notes |
1.0 |
10/12/2020 |
SalesEng |
First release |
2.0 |
17/12/2020 |
SalesEng |
Test rules details |
3.0 |
16/04/2020 |
SalesEng |
Webhook configuration |
4.0 |
29/04/2020 |
SalesEng |
Messages to the merchant |
Contents
1 How to use the Sandbox environment
4 Moving from Sandbox to Production
1. How to use the Sandbox environment
In the sandbox environment, a merchant can perform all tests necessary to verify that the order information is being integrated successfully and to confirm the workflow for all ClearSale decision scenarios.
**Do not use production data in this environment. This is only for testing purposes.**
More information about the ClearSale API is available at: https://www2.clear.sale/developers/api
For any questions or concerns, the merchant can contact ClearSale’s integration team at integration@clear.sale.
Before commencing use of the sandbox environment, the merchant will receive an email from our integration team with the credentials to utilize the ClearSale API. Each environment (Production and Sandbox) will have their own set of credentials. These credentials are NOT interchangeable.
The credentials will contain the information found below and will be used for authentication through the Login method.
ApiKey
ClientID
ClientSecret
To consume ClearSale’s API in the sandbox environment, the merchant must use the URLs below for each function:
Authentication
Login: https://sandbox.clear.sale/api/auth/login
Logout: https://sandbox.clear.sale/api/auth/logout
Order Integration/Update
Send Order: https://sandbox.clear.sale/api/order/send
Get Order Status: https://sandbox.clear.sale/api/order/get
Update Order: https://sandbox.clear.sale/api/order/update
For more in-depth information on the API methods and integration flow, consult the full API documentation:
https://www2.clear.sale/developers/api
In the sandbox environment, the machine learning model and manual review will not be applied. This environment is only for testing the data sent and the flow.
To test the flow, ClearSale has created some rules on its side to help the merchant’s development team. The ‘decision’ can be manipulated by sending specific values in the TotalOrder field.
To receive the result code for Automatic Approval (APA):
TotalOrder value sent must be <= 50.
To receive the result code for Automatically Denied (RPA):
TotalOrder value sent must be in the range 50 < TotalOrder <= 100.
To receive the result code for Manual Analysis (AMA):
TotalOrder value sent must be > 100.
2. Webhook Configuration
After the order is sent through ClearSale API, the decision will be returned asynchronously, through a webhook.
As soon as a decision is made regarding an order (either approved or denied), ClearSale system can be configured to actively send (post) the new status to an endpoint.
The endpoint should be implemented to receive the object OrderStatus (https://www2.clear.sale/developers/api#appendix-orderstatus) via POST in JSON format (Content type: application/json).
Typically, when we talk about partnerships, the architecture used is a centralized webhook to receive the decisions from ClearSale. According to the order data received, the partner system can direct the order to the merchant. A diagram with this architecture is shown below:
After defining the Webhook URL, the partner can share that with our integration team integration@clear.sale. Our team is responsible to do this configuration on ClearSale system. After that, ClearSale team will ask for some tests to confirm that the integration is ready to go-live.
3. Messages to the merchant
After ClearSale decides an order, the decision will be sent through the object OrderStatus according to the specification below (more information at https://www2.clear.sale/developers/api#appendix-orderstatus):
The available statuses are represented in the table below (more information available at https://www2.clear.sale/developers/api#appendix-status-list):
Best practice is to hide the score and to translate the status code to a merchant friendly message. Please see our color and verbiage suggestions below:
4. Moving from Sandbox to Production
After the tests are completed in the sandbox environment, the merchant will be able to send orders to the production environment for ClearSale to begin deciding the transactions.
If the merchant has not yet received the credentials for production, they can send an email request to integration@clear.sale.
Before moving to production, it’s recommended to notify ClearSale’s team beforehand at integration@clear.sale.
The merchant will receive an email from our integration team with the credentials to access ClearSale API. These credentials are only valid for our production environment.
These credentials will contain the information below and will be used for authentication through the Login method.
ApiKey
ClientID
ClientSecret
The merchant will need to replace the previous sandbox credentials with this new data to log into the production environment.
To utilize ClearSale’s API in the production environment, the merchant must use the URLs below:
Authentication
Login: https://integration.clear.sale/api/auth/login
Logout: https://integration.clear.sale/api/auth/logout
Order Integration/Update
Send Order: https://integration.clear.sale/api/order/send
Get Order Status: https://integration.clear.sale/api/order/get
Update Order: https://integration.clear.sale/api/order/update
**For more in-depth information on the API methods and integration flow, consult the full API documentation:
https://www2.clear.sale/developers/api **