Connection Objects

Connection objects represent the current state of the link between data on the IF Platform and the corresponding data on the service provider's side. They are utilized in both Built-In and Plug-In connections.

Purpose of Connection Objects

Linking Identifiers
Connection objects map identifiers between the IF Platform and the underlying service provider, ensuring seamless integration and synchronization.

Tracking Asynchronous Operations
They allow you to monitor the status of asynchronous operations performed on the service provider's side, such as:

Issuing an account or card
Closing an account
Processing a transfer

Error Warnings
Connection objects provide warnings about specific errors that may occur during asynchronous processes, enabling prompt resolution and better system reliability.

Structure of Connection Objects

{
  "id": "76b51f7a-2a4a-471f-a66d-d43e4c2728eb",
  "method": "built-in",
  "serviceProvider": "clearbank",
  "reference": "45ff4ac5-fe22-4233-8152-6a3272ae6569",
  "state": "completed-up-to-date",
  "status": "active",
  "error": null
}

{
  "id": "76b51f7a-2a4a-471f-a66d-d43e4c2728eb",
  "method": "built-in",
  "serviceProvider": "currencycloud",
  "reference": "45ff4ac5-fe22-4233-8152-6a3272ae6569",
  "state": "dependency-failed",
  "status": "pending",
  "error": {
    "category": "technical",
    "origin": "platform",
    "code": "generic",
    "message": "Error received from Currencycloud UK: Status: 400, Body: {\"error_code\":\"account_create_failed\",\"error_messages\":{\"\":[{\"code\":\"name_contains_numbers\",\"message\":\"Account name must not contain numbers.\",\"params\":{}}]}}",
    "attributes": {}
  }
}

Field	Description
id	the unique identifier assigned by the service provider. Since service providers use different types of IDs (e.g., UUIDs or numbers), this field is defined as a string.
method	enum with values of `built-in` or `plug-in`
serviceProvider	the code representing the connected service provider.
reference	a human-readable identifier assigned by the service provider. If the service provider assigns only one unique identifier, it will be used for both the `id` and `reference`.
state	enum with values of `pending`, `dependency-completed`, `dependency-failed`, `creation-in-progress`, `completed-up-to-date`, `creation-failed`, `update-in-progress`, `completed-outdated`. Please refer to the state diagram below for more details
status	represents the status of the entity on the service provider's side. The possible values vary by resource type. For example, the statuses for an account may differ from those for a client. Refer to the specific domain documentation for details on the possible statuses.
error	a complex object containing error details. This field is only present if the state is one of the following: `dependency-failed`, `creation-failed` or `completed-outdated`. For all other states, this field is `null`.
error.category	indicates the type of error. Possible values: `functional`: Indicates a validation error caused by the data itself. Updating the data might resolve the issue. Additional details are provided in `error.code` and `error.message`. `technical`: Indicates a technical error, such as a network issue, which requires intervention by IF engineers.
error.origin	indicates where the error originated. Possible values: `customer`: The error occurred in your system, and you pushed the details to the IF Platform. `platform`: The error occurred within the IF Platform. `provider`: The error occurred on the service provider's side.
error.code	a string code that identifies the error. This code can be used for implementing specific logic to handle errors.
error.message	a user-friendly message describing the error in detail.
error.attributes	a dynamic map exposing additional parameters related to the error.