Plugin Integrators
Welcome to the CRM.COM Application Programming Interface (API) documentation for Integrations. CRM.COM provides a complete set of Web APIs (also referred to as Integration Web APIs) that you can use to develop your own integrations (or plugins) that implement:
- Provisioning Providers
- Payment Gateways
- WiFi Platform Providers
- Customer events Management
Getting Started
- Check out each integration documentation provided per Integration category
- Study its set of integration Web APIs
- Implement your plugin
- Register the plugin into CRM.COM
- Set up the Integration within CRM.COM
- Set up any required integration configuration within CRM.COM (if any). The Integration’s configuration within CRM.COM provide the ability to set up the integration’s behaviour and flows.
Get a list of transactions from the Third Party system.
Request parameters
Start date / time for transaction list
Request headers
secret API Key
Responses
Body
Location code mapped to TAP
Reference Number for Order
Date of Transaction
GET https://sandbox.crm.com/backoffice/v1/customer_events/purchases HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"contact": {
"id": "84b5deb0-48fb-3a34-6d3d-8e8512a33f1d",
"surname": "",
"email": "",
"phone": "",
"card": {
"fingerprint": "",
"last4": "",
"brand": ""
}
},
"products": [
{
"id": "",
"sku": "FREDESPR001",
"name": "Freddo Espresso",
"quantity": 2,
"net_amount": 14.15,
"tax_amount": 1.04,
"total_amount": 15.19,
"components": [
{
"id": "",
"sku": "",
"name": "",
"quantity": "",
"net_amount": "",
"tax_amount": "",
"total_amount": ""
}
]
}
],
"fullfilled_by": {
"id": "TAP001",
"name": ""
},
"classification": {
"name": "Delivery Purchase"
},
"payments": [
{
"payment_type": "VOUCHER",
"total_amount": 1,
"net_amount": "",
"tax_amount": ""
}
]
}The ability for Payment Gateway to be configured / used by external gateways. In particualr creating payment methods that can be used by client based initiated flows or server based flows for recurring billing actions.
{id}{id}Client-side is responsible for generating a client token from the payment gateway. The client token includes configuration required for a successfull communication with the gateway as well as it authenticates and authorises the client to communicate with the gateway.
Request body
The contact that wants to make a payment or register a payment method
The contact identifier
The contact code
The contact (full) name
Responses
Body
The client token that authorises the integration with the payment gateway
The error code return by the integrator
The error description return by the integrator
The request sent by the integrator to the external system (that integration is made against)
The response received by the external system (that integration is made against)
POST https://sandbox.crm.com/backoffice/v1/payment_gateways/client_token HTTP/1.1
Content-Type: application/json
{
"contact": {
"id": "",
"code": "",
"name": ""
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"client_token": "",
"error_code": "500",
"error_description": "HTTP transport error: java.net.UnknownHostException",
"requests": [
{
"request": "",
"response": ""
}
]
}Add a payment method that has details collected by a front end SDK, HPP or other Data Capture such as Bank direct Debit
Request headers
Secret API Key
Request body
The details that may be needed to represent a contact in the payment gateway
The unique contact identifier from CRM.COM can be used as the payment gateway’s contact ID if supported or a relationship link
The contact full name
The contact email
The contact phone
An address that might also indicate the billing address of the contact
The address line 1
The address 2
The address state/province/county
The address town/city
The address postal code
The address country (3 code)
The card details (applicable only for card payment method types)
The unique card identifier that is either a token or unique id provided by an SDK or HPP flow
The wallet details (applicable only for wallet payment method types)
A payment method nonce, previously obtained from the payment gateway, by the front-end
The country the bank account is located in.
Responses
The request has succeeded
Body
The error code return by the integrator
The error description return by the integrator
The request sent by the integrator to the external system (that integration is made against)
The response received by the external system (that integration is made against)
The input request was invalid or incorrect, often due to missing a required parameter
The provided API Key or Token is invalid
The API key or Token does not have permissions to perform the request
The requested resource does not exist
The server encountered an unexpected condition which prevented it from fulfilling the request
The server received an invalid response from the upstream server it accessed in attempting to fulfill the request
The server is currently unable to handle the request due to a temporary overloading or maintenance
The server did not receive a timely response from the upstream server
POST https://sandbox.crm.com/backoffice/v1/payment_gateways/payment_methods HTTP/1.1
Content-Type: application/json
{
"type": "CARD",
"contact": {
"id": "61d25bd9-194b-5631-3395-7ab299302ead",
"name": "John Smith",
"email": "john.smith@gmail.com",
"phone": "+4475612345",
"address": {
"address_line_1": "",
"address_line_2": "",
"state_province_county": "",
"town_city": "",
"postal_code": "",
"country": ""
}
},
"card": {
"id": "11885936-29b2-423c-c241-2963cfdfa43b"
},
"wallet": {
"nonce": ""
},
"account_debit": {
"account_name": "",
"account_number": "",
"iban": "",
"swift": "",
"sort_code": "",
"mandate": {
"referencce": "",
"sign_date": ""
},
"account_holder_details": {
"account_holder_name": "",
"address_line_1": "",
"address_line_2": "",
"town_city": "",
"state_province_county": "",
"postal_code": "",
"country": ""
},
"bank": "",
"bank_code": "",
"country": "CY",
"currency": "EUR"
}
}
HTTP/1.1 201 Created
Content-Type: application/json
{
"token": "",
"error_code": "500",
"error_description": "HTTP transport error: java.net.UnknownHostException",
"requests": [
{
"request": "",
"response": ""
}
],
"card": {
"brand": "",
"first6": "",
"last4": "",
"expiration": {
"month": "",
"year": ""
}
}
}{id}Updates basic information of the payment method
Path variables
The unique identifier of the payment method as this was set in CRM.COM
Request headers
Secret API Key
Request body
Contact Details that may be needed to represent a contact in the payment gateway
Used for identification of a contact
Email of contact
Phone of contact
The payment method’s type
Card Details. Applicable only for Card payment method type - ROADMAP
The country the bank account is located in.
The payment method’s tokenised information
Responses
Body
The error code return by the integrator
The error description return by the integrator
The request sent by the integrator to the external system (that integration is made against)
The response received by the external system (that integration is made against)
The input request was invalid or incorrect, often due to missing a required parameter
The provided API Key or Token is invalid
The API key or Token does not have permissions to perform the request
The requested resource does not exist
The server encountered an unexpected condition which prevented it from fulfilling the request
The server received an invalid response from the upstream server it accessed in attempting to fulfill the request
The server is currently unable to handle the request due to a temporary overloading or maintenance
The server did not receive a timely response from the upstream server
PUT https://sandbox.crm.com/backoffice/v1/payment_gateways/payment_methods/{id} HTTP/1.1
Content-Type: application/json
{
"contact": {
"name": "John Smith",
"email": "john.smith@gmail.com",
"phone": "+4475612345",
"address": {
"address_line_1": "",
"address_line_2": "",
"state_province_county": "",
"town_city": "",
"country": "",
"postal_code": ""
}
},
"type": "WALLET",
"card": {
"exp_month": 1,
"exp_year": 1
},
"account_debit": {
"account_name": "",
"account_number": "",
"iban": "",
"swift": "",
"sort_code": "",
"mandate": {
"referencce": "",
"sign_date": ""
},
"account_holder_details": {
"account_holder_name": "",
"address_line_1": "",
"address_line_2": "",
"town_city": "",
"state_province_county": "",
"postal_code": "",
"country": ""
},
"bank": "",
"bank_code": "",
"country": "CY",
"currency": "EUR"
},
"token": ""
}
HTTP/1.1 201 Created
Content-Type: application/json
{
"error_code": "500",
"error_description": "HTTP transport error: java.net.UnknownHostException",
"requests": [
{
"request": "",
"response": ""
}
]
}{id}Deletes the payment method
Path variables
The payment method (identifier) to be deleted
Request headers
Secret API Key
Request body
The payment method’s tokenised information
The country the bank account is located in.
Responses
Body
The error code return by the integrator
The error description return by the integrator
The request sent by the integrator to the external system (that integration is made against)
The response received by the external system (that integration is made against)
The input request was invalid or incorrect, often due to missing a required parameter
The provided API Key or Token is invalid
The API key or Token does not have permissions to perform the request
The requested resource does not exist
The server encountered an unexpected condition which prevented it from fulfilling the request
The server received an invalid response from the upstream server it accessed in attempting to fulfill the request
The server is currently unable to handle the request due to a temporary overloading or maintenance
The server did not receive a timely response from the upstream server
DELETE https://sandbox.crm.com/backoffice/v1/payment_gateways/payment_methods/e893e711-1ca7-f790-0af2-2ea1155cf5de HTTP/1.1
Content-Type: application/json
{
"payment_method": {
"id": "",
"type": "ACCOUNT_DEBIT",
"fingerprint": "",
"account_debit": {
"account_name": "",
"account_number": "",
"iban": "",
"swift": "",
"sort_code": "",
"mandate": {
"referencce": "",
"sign_date": ""
},
"account_holder_details": {
"account_holder_name": "",
"address_line_1": "",
"address_line_2": "",
"town_city": "",
"state_province_county": "",
"postal_code": "",
"country": ""
},
"bank": "",
"bank_code": "",
"country": "CY",
"currency": "EUR"
}
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"error_code": "500",
"error_description": "HTTP transport error: java.net.UnknownHostException",
"requests": [
{
"request": "",
"response": ""
}
]
}Create a payment intent
Request body
The unique identifier of the payment intent at CRM.COM
Details about the contact
The contact identifier
The contact name
The contact code
The payment method’s tokenised information
The country the bank account is located in.
The payment amount
The currency code
roadmap
Details about the entity (i.e. order) to be paid as provided by CRM.COM
The entity type
The entity identifier
Details to add to Customer Statement for the payment. Manually specified by the front-end
Responses
Body
The error code return by the integrator
The error description return by the integrator
Payment Intent’s capturing was set to On hold on its creation
Payment Intent was successfully logged at the payment gateway but there’s a delayed response about its success or failure to collect the money
Payment Intent was successfully completed and money was collected from the payment method
Payment Intent was rejectes since money cannot be collected due to the payent method’s insufficient funds.
Roadmap. Payment intent cancelled after its initial creation. If money was put on hold, then the amount is released.
The request sent by the integrator to the external system (that integration is made against)
The response received by the external system (that integration is made against)
The input request was invalid or incorrect, often due to missing a required parameter
The provided API Key or Token is invalid
The API key or Token does not have permissions to perform the request
The requested resource does not exist
The server encountered an unexpected condition which prevented it from fulfilling the request
The server received an invalid response from the upstream server it accessed in attempting to fulfill the request
The server is currently unable to handle the request due to a temporary overloading or maintenance
The server did not receive a timely response from the upstream server
POST https://sandbox.crm.com/backoffice/v1/payment_gateways/intents HTTP/1.1
Content-Type: application/json
{
"id": "215bbff9-a423-2fef-1943-330e52d75abc",
"contact": {
"id": "915bbff9-a420-2fef-1943-330e52d75ddc",
"name": "John R. Doe",
"code": "C00000123"
},
"payment_method": {
"id": "",
"type": "CARD",
"fingerprint": "",
"account_debit": {
"account_name": "",
"account_number": "",
"iban": "",
"swift": "",
"sort_code": "",
"mandate": {
"referencce": "",
"sign_date": ""
},
"account_holder_details": {
"account_holder_name": "",
"address_line_1": "",
"address_line_2": "",
"town_city": "",
"state_province_county": "",
"postal_code": "",
"country": ""
},
"bank": "",
"bank_code": "",
"country": "CY",
"currency": "EUR"
}
},
"amount": 9.99,
"currency": "EUR",
"capture": "ON_HOLD",
"entity": {
"type": "INVOICE",
"id": "f98f384f-f415-82d6-9fb3-c9941dda2c8a"
},
"statement_info": "Payment for Order O125435 - Date 01.01.2010"
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"client_secret": "",
"error_code": "500",
"error_description": "HTTP transport error: java.net.UnknownHostException",
"state": "COMPLETED",
"requests": [
{
"request": "",
"response": ""
}
]
}Update a payment intent
Request body
The payment intent’s unique identifier. Either the id or client secret must be provided.
The payment intent’s unique identifier. Either the id or client secret must be provided. Note tht in front-end systems, only the client secret is known.
Defines the action that will be applied on the payment intent
Applicable when the payment intent was initially created with capturing method On hold. This parameter will ask the integrtaor to capture the money (move the money from the customer’s acccount to the merchant’s account)
Confirms payment intent to the payment gateway
Applicable when the payment intent is no longer valid at server side so it should also be cancelled in the payment gateway as well. IF money was put on hold, then cancelling the intents also releases the funds.
Responses
Body
The payment intent identifier
The error code return by the integrator
The error description return by the integrator
Payment Intent’s capturing was set to On hold on its creation
Payment Intent was successfully logged at the payment gateway but there’s a delayed response about its success or failure to collect the money
Payment Intent was successfully completed and money was collected from the payment method
Payment Intent was rejectes since money cannot be collected due to the payent method’s insufficient funds.
Roadmap. Payment intent cancelled after its initial creation. If money was put on hold, then the amount is released.
The request sent by the integrator to the external system (that integration is made against)
The response received by the external system (that integration is made against)
The input request was invalid or incorrect, often due to missing a required parameter
The provided API Key or Token is invalid
The API key or Token does not have permissions to perform the request
The requested resource does not exist
The server encountered an unexpected condition which prevented it from fulfilling the request
The server received an invalid response from the upstream server it accessed in attempting to fulfill the request
The server is currently unable to handle the request due to a temporary overloading or maintenance
The server did not receive a timely response from the upstream server
PUT https://sandbox.crm.com/backoffice/v1/payment_gateways/intents HTTP/1.1
Content-Type: application/json
{
"id": "",
"client_secret": "",
"actions": "CONFIRM"
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "0f51ee18-51a1-7233-510c-046f45e12ade",
"client_secret": "",
"error_code": "",
"error_description": "",
"state": "COMPLETED",
"requests": [
{
"request": "",
"response": ""
}
]
}Refunds one of the contact’s payments. Since the payment gaetway is the side managing the payment intents, this Web APi accepts the payment intent that will be fully or partially refunded.
Request body
Issue the Refund based on a payment. Either a payment or a payment intent must be specified
Issue the Refund based on a payment intent. Either a payment or a payment intent must be specified
The refund’s amount. If not specified, then the initial transaction is fully refunded.
Responses
Body
A unique id for the refund transaction
The error code return by the integrator
The error description return by the integrator
Payment Intent’s capturing was set to On hold on its creation
Payment Intent was successfully logged at the payment gateway but there’s a delayed response about its success or failure to collect the money
Payment Intent was successfully completed and money was collected from the payment method
Payment Intent was rejectes since money cannot be collected due to the payent method’s insufficient funds.
Roadmap. Payment intent cancelled after its initial creation. If money was put on hold, then the amount is released.
The request sent by the integrator to the external system (that integration is made against)
The response received by the external system (that integration is made against)
The input request was invalid or incorrect, often due to missing a required parameter
The provided API Key or Token is invalid
The API key or Token does not have permissions to perform the request
The requested resource does not exist
The server encountered an unexpected condition which prevented it from fulfilling the request
The server received an invalid response from the upstream server it accessed in attempting to fulfill the request
The server is currently unable to handle the request due to a temporary overloading or maintenance
The server did not receive a timely response from the upstream server
POST https://sandbox.crm.com/backoffice/v1/payment_gateways/refunds HTTP/1.1
Content-Type: application/json
{
"payment_id": "",
"intent_id": "",
"issue_reason": "",
"amount": 9.99,
"currency": "EUR"
}
HTTP/1.1 201 Created
Content-Type: application/json
{
"id": "",
"client_secret": "",
"error_code": "",
"error_description": "",
"state": "COMPLETED",
"requests": [
{
"request": "",
"response": ""
}
]
}Request body
A unique identifier of the Payout
The payout’s amount.
Number used for cross-refenrece betwen CRM and the plugin. Maps to CRM Payout’s code
The payment method’s tokenised information
The country the bank account is located in.
Responses
Body
A unique id for the payout transaction
Payment Intent’s capturing was set to On hold on its creation
Payment Intent was successfully logged at the payment gateway but there’s a delayed response about its success or failure to collect the money
Payment Intent was successfully completed and money was collected from the payment method
Payment Intent was rejectes since money cannot be collected due to the payent method’s insufficient funds.
Roadmap. Payment intent cancelled after its initial creation. If money was put on hold, then the amount is released.
The error code return by the integrator
The error description return by the integrator
The request sent by the integrator to the external system (that integration is made against)
The response received by the external system (that integration is made against)
The input request was invalid or incorrect, often due to missing a required parameter
The provided API Key or Token is invalid
The API key or Token does not have permissions to perform the request
The requested resource does not exist
The server encountered an unexpected condition which prevented it from fulfilling the request
The server received an invalid response from the upstream server it accessed in attempting to fulfill the request
The server is currently unable to handle the request due to a temporary overloading or maintenance
The server did not receive a timely response from the upstream server
POST https://sandbox.crm.com/backoffice/v1/payment_gateways/payouts HTTP/1.1
Content-Type: application/json
{
"id": "",
"issue_reason": "",
"amount": 9.99,
"currency": "EUR",
"reference_number": "",
"payment_method": {
"id": "",
"type": "",
"fingerprint": "",
"account_debit": {
"account_name": "",
"account_number": "",
"iban": "",
"swift": "",
"sort_code": "",
"mandate": {
"referencce": "",
"sign_date": ""
},
"account_holder_details": {
"account_holder_name": "",
"address_line_1": "",
"address_line_2": "",
"town_city": "",
"state_province_county": "",
"postal_code": "",
"country": ""
},
"bank": "",
"bank_code": "",
"country": "CY"
}
}
}
HTTP/1.1 201 Created
Content-Type: application/json
{
"id": "",
"state": "COMPLETED",
"error_code": "500",
"error_description": "HTTP transport error: java.net.UnknownHostException",
"requests": [
{
"request": "",
"response": ""
}
]
}Retrieve the attributes related to the Payment Gateway’s main processes and behaviour.
Request headers
The secret api key required for API calls to ensure that the client is trusted
Responses
Body
Which financial transaction classifications are supported by the payment gateway. Multiple classifications can be specified
PAYMENTSThe payment gateway integration’s supported payment method types
The input request was invalid or incorrect, often due to missing a required parameter
The provided API Key or Token is invalid
The API key or Token does not have permissions to perform the request
The requested resource does not exist
The server encountered an unexpected condition which prevented it from fulfilling the request
The server received an invalid response from the upstream server it accessed in attempting to fulfill the request
The server is currently unable to handle the request due to a temporary overloading or maintenance
The server did not receive a timely response from the upstream server
GET https://sandbox.crm.com/backoffice/v1/payment_gaetways/settings HTTP/1.1
api_key: 4dc0809f-ed91-4b68-b912-5bd6064d901e
HTTP/1.1 200 OK
Content-Type: application/json
{
"classifcations": [
"PAYMENTS"
],
"payment_method_types": [
"WALLET"
]
}Provisioning Provider Integration Web APIs are used to forward CRM.COM information to Integrations responsible for delivering digital services to consumers such as:
- OTT Platforms with/out a device
- Condtional Access Systems
- Radius Servers
- and many more
CRM.COM is considered as the “master system”, whereas the integration-side is the one that follows instructions sent over by CRM.COM. CRM.COM-related information sent over is a generic one, i.e. it is not bound to CRM terminology. On the contrary CRM information refers to generic business terms.
Flow
- Within CRM.COM various events are being fired when managing services. On each event, Provisioning Provider Intgration Web APIs are triggered that include information of the CRM event
- Provisioning Provider Integration accepts the Web APIs calls, process the information and translates it into commands that will be fowrarded to the actual provider which can for example be an OTT platform, a Conditional Access System or Radius server. In general, any provider system that actually authorises the service.
- Provisioning Provider system accepts and processes the request command and replies back to the the integration. the integration it self replies back to CRM.COM with the response
Integration Points CRM.COM will trigger the Provisioning Provider in the following cases:
- Manage Entitlements: Whenever a service is added, removed on updated (in terms of its state e.g. activated) on a subscription, manage entitlements is triggered so as to authorise or de-authorise the service
- Send Messages: Through CRM.COM’s communicaion plans, send messages to devices
- Send Device Commands: Send commands that manage/set up a device’s settings or features (commands other than authorising/deauthorising services)
- Send Service Commands: Send commands that perform additional actions on services (other that authorising them)
- Manage User: Commands that manage a user/account information on the provider’s side. A user/account is mapped to a contact in CRM.COM that subscribed to one or more services
CRM.COM Terminology CRM provisions Services as well as Devices
- Within CRM services are configured as to be used for Provisioning purposes. Such services can have one or more external references that represents their representation codes and how they are configured on the provider’s side. A service might be provisioned to one or more provisioning providers, therefore external references can be configured for each one of the required providers.
- Devices can also be provisioned. Devices can only be provisioned to a single Provisioning Provider. Basic device information sent over to the provider includes ** Serial Numer of the device ** An electronic ID ** A set of device characteristics. A Device migt have multiple characteristics in key-value pairs (e.g. static_ip=0.0.0.0 or pvr_supported=true). So whenever that device’s information is provisioned, the complete listof characterstics required by the provider is also included.
Porovisioning Provider settings represent specific information required by the integration to function properly. This set of settings are sent to CRM.COM and included in the integration’s settings in the back-end.
Request headers
The secret api key required for API calls to ensure that the client is trusted
Responses
Body
List of Device characteristics required by the integration in order to forward commands over to the provider.
The input request was invalid or incorrect, often due to missing a required parameter
The provided API Key or Token is invalid
The API key or Token does not have permissions to perform the request
The requested resource does not exist
The server encountered an unexpected condition which prevented it from fulfilling the request
The server received an invalid response from the upstream server it accessed in attempting to fulfill the request
The server is currently unable to handle the request due to a temporary overloading or maintenance
The server did not receive a timely response from the upstream server
GET https://sandbox.crm.com/backoffice/v1/provisioning/settings HTTP/1.1
api_key: 4dc0809f-ed91-4b68-b912-5bd6064d901e
HTTP/1.1 200 OK
Content-Type: application/json
{
"device_characteristics": [
"username"
]
}Provisioning Provider Integration is triggered whenever services of a contact change within CRM.COM and they need to be either authorised or de-authorised. CRM.COM events that trigger this Web API call, add or remove services or they change their state. In cases where devices are also prvisioned, the Web API is called when new devices are added or existing ones are removed from a subscription.
Each Web API call includes basic contact and subscription information and then at least one of the following:
- service(s) to authorise (and devices on which to be authorised, if any)
- service(s) to de-authorise (ad the devices from which they will be de-authorised, if any)
- device(s) to initialise: if a device is included in this list, then this is the first time that CRM passes information about this device so the integration can utilise this information to send some initialisation commands to the provider.
- device(s) to terminate: devices removed from subscriptions so they should stop provisioning services. Utilise this infroamtion to reset the device’s information.
Note: In case of service change (service in CRM is upgraded/downgraded), then the same Web API call will include the service to the de-authorised and the new service to be authorised.Similar case when a device is replaced by another one.
Request headers
The secret api key required for API calls to ensure that the client is trusted
Request body
Basic Contact information
The unique idnetifier of the contact as this was generated in CRM.COM
The contact’s code. This is an alphanumeric code.
The contact’s state on CRM.COm side. This state determines if the contact still has active or inactive or cancelled services once the event is performed.
Contact still has at least one Effective service
All of the contact’s services are Not Effective
All of the contact’s services are churned, i.e. the contact is not subscribed to any other service
The contact’s full name
The contact’s first name
The contact’s last name
The subscription that groups together the services
The subscription identifier
The subscription code. By default, the subscription’s code is a 16-digit code
The date on which the subscription was first activated
List of services that the contact subscribed to, but were never activated, i.e. they were never authorised on the provider’s side. Use this information in cases where some steps need to be performed before actually authorising the service.
The provider’s reference for the service that is still in Draft state
A code that defines the relation between the service and the provider. This is a random and unique, 16-digit code
Details about the services that will be (authorised) provisioned. In cases where a service is delivered through a device, then this list includes one entry for eash service-device pair, i.e. one entry for each device on which the service will be authorised on. Additionally, if a service has multiple external references configured in CRM.COM, then again the list includes one entry for each reference of the service.
The provider’s reference for the service that will be (authorised) provisioned
The date that the service is initially authorised
The last date that the service will be authorised. Applicable services that will be authorised for a specific period of time.
The date on which the service was successfully authorised
A code that defines the relation between the service and the provider. If a service is enabled on a specific device, then this code also denotes the service-device relation within CRM. This is a random and unique, 16-digit code
Details about the device on which the service will be authorised
The device’s external reference, usually its serial number
An electronic ID that uniquelly identifies the device
Unique key word that describes the device’s characteristic
The characteristic’s value
Product identifier
The product type’s name
The product’s SKU
The product’s classification as this is defined in its product type
The product type’s name
Details about the services that will be de-authorised. In cases where a service is delivered through a device, then this list includes one entry for eash service-device pair, i.e. one entry for each device on which the service will be de-authorised from. Additionally, if a service has multiple external references configured in CRM.COM, then again the list includes one entry for each reference of the service.
The provider’s reference for the service that will be deauthorised
A code that defines the relation between the service and the provider. This is a random and unique, 16-digit code.
Details about the devices on which such service will be deauthorised
The device’s external reference, usually its serial number
The electronic Id that uniquely identifies the device
Unique key word that describes the device’s characteristic
The characteristic’s value
Product identifier
The product type’s name
The product’s SKU
The product’s classification as this is defined in its product type
The product type’s name
A list of devices that require initialisation on the provider side before authorising services to them. Multiple devices can be initialised per Web API call.
The device’s external reference, usually its serial number
The electronic ID that uniquely identifies the device
Unique key word that describes the device’s characteristic
The characteristic’s value
Product identifier
The product type’s name
The product’s SKU
A list of devices that have to be terminated after all services have been de-authorised. Multiple devices can be terminated per Web API call. Use this list of devices when commads need to be sent to the provide rin order to enforce the device to stop sending signals.
The device’s external reference, usually its serial number
The electronic ID that uniquely identifies the device
Unique key word that describes the device’s characteristic
The characteristic’s value
Product identifier
The product type’s name
The product’s SKU
Responses
The request has succeeded
Body
Request sent to the integrator but no response received back (confirming whether the integrator received it, processed it etc)
Provisioning integrator successfully processed the request sent by CRM.COM
Provisioning request sent by CRM.COM was rejected by the integrator
Provisioning integrator received the request by CRM.COM and it’s being processed.
A reference number related to the provisioning request. Return by the provisioning integrator to uniquely identify the request.
The error code return by the integrator
The error description return by the integrator
Defines a list of requests that could be sent per CRM.COM event
The request sent by the provisioning provider integrator to CAS/OTT
The response received by the CAS/OTT
The input request was invalid or incorrect, often due to missing a required parameter
The provided API Key or Token is invalid
The API key or Token does not have permissions to perform the request
The requested resource does not exist
The server encountered an unexpected condition which prevented it from fulfilling the request
The server received an invalid response from the upstream server it accessed in attempting to fulfill the request
The server is currently unable to handle the request due to a temporary overloading or maintenance
The server did not receive a timely response from the upstream server
POST https://sandbox.crm.com/backoffice/v1/provisioning/entitlements HTTP/1.1
api_key: 4dc0809f-ed91-4b68-b912-5bd6064d901e
Content-Type: application/json
{
"contact": {
"id": "4dc0809f-ed91-4b68-b912-5bd6064d901e",
"code": "C00192311",
"state": "ACTIVE",
"name": "John Smith",
"first_name": "John",
"last_name": "Smith"
},
"subscription": {
"id": "b0b7b887-6fc5-957a-8e86-8abe689ed3bc",
"code": "4433940593221123",
"first_activation": 1618998627
},
"draft_services": [
{
"external_reference": "SERV01",
"code": "4345676789000987"
}
],
"authorise_services": [
{
"external_reference": "101",
"start_date": 1622009627,
"end_date": 1622009628,
"last_authorised": 1622009627,
"code": "4345676789000987",
"device": {
"external_reference": "STB2231233401",
"electronic_id": "",
"characteristics": [
{
"key": "mac_address",
"value": "12:a1:b5:00"
}
],
"product": {
"id": "b0b7b887-6fc5-957a-8e86-8abe689ed3bc",
"type": "HD Decoders",
"sku": "STB-12345"
}
},
"product": {
"classification": "ONE_TIME_SERVICE",
"type": "HD Decoders"
}
}
],
"deauthorise_services": [
{
"external_reference": "102",
"code": "4345676789000987",
"device": {
"external_reference": "STB2231233203",
"electronic_id": "",
"characteristics": [
{
"key": "mac_address",
"value": "12:a1:b5:00"
}
],
"product": {
"id": "b0b7b887-6fc5-957a-8e86-8abe689ed3bc",
"type": "HD Decoders",
"sku": "STB-12345"
}
},
"product": {
"classification": "ONE_TIME_SERVICE",
"type": "HD Decoders"
}
}
],
"initialised_devices": [
{
"external_reference": "STB2231233100",
"electronic_id": "",
"characteristics": [
{
"key": "mac_address",
"value": "12:a1:b5:00"
}
],
"product": {
"id": "b0b7b887-6fc5-957a-8e86-8abe689ed3bc",
"type": "HD Decoders",
"sku": "STB-12345"
}
}
],
"terminated_devices": [
{
"external_reference": "STB2231233303",
"electronic_id": "",
"characteristics": [
{
"key": "mac_address",
"value": "12:a1:b5:00"
}
],
"product": {
"id": "b0b7b887-6fc5-957a-8e86-8abe689ed3bc",
"type": "HD Decoders",
"sku": "STB-12345"
}
}
]
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"status": "PENDING",
"reference_number": "423045544544-122",
"error_code": "500",
"error_description": "HTTP transport error: java.net.UnknownHostException",
"requests": [
{
"request": "",
"response": ""
}
]
}Provisioning Provider Integration triggered whenever a communication should be sent to the subscriber’s device. A communication could either be a message stored on the device (e.g. a Set-Top-Box) or an on-screen-display message.
Request headers
The secret api key required for API calls to ensure that the client is trusted
Request body
Basic Contact information as this was generated in CRM.COM.
Contact’s unique identifier
Contact’s code
Contact’s name.
The devices on which the message will be sent
The serial number for the device on which the message will be sent to
The device’s electronic id
Unique key word that describes the device’s characteristic
The characteristic’s value
The product’s classification as this is defined in its product type
The product type’s name
The message (from the communication plan) that will be sent
Defines on which communication channel the message will be sent
Message will be shown On Screen Display (OSD)
Message will be send via email
Responses
The request has succeeded
The input request was invalid or incorrect, often due to missing a required parameter
The provided API Key or Token is invalid
The API key or Token does not have permissions to perform the request
The requested resource does not exist
The server encountered an unexpected condition which prevented it from fulfilling the request
The server received an invalid response from the upstream server it accessed in attempting to fulfill the request
The server is currently unable to handle the request due to a temporary overloading or maintenance
The server did not receive a timely response from the upstream server
POST https://sandbox.crm.com/backoffice/v1/provisioning/message HTTP/1.1
api_key: 4dc0809f-ed91-4b68-b912-5bd6064d901e
Content-Type: application/json
{
"contact": {
"id": "4dc0809f-ed91-4b68-b912-5bd6064d901e",
"code": "C000001245",
"name": "John Smith"
},
"devices": [
{
"external_reference": "SN091234344450",
"electronic_id": "",
"characteristics": [
{
"key": "mac_address",
"value": "12:a1:b5:00"
}
],
"product": {
"classification": "ONE_TIME_SERVICE",
"type": "HD Decoders"
}
}
],
"message": "Free Trial Period Expires Soon. Join our awesome scheme!",
"type": "OSD"
}
HTTP/1.1 200 OK Provisioning Provider Integration might implement/support a number of commands that can be sent over to devices in order to set up their settings and characteristics. These commands are irrelevant to authorising/de-authorising services. For example commands to Reset a PIN, download software etc. This Web API return the list of these device commands back to CRM.COM along with each command’s required attributes. CRM.COM uses this information to dynamically display the available provisioning commands within the UI as part of other device actions.
Request headers
The secret api key required for API calls to ensure that the client is trusted
Responses
Body
The command’s name as this will be displayed in CRM.COM UI
The command’s code. Suggested to be in capital letters only, no spaces.
The command’s description. Can be used to display Tips for the action within the UI
The command’s metadata attributes that are required for the specific command to be successully sent to the provider. CRM.COM will display each attribute as a required input when performing this action within the UI. User’s input will then be forwarded to the integration.
The metadata attribute key. Suggested to be in lower-case letters only, with no spaces
The metadata attribute label. Used for UI purposes within CRM.COM UI
The metadata attribute description
The metadata attribute (supported) field type
Defines whether the metadata attribute is mandatory or not. Command cannot be sent back to the integration unless the user actually enters a value, when mandatory.
GET https://sandbox.crm.com/backoffice/v1/provisioning/device_commands HTTP/1.1
api_key: 4dc0809f-ed91-4b68-b912-5bd6064d901e
HTTP/1.1 200 OK
Content-Type: application/json
{
"content": [
{
"name": "Reset PIN",
"code": "RESET_PIN",
"description": "Resets the PIN to a given value",
"metadata_attributes": [
{
"key": "pin",
"label": "PIN",
"description": "the new pin",
"type": "SINGLE_LINE",
"is_mandatory": true
}
]
}
]
}CRM.COM triggers this Web API whenever a user selects to perform a Device command. In order for the flow to work as expected:
- CRM.COM triggers Get Device Commands so the integratino replies back with all avialable options/commands as well as an expected list of each ommand’s metadata attributes
- CRM.COM displays all available commands per device and their required input (if any)
- User selects the command to be sent. If mandatory input is required, then CRM.COM ensues that this will be provided, otherwise this Web API will not be called.
- CRM.COM triggers this Web API.
Request headers
The secret api key required for API calls to ensure that the client is trusted
Request body
Basic contact information as this is created within CRM.COM
Contact’s unique identifier
Contact code.
Contact full name
Subscription information
Subscription identifier
Subscription code
The device (serial number) on which the command will be performed
The device’s electronic id
The device location
The command that should be performed. CRM sends one of the codes previsouly received via the Get Device Commands Web API.
Unique key word that describes the device’s characteristic
The characteristic’s value
Details about the metadata attributes that are required for the specific command. CRM.COM includes all of the command’s attributes as these were previously sent in the Get Device Commands (i.e.using the same keys)
The metadata attribute key
The metadata attribute value
Responses
The request has succeeded
Body
Request sent to the integrator but no response received back (confirming whether the integrator received it, processed it etc)
Provisioning integrator successfully processed the request sent by CRM.COM
Provisioning request sent by CRM.COM was rejected by the integrator
Provisioning integrator received the request by CRM.COM and it’s being processed.
A reference number related to the provisioning request. Return by the provisioning integrator to uniquely identify the request.
The error code return by the integrator
The error description return by the integrator
Defines a list of requests that could be sent per CRM.COM event
The request sent by the provisioning provider integrator to CAS/OTT
The response received by the CAS/OTT
The input request was invalid or incorrect, often due to missing a required parameter
The provided API Key or Token is invalid
The API key or Token does not have permissions to perform the request
The requested resource does not exist
The server encountered an unexpected condition which prevented it from fulfilling the request
The server received an invalid response from the upstream server it accessed in attempting to fulfill the request
The server is currently unable to handle the request due to a temporary overloading or maintenance
The server did not receive a timely response from the upstream server
POST https://sandbox.crm.com/backoffice/v1/provisioning/ird_commands HTTP/1.1
api_key: 4dc0809f-ed91-4b68-b912-5bd6064d901e
Content-Type: application/json
{
"contact": {
"id": "4dc0809f-ed91-4b68-b912-5bd6064d901e",
"code": "C00001245",
"name": "John Smith"
},
"external_reference": "SN000129828432",
"electronic_id": "",
"device_location": "",
"code": "RESET_PIN",
"characteristics": [
{
"key": "mac_address",
"value": "12:a1:b5:00"
}
],
"metadata_attributes": [
{
"key": "pin",
"value": "1234"
}
]
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"status": "PENDING",
"reference_number": "423045544544-122",
"error_code": "500",
"error_description": "HTTP transport error: java.net.UnknownHostException",
"requests": [
{
"request": "",
"response": ""
}
]
}Provisioning Provider Integration sends a list of commands/actions that can be performed on services as these are implemented at the plugin.
Request headers
The secret api key required for API calls to ensure that the client is trusted
Responses
Body
The name of the command/action used for display purposes in the UI
A unique code for the action
Description of the action to be used for display purposes
GET https://sandbox.crm.com/backoffice/v1/provisioning/service_commands HTTP/1.1
api_key: 4dc0809f-ed91-4b68-b912-5bd6064d901e
HTTP/1.1 200 OK
Content-Type: application/json
{
"content": [
{
"name": "Reset Service",
"code": "RESET_SERVICE",
"description": "Resets theservice's information",
"metadata_attributes": [
{
"key": "code",
"label": "Code",
"description": "A new code",
"type": "DATE_RANGE",
"is_mandatory": true
}
]
}
]
}Calls the Provisioning Provider Integration (plugin) in order to trigger a command related to a sepcific service.
Request headers
The secret api key required for API calls to ensure that the client is trusted
Request body
The command’s code as this is implemented in the integration. Use Get Service Commands to retrieve the applicable codes
The service’s external reference(S) as this is configured within CRM.COM. A service might have multiple external references
The service’s provisioning code. Available when the service is not authorised to any device. When authorised on a device, then get the provisioning codes from the devices list
The contact owning the service
Contact identifier
Contact code
Contact full name
List of devices that deliver the service
The devices external reference e.g its serial number
The provisioning code that relates the service to the device. For each device that delivers the service there’s a uniue provisioning code
Additional information that is required for the command to be sent successfully. Available metadata attributes can be retrieved using Get Service Commands Web API
Attribute’s code
Attribute value
Responses
Body
Request sent to the integrator but no response received back (confirming whether the integrator received it, processed it etc)
Provisioning integrator successfully processed the request sent by CRM.COM
Provisioning request sent by CRM.COM was rejected by the integrator
Provisioning integrator received the request by CRM.COM and it’s being processed.
A reference number related to the provisioning request. Return by the provisioning integrator to uniquely identify the request.
The error code return by the integrator
The error description return by the integrator
Defines a list of requests that could be sent per CRM.COM event
The request sent by the provisioning provider integrator to CAS/OTT
The response received by the CAS/OTT
POST https://sandbox.crm.com/backoffice/v1/provisioning/service_commands HTTP/1.1
api_key: 4dc0809f-ed91-4b68-b912-5bd6064d901e
Content-Type: application/json
{
"code": "RESET_DEVICE",
"external_reference": [
""
],
"provisioning_code": 232345556798432,
"contact": {
"id": "4dc0809f-ed91-4b68-b912-5bd6064d901e",
"code": "12345-123",
"name": "John Smith"
},
"devices": [
{
"external_reference": "SN123456789",
"code": "9944583233212000"
}
],
"metadata_attributes": [
{
"key": "pin",
"value": "1234"
}
]
}
HTTP/1.1 201 Created
Content-Type: application/json
{
"status": "PENDING",
"reference_number": "423045544544-122",
"error_code": "500",
"error_description": "HTTP transport error: java.net.UnknownHostException",
"requests": [
{
"request": "",
"response": ""
}
]
}Retrieve the supported networks for a specific organisation (site) from the WiFi network
Request headers
The secret api key required for API calls to ensure that the client is trusted
Request body
The side identifier that will be used to retrieve related networks
Responses
The request has succeeded
Body
The network identifier
The network name
Defines whether the network is enabled or not
Defines whether the network’s guest access is enabled or not
The page number
The number of records per page
The overal number of records
The input request was invalid or incorrect, often due to missing a required parameter
The provided API Key or Token is invalid
The API key or Token does not have permissions to perform the request
The requested resource does not exist
The server encountered an unexpected condition which prevented it from fulfilling the request
The server received an invalid response from the upstream server it accessed in attempting to fulfill the request
The server is currently unable to handle the request due to a temporary overloading or maintenance
The server did not receive a timely response from the upstream server
Retrieve the supported guest control settings for a specific organisation (site) from the WiFi network
Request headers
The secret api key required for API calls to ensure that the client is trusted
Request body
The side identifier that will be used to retrieve related guest control settings
Responses
The request has succeeded
Body
Defines the redirection URL (landing page) that contacts will access when joining a guest wifi network
The input request was invalid or incorrect, often due to missing a required parameter
The provided API Key or Token is invalid
The API key or Token does not have permissions to perform the request
The requested resource does not exist
The server encountered an unexpected condition which prevented it from fulfilling the request
The server received an invalid response from the upstream server it accessed in attempting to fulfill the request
The server is currently unable to handle the request due to a temporary overloading or maintenance
The server did not receive a timely response from the upstream server
GET https://sandbox.crm.com/backoffice/v1/wifi/organisations/guest_control HTTP/1.1
api_key: 4dc0809f-ed91-4b68-b912-5bd6064d901e
Content-Type: application/json
{
"side_id": "88quh2m6"
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"redirect_url": "https://crm.com/landing-page"
}Retrieve a list of devices (access points) for a specific site (organisation). Based on the retrieved devices will be imported as Transaction Acquiring Points for the given organisation (each device has a dedicated MAC Address that will be set as the TAP code).
Request headers
The secret api key required for API calls to ensure that the client is trusted
Request body
The side identifier that will be used to retrieve related networks
Responses
The request has succeeded
Body
The device name
The device MAC address
The page number
The number of records per page
The overal number of records
The input request was invalid or incorrect, often due to missing a required parameter
The provided API Key or Token is invalid
The API key or Token does not have permissions to perform the request
The requested resource does not exist
The server encountered an unexpected condition which prevented it from fulfilling the request
The server received an invalid response from the upstream server it accessed in attempting to fulfill the request
The server is currently unable to handle the request due to a temporary overloading or maintenance
The server did not receive a timely response from the upstream server
GET https://sandbox.crm.com/backoffice/v1/wifi/organisations/devices HTTP/1.1
api_key: 4dc0809f-ed91-4b68-b912-5bd6064d901e
Content-Type: application/json
{
"site_id": "88quh2m6"
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"content": [
{
"name": "CRM-Nicosia",
"mac_address": "00:00:5e:00:53:af"
}
],
"paging": {
"page": 2,
"size": 20,
"total": 5124
}
}Update the guest control and WiFi networks over to WiFi platform
Request headers
The secret api key required for API calls to ensure that the client is trusted
Request body
The organisation (identifier from WiFi network) of which network will be provisioned
Details about the guest control policy
Defines the URL that guests will be redirected to
Details about the WiFi networks that should be enabled and support guest access
The network identifier
The network name
Defines whether the network is enabled or not
Defines whether the guest access is enabled or not
Responses
The request has succeeded
Body
The error code return by the integrator
The error description return by the integrator
The request sent by the integrator to the external system (that integration is made against)
The response received by the external system (that integration is made against)
The input request was invalid or incorrect, often due to missing a required parameter
The provided API Key or Token is invalid
The API key or Token does not have permissions to perform the request
The requested resource does not exist
The server encountered an unexpected condition which prevented it from fulfilling the request
The server received an invalid response from the upstream server it accessed in attempting to fulfill the request
The server is currently unable to handle the request due to a temporary overloading or maintenance
The server did not receive a timely response from the upstream server
POST https://sandbox.crm.com/backoffice/v1/wifi/organisations/networks/guest HTTP/1.1
api_key: 4dc0809f-ed91-4b68-b912-5bd6064d901e
Content-Type: application/json
{
"site_id": "88quh2m6",
"guest_control": {
"redirect_url": "https://landingpage.crm.com/wifi"
},
"wifi_networks": [
{
"id": "602fcea431d36b25cb2b2269",
"name": "CRM-Nicosia",
"is_enabled": "true",
"is_guest_enabled": "false"
}
]
}
HTTP/1.1 200 OK Authorize a contact device over to WiFi platform
Request headers
The secret api key required for API calls to ensure that the client is trusted
Request body
The side identifier that will be used for authorization purposes
The contact identifier (as configured in CRM) that will be used for authorization and usage purposes
The contact gadget identifier (as configured in CRM) that its provided MAC Address will be used for authorization and usage purposes
The contact MAC address that will be used for authorization purposes
The data transfer limit that contact will be authorized for
Responses
The request has succeeded
Body
The error code return by the integrator
The error description return by the integrator
The request sent by the integrator to the external system (that integration is made against)
The response received by the external system (that integration is made against)
The input request was invalid or incorrect, often due to missing a required parameter
The provided API Key or Token is invalid
The API key or Token does not have permissions to perform the request
The requested resource does not exist
The server encountered an unexpected condition which prevented it from fulfilling the request
The server received an invalid response from the upstream server it accessed in attempting to fulfill the request
The server is currently unable to handle the request due to a temporary overloading or maintenance
The server did not receive a timely response from the upstream server
POST https://sandbox.crm.com/backoffice/v1/wifi/contact/authentication HTTP/1.1
api_key: 4dc0809f-ed91-4b68-b912-5bd6064d901e
Content-Type: application/json
{
"mac_address": "01-23-45-67-89-AB"
}
HTTP/1.1 200 OK POST https://sandbox.crm.com/backoffice/v1/wifi/contact/authorisation HTTP/1.1
api_key: 4dc0809f-ed91-4b68-b912-5bd6064d901e
Content-Type: application/json
{
"mac_address": "23-45-67-89"
}
HTTP/1.1 401 Unauthorized Send the required provider attributes (as defined in the provisioning provider adapter) as specified within CRM
Request headers
The secret api key required for API calls to ensure that the client is trusted
Request body
A set of parameters required for successfully integrating with the 3rd party provider
The parameter key
The parameter value
Responses
The request has succeeded
The input request was invalid or incorrect, often due to missing a required parameter
The provided API Key or Token is invalid
The API key or Token does not have permissions to perform the request
The requested resource does not exist
The server encountered an unexpected condition which prevented it from fulfilling the request
The server received an invalid response from the upstream server it accessed in attempting to fulfill the request
The server is currently unable to handle the request due to a temporary overloading or maintenance
The server did not receive a timely response from the upstream server
PUT https://plugin.com/plugins/settings HTTP/1.1
api_key: 4dc0809f-ed91-4b68-b912-5bd6064d901e
Content-Type: application/json
{
"parameters": [
{
"key": "hostname",
"value": "crm.com/provider"
}
]
}
HTTP/1.1 200 OK Retrieve the required attributes (as defined in the provisioning provider adapter) that need to be set within CRM, when setting up the provider. Part of the reponse, the provider media (image) is returned as well (if any)
Request headers
The secret api key required for API calls to ensure that the client is trusted
Responses
Body
The provisioning provider media URL
The provisioning provider media (logo) URL
A set of parameters required for successfully integrating with the 3rd party provider
The parameter key
The parameter value
The parameter label, used for display purposes
The parameter type
Search component of Products configured in CRM.COM
The input request was invalid or incorrect, often due to missing a required parameter
The provided API Key or Token is invalid
The API key or Token does not have permissions to perform the request
The requested resource does not exist
The server encountered an unexpected condition which prevented it from fulfilling the request
The server received an invalid response from the upstream server it accessed in attempting to fulfill the request
The server is currently unable to handle the request due to a temporary overloading or maintenance
The server did not receive a timely response from the upstream server
GET https://sandbox.crm.com/backoffice/v1/plugins/settings HTTP/1.1
api_key: 4dc0809f-ed91-4b68-b912-5bd6064d901e
HTTP/1.1 200 OK
Content-Type: application/json
{
"media_url": "crm.com/provider.png",
"logo_media_url": "crm.com/logo-provider.png",
"parameters": [
{
"key": "hostname",
"value": "crm.com/provider",
"label": "Hostname",
"is_read_only": true,
"type": "PRODUCT",
"mandatory": "true"
}
]
}Generate a random API Key that will be used for authenticating/authorising requests made to the provisioning provider integration.
Notes
API Key should be created as part of the process of creating a new provider (e.g. payment gateway provider).
Request body
The organisation (ext identifier) on which the provider will be associated with
The organisation (name) on which the provider will be associated with
Responses
Body
The non-encrypted api key value that will be used for subsuquent provisioning authentication
The input request was invalid or incorrect, often due to missing a required parameter
The provided API Key or Token is invalid
The API key or Token does not have permissions to perform the request
The requested resource does not exist
The server encountered an unexpected condition which prevented it from fulfilling the request
The server received an invalid response from the upstream server it accessed in attempting to fulfill the request
The server is currently unable to handle the request due to a temporary overloading or maintenance
The server did not receive a timely response from the upstream server
POST https://plugin.com/plugins/apikeys HTTP/1.1
Content-Type: application/json
{
"organisation_id": "ccc740f9-7482-b689-54ee-bd78e065d550",
"organisation_name": "crm"
}