Passes Integrators

The passes integration guide provides the necessary information for a third party system to integrate with CRM.COM, for the purpose of managing passes and posting purchases using a pass.

This guide covers gift and top-up passes in both printed and electronic formats, promotion passes are not within the scope of this integration guide.

What are passes?

A pass has carries an initial value and once redeemed the contact wallet is credited in order to use the money to pay for all or part of a purchase.

Passes can be configured to have the following attributes:

• One of two types: Gift or Top-up
• Available in electronic or printed format
• Fixed or variable value
• Validity period whereby a pass must be redeemed
• Unique codes
• Option to hash pass codes using the SHA-1 algorithm
• Optional PIN to provide additional security
  
  

Wallets

CRM.COM uses the eWallet concept to manage a contact’s money, i.e. once a pass has been redeemed, the contact’s wallet is credited with the value of the pass. The wallet is then subsequently debited during each purchase until the wallet funds have been consumed.

Gift Passes

A gift pass would normally be bought and offered as a gift to another person, who, in turn uses it during a purchase as a form of payment without having to provide any personal information. Gift passes can also be purchased and used by the same person, and reloaded multiple times for continuous use.

Top-up Passes

A top-up pass is typically bought and used by a consumer to top-up their own wallet with an amount of money. The consumer must be a registered contact in CRM.COM, with some sort of identifiable personal information (e.g. phone number or email). Top-up passes are single-use only, and are no longer valid once redeemed.

Using the pass code as identification

Once redeemed the actual pass no longer has a value. However, in the case of a gift pass being used by an unknown contact, the pass code must continue to be provided when purchasing, in order to identify the contact and thus the wallet to be used.

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"
        ]
    }

This action loads a pass with money, and is necessary only for those cases where a pass was generated without an initial value. The following steps should be performed when such a pass is purchased, and prior to being redeemed.

The process for redeeming a pass differs depending on whether an electronic/printed, or gift/top-up pass is being redeemed. The final result though is the same, i.e. a contact’s wallet is credited with the value of the pass.

Before a pass is redeemed it must be in Active state and have a value.

REDEEMING A GIFT PASS FOR AN UNKNOWN CONTACT
A new, unknown contact will be created in the system using the gift pass code as the name and surname, and the contact’s wallet will be credited with the pass value. As there are no contact details relating the pass to the actual person, the new contact is identifiable only by the gift pass code. This API call would typically be used for redeeming printed gift passes.

REDEEMING A TOP-UP OR GIFT PASS FOR A REGISTERED CONTACT
The contact redeeming the pass must be an existing contact in the system, once the contact has been identified, their wallet is credited with the pass value. This flow is appropriate for electronic top-up and gift passes, and also for printed top-up passes.

This API call must to be submitted every time a contact makes a purchase with the intent of consuming wallets funds. If successfully completed, then the contact’s wallet will be debited with the spent amount.

Passes with pins
If the pass has an associated pin, then the pin must also be provided for completion of the purchase. If the pin validation is successful - the purchase event will be created and the wallet funds will be adjusted accordingly, however, if the pin validation fails - the purchase event will not be created and wallet funds will not be consumed.

Call this API to retrieve the available wallet balance (remaining pass amount) for a contact. If the pass code has an associated pin, then the pass and pin must be validated first.

This procedure cancels a purchase transaction, any wallet funds spent during the purchase will be refunded to the wallet.

This process would normally take place after the wallet funds for a redeemed gift pass have been consumed, in effect a contact’s wallet is topped-up with an additional amount of money so that it can continue to be used for future purchases.

In the case of an unknown contact using a gift pass, then they can continue to use the gift pass number for identification purposes. If the gift pass has an associated pin then it must be validated first.

This API will typically be called prior to other API calls to check whether a pass code is valid, and to also validate the pin (if applicable), if the request is successful a pass id is retrieved for subsequent API calls.

This API call is necessary when a contact needs to be verified, it can be used in conjunction with a number of other flows such as submitting a purchase transaction.

Perform these API calls to change the pin of an existing pass. For security reasons it’s recommended that the old pin be validated first before the new one is set.

Perform these API calls to change the expiration date of an existing pass. Note that the pass expiration date indicates the date that a pass can be redeemed by, and does not relate to the expiration of the pass value.

This sequence of API calls changes the state of a to Cancelled so that it can’t be redeemed.

This sequence of API calls retrieves the details of a single pass. It’s recommended that the pass code and pin are validated first for security reasons in cases where the pass has an associated pin.

This sequence of API calls changes the state of a printed pass from Draft to Active so that it can be redeemed.

This procedure creates an electronic pass. Both gift and top-up passes can be created in a similar manner but with some minor differences:

• An electronic gift pass can be generated for an unknown contact, or for an existing contact (can only be redeemed by that specific contact)
• The call to generate an electronic gift pass can also include the gift sender information (i.e. name & a message)
• Top-up passes can only be generated for existing contacts

All scenarios for creating a pass are covered in the flows below, if in some cases parameters are optional then this will be stated as such.