logo

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 

2 Webhook Configuration 

3 Messages to the merchant 

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

Capturar-4

For any questions or concerns, the merchant can contact ClearSale’s integration team at integration@clear.sale.

  1. 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.

Capturar-May-10-2021-07-20-03-06-PM

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.

Capturar-May-10-2021-07-20-53-19-PM

  • 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 **