POS and eCommerce Systems

Welcome to the CRM.COM API documentation for POS & eCommerce System Integrators!

Throughout this integration guide you will be able to understand the key concepts and methods that are required for a digital integration between a POS & eCommerce System and CRM.COM, enabling transaction and order processing between the two.

The Use Case

CRM.COM is a payments and rewards platform that awards loyal contacts via a broad range of reward offers. An eWallet maintains an open and commerce balance whilst submitted purchases are processed and matched against reward offers and award commerce balance.

Each offer defines a goal that contacts should reach in order to earn an award in the form of cashback, conditional or not, that can be spent on specific products, locations or days/hours.

Contacts can spend their wallet balance (open and commerce) either on request during the purchase submit or by setting auto-spend preferences or as part of an instant discount.

Reduction Method

Reduction method defines how the spend will take place. There are two reduction methods: back-end and front-end, the easier to implement and most commonly deployed being the back-end reduction.

Events and Processes

TRANSACTION ACQUIRING

On checkout, the front-end system submits the purchase transaction to CRM.COM and optionally indicates a spend amount (as per contact request).

VOID TRANSACTION

To void an existing transaction the front-end system submits the purchase transaction that should be voided to CRM.COM.

AD HOC RETURN OF GOODS

When returning products without knowing the initial purchase transaction, the front-end system submits an ad hoc return of goods with the total amount of the returned goods.

PRODUCT SYNCHRONIZATION

Product Synchronization provides the ability for the front-end system to create or update a group of products into CRM.COM. Synchronization can be achieved either during transaction acquiring (creating product skus or product families that do not exist in CRM.COM) or as a dedicated bulk process of creating new or updating existing product skus, families and brands in the CRM.COM.

The Back-End Purchase flow is the process where the front-end system submits a purchase to be awarded with an optional spend as part of CRM.COM’s back-end rewards reduction process. This typically takes place at the checkout phase of the POS & eCommerce system.

The Purchase with OTP Spend Request flow is the process where the front-end system submits a purchase to be awarded with an optional OTP spend request. This typically takes place at the checkout phase of the POS & eCommerce system.

The Void Purchase flow is the process where the front-end system voids an existing purchase transaction.

The Contact Reclaim Purchases flow is the process where the front-end system submits a purchase and the contact claims it via applications in order to be awarded.

The Contact Self-Service Purchases flow is the process where the front-end system closes the purchase (without submitting it to CRM.COM) and contact self-submits such purchase in order to be awarded.

The Front-End Purchase flow is the process where the front-end system submits a purchase to be awarded with an optional spend as part of CRM.COM’s front-end rewards reduction process. This typically takes place at the checkout phase of the POS & eCommerce system.

The Product Synchronization flow is the process where the front-end system synchronizes its products to CRM.COM.

The Order Provisioning flow is the process where the front-end system retrieves CRM.COM orders placed by contacts in order to fulfil them.

CRM.COM API is organized around REST. Our API has specific resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses and uses standard HTTP response codes, authentication & verbs.

You can use the entire API in test mode, which does not affect your live data. The API Key used to authenticate any of your requests will determine whether the request is on live mode or test mode.

The API may differ based on each CRM.COM release. For every new release with noticable changes that might alter backwards compatibility, a new version will be created.

CRM.COM API uses either API Keys to authenticate requests or an authentication JWT token obtained from a user successful logging in process.

All API requests made by POS & eCommerce integrators should authenticate using an API (Secret) Key, which can be accessed and managed from the CRM.COM Dashboard.

API KEY AUTHORIZATION HEADER EXAMPLE

curl -X $HTTP_METHOD -H "api_key: 2189341e-981e-9ad5-9912-11101670314a" 

API requests should be made using the HTTPS protocol so that traffic is encrypted. The interface responds to different methods depending on the action required.

Along with the HTTP methods that the API responds to, CRM.COM uses conventional HTTP response codes and human-readable messages in JSON format to indicate the success or failure of an API request.

In the event of a problem, the status will contain the error code, while the body of the response will usually contain additional information about the problem that was encountered.

Most of our 4XX range errors that could be handled programmatically contain all the necessary details for a better integration handling. Such details are

• HTTP Status Code & Error are used for programmatic consumption
• Message is human-readable and can be used as a default error message
• Parameters are used for programmatic consumption and can be used for enhancing the interface error message with additional information

4XX ERROR RESPONSE EXAMPLE

An example of a customer not found error is as follows

HTTP/1.1 400 Bad Request
    {
        "status": 400,
        "message": "Record not found.",
        "error": "CRM.EXCEPTIONS.NOTFOUNDEXCEPTION",
        "parameters": [
            "contact",
            "789dacae-cf71-414f-9483-ca88acaa46432"
        ]
    }