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 information within CRM.COM (if any). CRM.COM provides the ability to configure the integration’s behaviour, flows or required settings within the back-end.
A Provisioning Provider is a system that provisions services to customer such as an OTT platform (for TV services) or a Freeradius service (for broadband services).
CRM.COM provides the ability to integrate with such systems via its Provisioning Provider Integration Web APIs which are used to forward CRM.COM information to Integrations. Provisioning Providers Integrations in their turn, are plugged into CRM.COM and they act as an intermediate between CRM.COM and the Provisioning Provider itself, as they translate CRM.COM information into Provisioning Provider information and functionality.
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 instructs the integration on how, when and which services should be provisioned (and to which devices in cases where services are provisioned via a device). CRM.COM triggers the integration for other provisioning-related processes as well, like messaging, service or device management.
Flow
- Within CRM.COM various events are fired when managing services like adding or activating a service. On each event, Provisioning Provider Intgration Web APIs are triggered that include information of the CRM event i.e. which services should be authorised/de-authorised (and to which devices, if any). CRM.COM calls integration Web APIs for messaging events as well as for performing service/device management actions.
- Provisioning Provider Integration accepts the Web APIs calls, process the received information and translates it into commands that will be fowrarded to the provisioning provider that actually delivers/enables the service to the subscriber.
- 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 triggers the Provisioning Provider Integrations in the following cases:
- Manage Entitlements: Whenever a service is added, removed or updated (e.g. activated or deactivated) on a subscription, manage entitlements is triggered to authorise or de-authorise the service accordingly. In cases where devices are also required to deliver the service, CRM.COM clearly states the service and ti which device it will be enabled on.
- Send Messages: Through CRM.COM’s communicayion plans, messages are sent to devices
- Send Device Commands: Send provisioning commands that manage or 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)
A Provisioning Provider Integration must implement CRM.COM’s Integration Web APIs for a successful set of integration points.
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 represent 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. Maintaining a mapping between the service and the Provider, enables CRM.COM to trigger the appropriate Provisioning Provider at each event.
- Devices can also be provisioned. Devices can only be provisioned to a single Provisioning Provider which is clearly stated per device product within CRM.COM. Basic device information sent over to the provider includes its serial number, electronic ID and the device’s characteristics.
Required Configuration
In order for the whole integration flow to work properly, follow these steps:
- Set up service products within CRM.COM, mark them as to be used for Provisioning and for which Provisioning Provider(s) and finally set up their external reference(s).
- In case where devices will also be provisioned, mark the traceable physical good (i.e. the device’s product) as to be used for Provisioning and for which Provisioning Provider (can only be one). Additionally, set up the device characteristics, if any. Note that the Provisioning Provider determines a device’s characteristics (e.g. a static IP in the case of Routers).
- Set up CRM.COM’s Integrations by plugging in the new integration. In addition, specify any connection or integration details for this integration point.
Implementation Getting Started
Provisioning Provider Integration must implement CRM.COM’s intregation Web APIs. However, there are two cases; Web APIs that are required to be implemented since they are triggered in each CRM.COM event (like activating a service), and optional ones which are triggered on demand (like messaging).
Required Integration Web APIs
- https://speca.io/CRM/plugin-integrators/V2-WIP#get-provider-attributes
- https://speca.io/CRM/plugin-integrators/V2-WIP#set-provider-attributes
- https://speca.io/CRM/plugin-integrators/V2-WIP#manage-entitlements
Optional Integration Web APIs
- https://speca.io/CRM/plugin-integrators/V2-WIP#get-provisioning-provider-settings
- https://speca.io/CRM/plugin-integrators/V2-WIP#send-message
- https://speca.io/CRM/plugin-integrators/V2-WIP#get-ird-commands
- https://speca.io/CRM/plugin-integrators/V2-WIP#send-ird-command
- https://speca.io/CRM/plugin-integrators/V2-WIP#get-service-commands
- https://speca.io/CRM/plugin-integrators/V2-WIP#send-service-command
Additional information is provided in each one of the integration Web APIs.
Provisioning Provider settings represent the information required for a successful integration between CRM.COM, the Integration and the Provisioning Provider. Through this Web API, the Integration provides CRM.COM some additional settings or information about the Provider’s behaviour or expected information.
This Web API collaborates with Get Provider Attributes Web API.Get Provider Attributes is an integration Web API used among all CRM.COM Integrations (like Payment Gateways as well), whereas Get Provisioning Provider Settings includes specific informaiton and behaviour that can be mapped to CRM.COM behaviour and information. The Web API is triggered whenever a new Provisioning Provider is configued, so it is required to be implemented byt the Integration. If not applicable, then the Web API returns nothing.
Request headers
The secret api key required for API calls to ensure that the client is trusted
Responses
Body
List of characteristics of devices provisioned by the Provisioning Provider. Applicable only if these characteristics’ values are required by the Integration in order to forward commands over to the provider. Within CRM.COM device characteristics are configured using the same value as their key. Then Devices are assigned these characteristics ad a value is given. On provisioning such devices to this provider, the complete set of device characteristics will be sent in key-value pairs. Ensure that device characteristics sent have the same name as implemented at the integration side
[
"username","password","static_ip"
]Set to True when the Provisioning Provider requires service renewals to be performed whenever the renewal/expiration date is required to be provisioned by CRM.COM.
Indicates which system monitors and manages usage consumption and blocking. If set to True, then the provisioning integration requires CRM.COM to moninor and block usage consumtpino once consumers exceed their allowance. If set to False, then CRM.COM monitors usage only for billing purposes and the integration will manage usage blocking.
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": [
""
],
"requires_renewals": "true",
"requires_usage_blocking": true
}Provisioning Provider Integration is triggered whenever services 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 services are provisioned via a device, 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 (and 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 it to send some initialisation commands to the provider.
- device(s) to terminate: devices removed from subscriptions so they should stop provisioning services. Utilise this information 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 identifier 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, 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 (deactivated)
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 service identifier at CRM.COM side. To be used whenever the integration requires additional information from CRM and for this 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 generated by CRM.COM.
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 each 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 service identifier at CRM.COM side. To be used whenever the integration requires additional information from CRM and for this service
The service’s code as this is configured on the Provisioning Provider’s side.
The date that the service is initially authorised on CRM.COM side
The date until which the service will be authorised. Applicable for services that will be authorised for a specific period of time (not open-ended).
The last time the service was successfully authorised. This is information kept in CRM.COM based on previous integration points.
A code that defines the relation between the service and the Provisioning 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
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 service identifier at CRM.COM side. To be used whenever the integration requires additional information from CRM and for this 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
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. It’s stongly suggested to process this list first whenever provided by CRM.COM, before start authorising services to the device.
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
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
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 from the integration to the provisioning pprovider
The response received by the provisioning 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
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": [
{
"id": "b0b7b887-6fc5-957a-8e86-8abe689ed3bc",
"external_reference": "SERV01",
"code": "4345676789000987"
}
],
"authorise_services": [
{
"id": "b0b7b887-6fc5-957a-8e86-8abe689ed3bc",
"external_reference": "101",
"start_date": 1622009627,
"end_date": 1622009628,
"last_authorisation_date": 1622009627,
"code": "4345676789000987",
"device": {
"external_reference": "STB2231233401",
"electronic_id": "",
"characteristics": [
{
"key": "mac_address",
"value": "12:a1:b5:00"
}
]
},
"product": {
"classification": "TERMED_SERVICE",
"type": "HD Decoders"
}
}
],
"deauthorise_services": [
{
"id": "b0b7b887-6fc5-957a-8e86-8abe689ed3bc",
"external_reference": "102",
"code": "4345676789000987",
"device": {
"external_reference": "STB2231233203",
"electronic_id": "",
"characteristics": [
{
"key": "mac_address",
"value": "12:a1:b5:00"
}
]
},
"product": {
"classification": "TERMED_SERVICE",
"type": "HD Decoders"
}
}
],
"initialised_devices": [
{
"external_reference": "STB2231233100",
"electronic_id": "",
"characteristics": [
{
"key": "mac_address",
"value": "12:a1:b5:00"
}
],
"product": {
"type": "HD Decoders",
"sku": "STB-12345"
}
}
],
"terminated_devices": [
{
"external_reference": "STB2231233303",
"electronic_id": "",
"characteristics": [
{
"key": "mac_address",
"value": "12:a1:b5:00"
}
],
"product": {
"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": ""
}
]
}Request headers
The secret api key required for API calls to ensure that the client is trusted
Request body
The contact owning the service
Contact identifier
Contact code
Contact full name
Basic subscription information
Subscription identifier
Subscirption code. This is a unique code
Date of subscription’s first activation
The service identifier at CRM.COM side. To be used whenever the integration requires additional information from CRM and for this service
The service’s external reference which maps to its code/number on the provisioned provider side
Unique key word that describes the device’s characteristic
The characteristic’s 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 from the integration to the provisioning pprovider
The response received by the provisioning provider
POST https://sandbox.crm.com/backoffice/v1/provisioning/usage HTTP/1.1
api_key: 4dc0809f-ed91-4b68-b912-5bd6064d901e
Content-Type: application/json
{
"contact": {
"id": "4dc0809f-ed91-4b68-b912-5bd6064d901e",
"code": "12345-123",
"name": "John Smith"
},
"subscription": {
"id": "4dc0809f-ed91-4b68-b912-5bd6064d901e",
"code": "4435550496877795",
"first_activation": 1661841773
},
"block_usage": [
{
"id": "4dc0809f-ed91-4b68-b912-5bd6064d901e",
"external_reference": "ABC_123",
"device": {
"external_reference": "",
"electonic_id": "",
"characteristics": [
{
"key": "mac_address",
"value": "12:a1:b5:00"
}
]
}
}
]
}
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": ""
}
]
}Integration Web API triggered whenever a termed service is renewed at CRM.COM side, moving thus its next renewal (or expiration) date a period ahead. This new renewal/epxiration date is communicated to the provisioning provider so as to also update the service’s date in the future. This integration Web API can be ignored and not included in the integration if service renewal is not a mandatory process for a successful integration flow.
Request headers
The secret api key required for API calls to ensure that the client is trusted
Request body
The contact owning the service
Contact identifier
Contact code
Contact full name
Basic subscription information
Subscription identifier
Subscirption code. This is a unique code
Date of subscription’s first activation
The service identifier at CRM.COM side. To be used whenever the integration requires additional information from CRM and for this service
The service’s external reference which maps to its code/number on the provisioned provider side
The service’s renewal period starts as of this date
The service’s renewal period ends on this date
Unique key word that describes the device’s characteristic
The characteristic’s 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 from the integration to the provisioning pprovider
The response received by the provisioning provider
POST https://sandbox.crm.com/backoffice/v1/provisioning/service_renewal HTTP/1.1
api_key: 4dc0809f-ed91-4b68-b912-5bd6064d901e
Content-Type: application/json
{
"contact": {
"id": "4dc0809f-ed91-4b68-b912-5bd6064d901e",
"code": "12345-123",
"name": "John Smith"
},
"subscription": {
"id": "4dc0809f-ed91-4b68-b912-5bd6064d901e",
"code": "4435550496877795",
"first_activation": 1661841773
},
"renewed_services": [
{
"id": "4dc0809f-ed91-4b68-b912-5bd6064d901e",
"external_reference": "ABC_123",
"start_date": 1661841773,
"end_date": 1661841773,
"device": {
"external_reference": "",
"electronic_id": "",
"characteristics": [
{
"key": "mac_address",
"value": "12:a1:b5:00"
}
]
}
}
]
}
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 is triggered whenever a communication (or message) is sent to the subscriber. A communication could either be a message stored on the device or an on-screen-display message. The ability to send messages to subscribers is provided through CRM.COM’s Communications Plans. Within the Communication plan the message and the recipients are specified, as well as the Provisioning Provider Integration via which the message will be sent. This integration Web API is optional and does to have to be included in the Integration since it’s triggered by CRM.COm only on demand.
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 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"
}
]
}
],
"message": "Free Trial Period Expires Soon. Join our awesome scheme!",
"type": "MAIL"
}
HTTP/1.1 200 OK Provisioning Provider Integrations might implement/support a number of commands that should 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 can be triggered by CRM.COM that asks the integration for any available commands per device. The integration returns 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. This integration Web API can be ignored and not included in the integration if no device commands are supported.
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": "AMOUNT",
"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 integration replies back with all available options/commands as well as an expected list of each ommand’s metadata attributes
- CRM.COM displays 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 ensures that this will be provided, otherwise this Web API will not be called.
- CRM.COM triggers this Web API.
This integration Web API can be ignored and not included in the integration if no device commands are supported.
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
The device (serial number) on which the command will be performed
The device’s electronic id
The command that should be performed. CRM sends one of the codes previously 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 from the integration to the provisioning pprovider
The response received by the provisioning 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
POST https://sandbox.crm.com/backoffice/v1/provisioning/device_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": "",
"code": "ENFORCE_DOWNLOAD",
"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. The Web API is triggered on demand (eg. through CRM.COM’s UI) i.e. CRM asks the Integration for list of available commands. This integration Web API can be ignored and not included in the integration if no service commands are supported.
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
List of metadata attributes of the service’s command
The attribute’s key that shoulb be unique
The attribute’s label as this will be displayed in the UI
A description for the attribute that will be used to display a Tip in the UI
The attribute’s type
Determines whether an inpt must be provided for the command to be sent successfully.
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": "SINGLE_LINE",
"is_mandatory": true
}
]
}
]
}Calls the Provisioning Provider Integration (plugin) in order to trigger a command related to a specific service. The Ger Service Commands Web API was previously called by CRM to get the list of implemented commands along with their required information. This integration Web API can be ignored and not included in the integration if no device commands are supported.
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 device’s electronic ID
The provisioning code that relates the service to the device. For each device that delivers the service there’s a uniue provisioning code
Unique key word that describes the device’s characteristic
The characteristic’s value
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 from the integration to the provisioning pprovider
The response received by the provisioning provider
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",
"electronic_id": "",
"code": "9944583233212000",
"characteristics": [
{
"key": "mac_address",
"value": "12:a1:b5:00"
}
]
}
],
"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": ""
}
]
}Introduction
A Payment Gateway is a service used by a merchant, responsible for capturing payment details and transfers money from a contact’s bank account into the marchant’s bank account. The Payment Gateway is responsible for:
- Capturing and maintaining the contact’s payment method details like Credit Card numbers
- Check whether money is available in the contact’s payment method
- Perform Payments, Refunds and Payouts
CRM.COM provides the ability to integrate with Payment Gateways to manage various payment flows:
- Card-holder Present Transactions (CIT): Initiated in front-end systems (apps and portals), flows in which the contact is present and the requested payment requires some additional actions like consumer authentication, 3DS etc.
- Merchant Initiated Transactions (MIT): Server-side payment flows where no extra actions are required like automated payments initiated due to recurring billing.
CRM.COM provides a complete set of Payment Gateway Integration Web APIs that can be used to cover the various payment flows. A Payment Gateway integration implements these Web APIs and then it needs to be plugged in into CRM.COM.
Integration Points
CRM.COM triggers a Payment Gateway Integration in various cases:
- On registering a new payment method or when updating an existing one.
- On performing various financial events like Topups, Payments, Refunds and Payouts i.e. whenever funds need to be captured on the Payment Gateway service.
The Payment Gateway on which the payment method was registered (or tokenised) is the one that will be triggered on each financial event.
The Payment Gateway Integration implements the integration Web APIs, it accepts the requests from CRM.COm and forwards them to the Payment Gateway service. The Payment Gateway Integration might reply back to CRM.COM immediatelly (e.g. in Card payments) or after a period of time (e.g. SEPA payments). In the latter case, the integration will have to callback CRM.COM about the flow’s result.
CRM.COM Terminology
Payment Methods: A contact’s payment method shows their preferred source for paying off physical goods and services purchased from a business. Within CRM.COM, payment methods are classified into online and offline ones. Online payment methods indicate that money will be collected immediately through a Payment Gateway service. Online payment methods require some verification from the payment gateway through which payments are submitted. On the other hand, offline payment methods indicate that a company will collect the money manually like payments using Cash. CRM.COM supports the following online payment method types:
- Card that could be any Debit, Credit, Prepaid card
- Account Debit, indicating a bank account like SEPA
- Wallet, any wallet-based method like PayPal
Payment Intents: CRM.COM uses payment intents to control the whole process of collecting money from the contact in both CPT and MIT flows. The payment intent:
- keeps track of the financial event’s lifecycle on both CRM.COM-side and the integration side, maintaining thus a correct flow with no duble-charges.
- provides payment information to the integration, not just for the payment method and amount, but also when the funds will be captured and if the payment is confirmed or not by the contact.
- provides an enhanced security for front-end payments since it is always generated and maintained only at server-side. So a front-end system cannot modify the intent and its amount.
{id}{id}Retrieve the attributes related to the Payment Gateway integration’s main processes and behaviour. This integration eb API is triggered when the integration is set up in CRM.COM’s backend and its information can be utilised by CRM.COM during the various payment flows. This is an optional Web API, if no information is sent, then CRM.COM applies some behaviour.
Request headers
The secret api key required for API calls to ensure that the client is trusted
Responses
Body
Which financial transactions are supported by the payment gateway. Multiple classifications can be specified. If nothing is sent to CRM.COM, then CRM.COM triggers the integration is all of financial events. For example, if the Payment Gateway service does not support Payouts, then on perfoming a Payout in CRM.COM that Payment Gateway’s payment method will not be available for selection in CRM.COM therefore, the integration will not be triggered.
PAYMENTSThe payment gateway integration’s supported payment method types. Multiple types can be specified. If nothing is sent to CRM.COM, then CRM.COM considers that the Payment Gateway service supports all types, i.e. it the service can log payment methods of any type. This information is used on adding new payment methods.
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"
]
}Integration Web API used by front-end systems (e.g. mobile apps) to acquire configuration settings from the Payment Gateway service. This information, also called client token, is required by front-end systems for a successful communication with the service since it authenticates/authorises the client. This is an optional Web API since it depends on the Payment Gateway’s communication protocol. In addition, the Web API is called on demand and only if required by the client-side implementation.
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": "c95f566f-22b8-9242-bfad-beb81e751541",
"code": "9b0ffd269ca2",
"name": "John Doe"
}
}
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 new payment method to the contact. The request includes the payment method’s tokenised information and details previously captured via SDK, HPP of other data capture utility of the Payment Gateway service. CRM.COM forwards this information so the integration performs any required steps to log the new payment method to the Payment gateway service (e.g. create cotnact account and/or add the new payment method). A single payment method can be added per Web API call and for each method either a Card, an Account Debit or a new Wallet method’s details are required. In cases, where the Payment Gateway service does not support storing detals on its side, then the Web API must still be implemented by the integration and return an epty response back to CRM.COM since this Web API is triggered whenever a new payment method is added
Request headers
Secret API Key
Request body
Unique identifier of contact from CRM.COM can be used as the payment gateway’s contact ID if supported or a link relationship
The contact’s full name
Contact’s email address
Contact’s phone number
Address Line 1
Address Line 2
State/Province/County
Town/City
Postal Code
Country 3-char code
Card Details. Applicable and required only for Card payment method type. The card’s details include only the tokenised information previously acquired by the Payment Gateway service.
Unique token of the card that is either a token or unique id provided by an SDK or HPP flow.
A payment method nonce, previously obtained from the payment gateway. Applicable and required for Wallet paymetn method types.
Payment Method nonce
Bank account name
Bank Account number
The IBAN number
Swift code
Sort code
Mandate information
Reference number
Mandate sign date
Account holder details
Account holder name
Address line 1
Address line 2
Town/City
State/Province/Country
Postal Code
Cuntry 3-char code
Bank Name
Bank code
The country the bank account is located in.
Currency 3-char code
Responses
Body
A unique identifier of the payment method at the integration side (called id, token, fingerprint). This unique identifier kept at CRM.COM side as a reference between the payment methods between the two sides (CRM.COM and Payment Gateway service). After acquiring the first token on data capturing flow, the Payment Gateway service might reply back with another token after adding the payment method at their side. CRM.COm considers this token as the final token to be stored on its side. Return back the token even if it remains the same after this Web API call.
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)
Additional information of a Card payment method sent back to CRM.COM if it is available at integration side. This information is optional but it is useful in cases where CRM.COM does not have access to these details at the time of capturing. Integration could send this infroamtion back to CRM.COM in order to be stored at CRM.cOM side and be displayed in the UI for usability purposes to the consumer.
The Card’s brand
First six digits of the Card
Last four digits
Card’s expiration details
Expiration month
Expiration year
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": "jsmith@anemailaddress.coom",
"phone": "0003799655444",
"address": {
"address_line_1": "Main Street 100",
"address_line_2": "Athens",
"state_province_county": "Attica",
"town_city": "Athens",
"postal_code": "1026",
"country_code": "GRC"
}
},
"card": {
"token": "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_code": ""
},
"bank": "",
"bank_code": "",
"country_code": "CY",
"currency_code": "EUR"
}
}{id}Update the Payment Method at the Payment Gateway service based on CRM.COM’s updated information. Depending on the payment method type, only specific piece of information can be updated. When updating, at least Card, Account Debit or Wallet update information must be sent.
Path variables
The unique identifier of the payment method as this was set in CRM.COM
Request headers
Secret API Key
Request body
The payment method’s tokenised information at this was stored in CRM.COM after its addition in Paymet Gateway service. This information can be used by the integration to identify the payment method to be updated.
Unique identifier of contact from CRM.COM can be used as the payment gateway’s contact ID if supported or a link relationship
The contact’s full name
Contact’s email address
Contact’s phone number
Address Line 1
Address Line 2
State/Province/County
Town/City
Postal Code
Country 3-char code
Card Details. Applicable and required only for Card payment method type. For each Card only its expiration information can be updated
Expiration month
Expiration year
Bank account name
Bank Account number
The IBAN number
Swift code
Sort code
Mandate information
Reference number
Mandate sign date
Account holder details
Account holder name
Address line 1
Address line 2
Town/City
State/Province/Country
Postal Code
Cuntry 3-char code
Bank Name
Bank code
The country the bank account is located in.
Currency 3-char code
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
{
"token": "",
"type": "CARD",
"contact": {
"id": "61d25bd9-194b-5631-3395-7ab299302ead",
"name": "John Smith",
"email": "jsmith@anemailaddress.coom",
"phone": "0003799655444",
"address": {
"address_line_1": "Main Street 100",
"address_line_2": "Athens",
"state_province_county": "Attica",
"town_city": "Athens",
"postal_code": "1026",
"country_code": "GRC"
}
},
"card": {
"exp_month": 3,
"exp_year": 25
},
"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_code": ""
},
"bank": "",
"bank_code": "",
"country_code": "CY",
"currency_code": "EUR"
}
}{id}Delete the payment method. The payment method was removed from CRM.COM side upon contact request, so it should also be removed at the Payment Gateway service. Within CRM.COM a payment method can be removed at any point of time with no restrictions to the contact.
Path variables
The payment method (identifier) to be deleted
Request headers
Secret API Key
Request body
The payment method’s tokenised information at this was stored in CRM.COM after its addition in Paymet Gateway service. This information can be used by the integration to identify the payment method to be updated.
Unique identifier of contact from CRM.COM can be used as the payment gateway’s contact ID if supported or a link relationship
The contact’s full name
Contact’s email address
Contact’s phone number
Address Line 1
Address Line 2
State/Province/County
Town/City
Postal Code
Country 3-char code
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
{
"token": "",
"type": "CARD",
"contact": {
"id": "61d25bd9-194b-5631-3395-7ab299302ead",
"name": "John Smith",
"email": "jsmith@anemailaddress.coom",
"phone": "0003799655444",
"address": {
"address_line_1": "Main Street 100",
"address_line_2": "Athens",
"state_province_county": "Attica",
"town_city": "Athens",
"postal_code": "1026",
"country_code": "GRC"
}
}
}
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. The payment intent is initiated by CRM.COM in order to declare its intention to collect money from the Payment Gateway service. It includes detailed information about the contact, the payment method and the required amount. The payment intent is initiated by various financial events like placing an order that requires a payment or posting a Top-up. The integration must reply back with the intent’s result at the payment gateway service’s side either immediatelly (i.e. as a response of this Web API call) or at a later stage via a callback using the Update Payment Intent Web API.
Request body
Details about the contact
The contact identifier
The contact name
The contact code
The payment method’s tokenised information
Bank account name
Bank Account number
The IBAN number
Swift code
Sort code
Mandate information
Reference number
Mandate sign date
Account holder details
Account holder name
Address line 1
Address line 2
Town/City
State/Province/Country
Postal Code
Cuntry 3-char code
Bank Name
Bank code
The country the bank account is located in.
Currency 3-char code
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 payment intent’s token. The integration assigns a unique token for the intent so CRM.COM can forward it back to front-end systems. If this token is not returned by the Payment Gateway service nor by the integration itself, then CRM.cOM will still assign one and return it back to the client for security purposes.
The error code return by the integrator
The error description return by the integrator
The payment intent’s state after the integration gets a response back from the Payment Gateway service.
Integration logged the intent at the Payment Gateway service successfully, but it’s final result is still pending (whether the funds exist or not)
Integration gor back a reply from the Payment Gateway service that there are not enough funds as requested.
Integration logged the intent and Payment Gateway confirmed that funds exist and are captured as well.
Integration logged the intent, Payment Gateway service confimred that funds exists but fnds are kept on hold. Final capturing will be performed at a later stage, otherwise funds will be released within a period of time.
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 Smith",
"code": "C00000123"
},
"payment_method": {
"id": "",
"type": "CARD",
"token": "",
"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_code": ""
},
"bank": "",
"bank_code": "",
"country_code": "CY",
"currency_code": "EUR"
}
},
"amount": 9.99,
"currency_code": "EUR",
"capture": "ON_HOLD",
"entity": {
"type": "PAYMENTS",
"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
{
"token": "",
"error_code": "500",
"error_description": "HTTP transport error: java.net.UnknownHostException",
"state": "COMPLETED",
"requests": [
{
"request": "",
"response": ""
}
]
}Update a payment intent. CRM.COM intructs the integration to perform an update on a previosuly submitted intent. This occurs in cases where:
- The intent still requires capturing, i.e. CRM.COM initially requests for funds to be put on hold, so CRM.COM with this update captures or releases these funds
- The intent was pending, so CRM.COM cancels it in cases where the process that initialised it is cancelled as wll
Completed intents can never be updated.
Request body
The payment intent’s unique identifier. Either the id or token must be provided.
The payment intent’s unique code. If the token was not returned by the integration on its creation, then CRM.COM assigns a unique and random 16-digit code.
Defines the action that will be applied on the payment intent
Applicable when the payment intent was initially created with capturing method On hold, so its state is Requires Capturing. This parameter will ask the integration to capture the money (move the money from the contact’s acccount to the merchant’s account)
Confirms payment intent to the payment gateway service. Applicable only if the initial payment intent was not confirmed by the contact.
Cancels the intent and if funds were put on hold, then these must be released. Applicable when the payment intent is no longer valid at server side so it should also be cancelled in the payment gateway service as well. Applicable when the intents state is Requires Capturing or Pending.
Responses
Body
The payment intent identifier
The payment intent’s token.
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/intents HTTP/1.1
Content-Type: application/json
{
"id": "",
"token": "",
"actions": "CAPTURE"
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "0f51ee18-51a1-7233-510c-046f45e12ade",
"token": "",
"error_code": "500",
"error_description": "HTTP transport error: java.net.UnknownHostException",
"state": "COMPLETED",
"requests": [
{
"request": "",
"response": ""
}
]
}Refunds one of the contact’s payments. This integration Web API is triggered whenever CRM.COM triggers a Refund financial event. A Refund is always issued against a posted Payment and the intention is to fully or partially return back the money to the same payment method from which money was taken. CRM.COM instructs the integration to issue a refund based on a previously submitted payment intent. The amount is also stated in cases where the contact is partially refunded. CRM.COM ensures that the payment intent is completed by the time the contact is refunded.
Request body
Issue the Refund based on a payment using its identifier.
Issue the Refund based on a payment intent. The payment intent was Completed in previous payment flows.
Refund issuing reason as stated within CRM.COM
The refund’s amount. If not specified, then the initial transaction is fully refunded.
3-char currency code
Responses
Body
A unique id for the refund transaction as this is generated by either the Payment Gateway service or the integration.
The refund transaction’s token which is a code returned either by the Payment Gateway service or generated by the integration. This code will be sent by CRM.COM back to front-end system that triggered the Refund transaction for security purposes. If not returned by the integration, CRM.COm will issue its own random and uniqe 16-digit code.
The error code return by the integrator
The error description return by the integrator
The refund intent’s state
Payment Gateway service replied that the Refund cannot be created at their side. This will result in rejecting the Refund transaction in CRM.COM as well.
Payment Gateway service replied that the refund intention is logged but there’s no final response of its result. This will result in marking the Refund transaction in CRM.COM as pending as well until the integration calls back with the final result when this is received by the Payment Gateway service.
Payment Gateway service replied that the refund intention was logged and executed successfully This will result in posting the Refund transaction in CRM.COM as well.
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": "11885936-29b2-423c-c241-2963cfdfa43b",
"intent_id": "ab125936-29b2-423c-c241-2340afdfaaf1",
"issue_reason": "Refund due to partial return of goods",
"amount": 9.99,
"currency_code": "EUR"
}
HTTP/1.1 201 Created
Content-Type: application/json
{
"id": "",
"token": "",
"error_code": "500",
"error_description": "HTTP transport error: java.net.UnknownHostException",
"state": "COMPLETED",
"requests": [
{
"request": "",
"response": ""
}
]
}Perform a Payout. This integration Web API is triggered whenever CRM.COM triggers a Payout financial event. A Payout is issued in CRM.cOM whenever the business retuns money back to the contact’s bank account irrespectivelly of previous payments/payment intents. CRM.COM instructs the integration to issue a payout using just an amount of money to be returned.
Request body
Payout issung reason
The payout’s amount.
3-char currency code
Number used for cross-refenence betwen CRM and the plugin. Maps to CRM Payout’s code
The payment method’s tokenised information
Bank account name
Bank Account number
The IBAN number
Swift code
Sort code
Mandate information
Reference number
Mandate sign date
Account holder details
Account holder name
Address line 1
Address line 2
Town/City
State/Province/Country
Postal Code
Cuntry 3-char code
Bank Name
Bank code
The country the bank account is located in.
Currency 3-char code
Responses
Body
A unique id for the payout transaction
The Payout intent’s state after integrating with the Paymen tGateway service
Payment Gateway service replied that the Payout cannot be created at their side. This will result in rejecting the Payout transaction in CRM.COM as well.
Payment Gateway service replied that the Payout intention is logged but there’s no final response of its result. This will result in marking the Payout transaction in CRM.COM as pending as well until the integration calls back with the final result when this is received by the Payment Gateway service.
Payment Gateway service replied that the Payout intention was logged and executed successfully This will result in posting the Payout transaction in CRM.COM as well.
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": "2301a540-8f81-e4d2-7418-dfa714ac53ee",
"issue_reason": "Wrong invoicing",
"amount": 9.99,
"currency_code": "EUR",
"reference_number": "",
"payment_method": {
"id": "",
"type": "CARD",
"token": "",
"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_code": ""
},
"bank": "",
"bank_code": "",
"country_code": "CY",
"currency_code": "EUR"
}
}
}
HTTP/1.1 201 Created
Content-Type: application/json
{
"id": "",
"state": "PENDING",
"error_code": "500",
"error_description": "HTTP transport error: java.net.UnknownHostException",
"requests": [
{
"request": "",
"response": ""
}
]
}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": {
"email": "johndoe@crm.com",
"phone": "0035722265566"
},
"outlet_tap": "VEN0012",
"products": [
{
"product_sku": "10023401",
"product_name": "Soda",
"net_amount": 11.11,
"tax_amount": 0.04,
"total_amount": 11.15,
"quantity": 1
}
],
"reference": "PCE110211",
"performed_on": 1667983702
}
]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
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
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
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
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
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 Set of Web APIs that must be implemented in all plugin integrations. They provide the ability to set up the integration’s settings within CRM.COM. Integration settings include any required piece of infomration that the integration needs to function properly such as:
- Connection details on how the integration connects to the provisioning provider like endpoints, hotname, port etc
- Default or allowed values of various parameters that are inclded in requests from the integration to the provisoning provider. Instead of hardcoding these value at the integratino side, have them configurable in CRM.COM’s Integrations
- Mapping values between provisioning provider and CRM.COm information.
Generate a random API Key that will be used for authenticating/authorising requests made to the provider. This We API is the first Web API call made by CRM.COM to the Integration and this event occurs when creating a new Integration, i.e. when the integration is registered within CRM.COM.
Notes
API Key should be created as part of the process of creating a new Integration (e.g. Probvisioning Provider or 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://sandbox.crm.com/backoffice/v1/plugins/apikeys HTTP/1.1
Content-Type: application/json
{
"organisation_id": "ccc740f9-7482-b689-54ee-bd78e065d550",
"organisation_name": "crm"
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"key": "key-123456789"
}Retrieve the required attributes (as defined in the provisioning provider integration) that need to be set within CRM.COM, when setting up the Integration. Part of the reponse, the provider media (image) is returned as well (if any). The Web API is triggered by CRM.COM when a new Integration is created. The purpose is to request the integration to notify of any required settings that must be set up before initiating the integration between the two systems. Settings are displayed withnin the CRM backend and they can be set up based on the Integration’s specifications. The next step is to save these settings and set them back to the integration using Set Provider Attributes Web API.
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. It must be unique among the integration’s paramters.
The parameter value. If a parameter has a value, then CRM.COM can utilise this information
The parameter label, used for display purposes
Indicates that the parameter will be displayed within CRM.COM as read-only or not.
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": "MULTIPLE_DATES"
}
]
}Send the required integration attributes (as defined in the provisioning integration) as specified within CRM back to the integration. The integration side can store these parameters and their values within its implementation and utilise them in various integration points. This Web APi might be called more times in the future whenever settings are updated, or new ones are added.
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. Each key name is unique
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