Plugin Integrators
Welcome to the CRM.COM Application Programming Interface (API) documentation for Provisioning Provider Integrations.
CRM.COM API is organized around REST. Our API has specific resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses and uses standard HTTP response codes, authentication & verbs.
You can use the entire API in test mode, which does not affect your live data. The API Key used to authenticate any of your requests will determine whether the request is on live mode or test mode.
The API may differ based on each CRM.COM release. For every new release with noticable changes that might alter backwards compatibility, a new version will be created.
CRM.COM API uses either API Keys to authenticate requests or an authentication JWT token obtained from a user successful logging in process.
All API requests made by CRM.COM (Provisioning) Provider API should authenticate using an API (Secret) Key, which can be accessed and managed from the CRM.COM Dashboard.
All API requests must be made over HTTPS. Any request made over plain HTTP or without authentication will fail. In addition, API Keys carry many privileges, so be sure to keep them secure! Do not share your secret API Keys in publicly accessible areas, such as GitHub or client-side code.
API KEY AUTHORIZATION HEADER EXAMPLE
curl -X $HTTP_METHOD -H "api_key: 2189341e-981e-9ad5-9912-11101670314a"
API requests should be made using the HTTPS protocol so that traffic is encrypted. The interface responds to different methods depending on the action required.
| Method | Usage |
|---|---|
| POST | To create a new object, your request should specify the POST method. The POST request includes all of the attributes necessary to create a new object to the targeted endpoint. |
| PUT | To update the information on an existing object, the PUT method should be used. This will update the specified object if it is found using the provided values, regardless of their current values. If it is not found, the operation will return a response indicating that the object was not found. This idempotency means that you do not have to check for a resource’s availability prior to issuing an update command, the final state will be the same regardless of its existence. Requests using the PUT method do not need to check the current attributes of the object. |
| DELETE | To remove an existing object from your environment, the DELETE method should be used. Similar to PUT method, the DELETE method is idempotent. |
| GET | For retrieving information about customers, purchases or orders, the GET method should be used. Any requested information will be returned as a JSON object. The attributes defined by the JSON object can be used to form additional requests. Any request using the GET method is read-only and will not affect any of the retrieved objects. |
Along with the HTTP methods that the API responds to, CRM.COM uses conventional HTTP response codes and human-readable messages in JSON format to indicate the success or failure of an API request.
In the event of a problem, the status will contain the error code, while the body of the response will usually contain additional information about the problem that was encountered.
| HTTP Status | Description |
|---|---|
| 2XX | Return codes in the 200 range indicate that the request was fulfilled successfully and that no error was encountered. |
| 4XX | Return codes in the 400 range, typically, indicate that there was an issue with the request that was sent. Most common reasons could be an invalid authentication method, unauthorised requests or the object that you are requesting does not exist. |
| 5XX | Return codes in the 500 range indicate that there is a server-side problem and CRM.COM cannot fulfill your request at the moment. |
Most of our 4XX range errors that could be handled programmatically contain all the necessary details for a better integration handling. Such details are
- HTTP Status Code & Error are used for programmatic consumption
- Message is human-readable and can be used as a default error message
- Parameters are used for programmatic consumption and can be used for enhancing the interface error message with additional information
4XX ERROR RESPONSE EXAMPLE
An example of a customer not found error is as follows
HTTP/1.1 400 Bad Request
{
"status": 400,
"message": "Record not found.",
"error": "CRM.EXCEPTIONS.NOTFOUNDEXCEPTION",
"parameters": [
"contact",
"789dacae-cf71-414f-9483-ca88acaa46432"
]
}
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
Send to the provisioning provider intergator whenever there’s a change in the set of subscirption services (e.g. whenever an authorisation or a de-authorisation signal must be sent) or in the set of devices which provision the services. Each Web API call must include basic subscirpiton information and then at least one of the following:
- service(s) to authorise on devices (if any)
- service(s) to de-authorise on devices (if any)
- device(s) to initialise
- device(s) to terminate
For OTT platforms, device information is not required.
Request headers
The secret api key required for API calls to ensure that the client is trusted
Request body
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
Details about the services that will be (authorised) provisioned. Multiple services can be authorised on multiple devices per Web API call. When a service is to be authorised on multiple devices in a signle call, then one entry per service-device pair will have to be sent.
The provider’s reference for the service that will be (authorised) provisioned
The date that the service was initially authorised
The last date that the service will be authorised (applicable for one-time services)
roadmap
Details about the device on which the service will be authorised
The device’s external reference, for example its serial number
Details about the services that will be deauthorised. Multiple services can be de-authorised on multiple devices per Web API call. When a service is to be de-authorised on multiple devices in a signle call, then one entry per service-device pair will have to be sent.
The provider;'s reference for the service that will be deauthorised
Details about the devices on which such service will be deauthorised
The device’s external reference, for example its serial number
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, for example its serial number
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.
The device’s external reference, for example its serial number
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.
Error code return by the provisioning integrator
Error description return by the provisioning integrator
A list of provioning requests that might 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/entitlements HTTP/1.1
api_key: 4dc0809f-ed91-4b68-b912-5bd6064d901e
Content-Type: application/json
{
"subscription": {
"id": "b0b7b887-6fc5-957a-8e86-8abe689ed3bc",
"code": "4433940593221123",
"first_activation": 1618998627
},
"authorise_services": [
{
"external_reference": "101",
"start_date": 1622009627,
"end_date": 1622009628,
"last_authorisation_date": 1622009627,
"device": {
"external_reference": "STB2231233401"
}
}
],
"deauthorise_services": [
{
"external_reference": "102",
"device": {
"external_reference": "STB2231233203"
}
}
],
"initialised_devices": [
{
"external_reference": "STB2231233100"
}
],
"terminated_devices": [
{
"external_reference": "STB2231233303"
}
]
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"state": "PENDING",
"reference_number": "423045544544-122",
"error_code": "500",
"error_description": "HTTP transport error: java.net.UnknownHostException",
"requests": [
{
"request": "",
"response": ""
}
]
}Send to the Provisioning Provide Integrator whenever a communication should be sent to the customer’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
The devices on which the message will be sent
The serial number for the device on which the message will be sent to
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
POST https://sandbox.crm.com/backoffice/v1/provisioning/message HTTP/1.1
api_key: 4dc0809f-ed91-4b68-b912-5bd6064d901e
Content-Type: application/json
{
"devices": [
{
"external_reference": "SN091234344450"
}
],
"message": "Free Trial Period Expires Soon. Join our awesome scheme!",
"type": "OSD"
}Retrieve a list of Integrated Receiver/Decoder (IRD) commands (of a device) as implemetned in the provisoning adapter
Request headers
The secret api key required for API calls to ensure that the client is trusted
Responses
Body
The command name
The command code
The command description
Details about the metadata attributes that are required for the specific command
The metadata attribute key
The metadata attribute label
The metadata attribute description
The metadata attribute (supported) field type
Defines whether the metadata attribute is mandatory or not
GET https://sandbox.crm.com/backoffice/v1/provisioning/ird_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": "DATE",
"is_mandatory": true
}
]
}
]
}
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": "MULTIPLE_LINES",
"is_mandatory": true
}
]
}
]
}Send an Integrated Receiver/Decoder (IRD) command for a device over to the provisioning adapter
Request headers
The secret api key required for API calls to ensure that the client is trusted
Request body
The device (serial number) on which the command will be performed
The command that should be performed
The device’s location. Required only when sending a command related to the device’s physical locatin/region.
Details about the metadata attributes that are required for the specific command
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.
Error code return by the provisioning integrator
Error description return by the provisioning integrator
A list of provioning requests that might 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/ird_commands HTTP/1.1
api_key: 4dc0809f-ed91-4b68-b912-5bd6064d901e
Content-Type: application/json
{
"external_reference": "DEV-01",
"code": "RESET_PIN",
"device_location": "master room",
"metadata_attributes": [
{
"key": "pin",
"value": "1234"
}
]
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"state": "PENDING",
"reference_number": "423045544544-122",
"error_code": "500",
"error_description": "HTTP transport error: java.net.UnknownHostException",
"requests": [
{
"request": "",
"response": ""
}
]
}The ability for Payment Gateway Providers 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.
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
Contact Details that may be needed to represent a contact in the payment gateway
Unique identifier of contact from CRM.COM can be used as the payment gateway’s contact ID if supported or a link relationship
Used for identification of a contact
Email of contact
Phone of contact
An address that might also indicate the billing address of the contact
Card Details. Applicable only for Card payment method type
Unique id of the card that is either a token or unique id provided by an SDK or HPP flow.
Bank Details. Applicable only for Direct Debit payment method type. Roadmap
Bank account name
Bank account number
Bank account’s sort code
Responses
POST https://sandbox.crm.com/backoffice/v1/payment_gateways/payment_methods HTTP/1.1
Content-Type: application/json
{
"type": "CARD",
"contact": {
"id": "",
"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": ""
}
},
"card": {
"id": ""
},
"account_debit": {
"account_name": "",
"account_number": "",
"iban": "",
"bank": "",
"bank_code": ""
}
}
HTTP/1.1 201 Created
Content-Type: application/json
{
"id": ""
}Create a payment intent that can be used online or offline.
Request body
The unique identifier of the payment intent at CRM.COM
Unique identifier of the contact
The contact’s payment method identifier
Additional details about the account debit method
The account name (i.e. bank account name)
The account IBAN
The account Business Identifier Code (BIC) - SWIFT code
Details about mandate
The mandate reference
The mandate sign up date
The payment amount
The currency code
roadmap
The order to be paid. Provided by CRM.COM
Details to add to Customer Statement for the payment. Manually specified by the front-end
Responses
Body
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 payen tmethod’s insufficient funds.
Roadmap. Payment intent cancelled after its initial creation. If money was put on hold, then the amount is released.
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": "",
"code": ""
},
"payment_method": {
"id": "d6ee0df7-0ab7-a3cc-4700-9955f6f613d8",
"type": "WALLET",
"fingerprint": "",
"account_debit": {
"account_name": "John Doe",
"iban": "CY17002001280000001200527600",
"swift": "BCYPCY2N",
"mandate": {
"reference": "d9fd84de378f191067da",
"sign_date": 1633951353
}
}
},
"amount": 9.99,
"currency": "EUR",
"capture": "ON_HOLD",
"entity": {
"type": "ORDER",
"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": "",
"error_description": "",
"state": "COMPLETED"
}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.
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
Roadmap. Applicable hwen 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
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 payen tmethod’s insufficient funds.
Roadmap. Payment intent cancelled after its initial creation. If money was put on hold, then the amount is released.
PUT https://sandbox.crm.com/backoffice/v1/payment_gateways/intents HTTP/1.1
Content-Type: application/json
{
"client_secret": "",
"intent_id": "",
"state": ""
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "0f51ee18-51a1-7233-510c-046f45e12ade",
"client_secret": "",
"error_code": "",
"error_description": "",
"state": "PENDING"
}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
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 payen tmethod’s insufficient funds.
Roadmap. Payment intent cancelled after its initial creation. If money was put on hold, then the amount is released.
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"
}Request body
The payout’s amount.
The payment method to which the payout will be sent to. It should be a payment method of type Account Debit.
Responses
Body
A unique id for the refund 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 payen tmethod’s insufficient funds.
Roadmap. Payment intent cancelled after its initial creation. If money was put on hold, then the amount is released.
POST https://sandbox.crm.com/backoffice/v1/payment_gateways/refunds HTTP/1.1
Content-Type: application/json
{
"id": "",
"type": "PAYMENT_INTENT",
"issue_reason": "",
"amount": 9.99,
"curency": "EUR"
}
HTTP/1.1 201 Created
Content-Type: application/json
{
"id": "",
"error_code": "",
"error_description": "",
"state": "COMPLETED"
}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
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
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
GET https://plugin.com/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",
"parameters": [
{
"key": "hostname",
"value": "crm.com/provider",
"label": "Hostname",
"type": "INTEGER"
}
]
}Generate a random API Key that will be used for authenticating/authorising requests made to the provider
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
POST https://plugin.com/plugins/apikeys HTTP/1.1
Content-Type: application/json
{
"organisation_id": "ccc740f9-7482-b689-54ee-bd78e065d550",
"organisation_name": "crm"
}