Generic Transactions

Overview

Generic Transactions are the transactions that can be configured for specific use cases which are out of scope of incoming/outgoing transfers and exchange transactions. Please contact your solution consultant to explain your required use case before using these APIs. IF Team needs to configure your instance for your use case of generic transactions. You'll receive the configured values that can be used as generic-transaction-type. After that, Generic Transaction APIs can be used with specified type values.

Create a Generic Transaction

POST /generic-transactions

{
  "workflow": {
    "code": "direct",
    "narrative": {
      "sourcingMethod": "explicit",
      "enabled": true
    }
  },
  "data": {
    "genericTransaction": {
      "type": "<generic-transaction-type>",
      "clientId": "00000000-0000-0000-0000-000000000000",
      "accountId": "00000000-0000-0000-0000-000000000000",
      "amount": 10,
      "currency": "GBP",
      "attributes": {
        "key01": "value01",
        "key02": "value02"
      }
    },
    "narrative": {
      "template": "Payment of <#if key01??>${key01}</#elseif key02??>${key02}<#/else>N/A</#if>"
    }
  },
  "connect": {},
  "metadata": {}
}

{
  "workflow": {
    "code": "direct",
    "narrative": {
      "sourcingMethod": "explicit",
      "enabled": true
    }
  },
  "data": {
    "genericTransaction": {
      "id": "00000000-0000-0000-0000-000000000000",
      "type": "<generic-transaction-type>",
      "clientId": "00000000-0000-0000-0000-000000000000",
      "accountId": "00000000-0000-0000-0000-000000000000",
      "transactionNumber": "20230613-ABCDEF",
      "amount": 10,
      "currency": "GBP",
      "status": "completed",
      "narrative": "Payment of value01",
      "creationDateTime": "2023-06-13T00:00:00.000",
      "attributes": {
        "key01": "value01",
        "key02": "value02"
      }
    }
  },
  "connect": {},
  "metadata": {}
}

workflow.code must be sent as direct.
data.genericTransaction.type is required and it must be sent using one of the types configured in your instance.
Fields other than attributes are required in data.genericTransaction section.
attributes is a key value map to store any related information with this transaction. Invoice ID, ID from an external service, ID or reference assigned to this transaction on your side can be the example usages.
Narrative is the text that will be displayed on account statements. workflow.narrative configures the usage of narrative. workflow.narrative.sourcingMethod must be one of implicit or explicit.
Implicitly defined narrative means the template of the narrative has already been defined by your solution consultant on IF side and it'll be used to generate the narrative text. In this case, workflow.narrative.enabled & data.narrative shouldn't be included in the payload.
Explicitly defined narrative means the configuration of the narrative is passed in the payload. In this case, workflow.narrative.enabled is required. If the narrative would like to be discarded, workflow.narrative.enabled must be sent as false, otherwise it must be true. If narrative is enabled, data.narrative.template is also required.
data.narrative.template defines how narrative text should be built. It supports Apache Freemarker template language (https://freemarker.apache.org/docs/dgui.html). The values defined in data.genericTransaction.attributes section are passed to template engine to build the narrative. If you'd like to build the narrative on your side and send it as plain text, you can send it in data.narrative.template field without using any template functionality.
Example of narrative generation:
- Narrative Template: Payment for invoice ${invoiceId}
- invoiceId parameter is set in attributes as 123456
- Generated narrative: Payment for invoice 123456
Generic transactions are created as completed and there is no additional status.

Update a Generic Transaction

PATCH /generic-transactions/{id}

{
  "workflow": {
    "code": "direct"
  },
  "data": {
    "genericTransaction": {
      "attributes": {
        "key01": "updated-value",
        "key02": null
      }
    }
  },
  "connect": {},
  "metadata": {}
}

{
  "workflow": {
    "code": "direct"
  },
  "data": {
    "genericTransaction": {
      "id": "00000000-0000-0000-0000-000000000000",
      "type": "<generic-transaction-type>",
      "clientId": "00000000-0000-0000-0000-000000000000",
      "accountId": "00000000-0000-0000-0000-000000000000",
      "transactionNumber": "20230613-ABCDEF",
      "amount": 10,
      "currency": "GBP",
      "status": "completed",
      "narrative": "narrative text",
      "creationDateTime": "2023-06-13T00:00:00.000",
      "attributes": {
        "key01": "updated-value"
      }
    }
  },
  "connect": {},
  "metadata": {}
}

Only attributes of a generic transaction are allowed to be updated. If an already existing key is not available in the request, it means it shouldn't be updated. If a key mentioned in the request with a null value, it means the key should be deleted.
Updating attributes does not affect narrative of the transaction even if narrative template includes the updated attributes. Narratives are immutable and they are created on generic transaction creation.

Get a Generic Transaction

GET /generic-transactions/{id}

{
  "workflow": {},
  "data": {
    "genericTransaction": {
      "id": "00000000-0000-0000-0000-000000000000",
      "type": "<generic-transaction-type>",
      "clientId": "00000000-0000-0000-0000-000000000000",
      "accountId": "00000000-0000-0000-0000-000000000000",
      "transactionNumber": "20230613-ABCDEF",
      "amount": 10,
      "currency": "GBP",
      "status": "completed",
      "narrative": "narrative",
      "creationDateTime": "2023-06-13T00:00:00.000",
      "attributes": {
        "key01": "value01",
        "key02": "value02"
      }
    }
  },
  "connect": {},
  "metadata": {}
}

List Generic Transactions

GET /generic-transactions

Supported query parameters:

parameter	description
metadata.page.number	0-indexed, default=0
metadata.page.size	default=10
data.genericTransaction.type	A predefined type used with generic transactions
data.genericTransaction.clientId	ID of a client
data.genericTransaction.accountId	ID of an account
data.genericTransaction.transactionNumber	transaction number of generic transaction
data.genericTransaction.amountFrom	minimum amount
data.genericTransaction.amountTo	maximum amount
data.genericTransaction.currency	ISO 4217 currency code
data.genericTransaction.creationDateTimeFrom	minimum creation date time
data.genericTransaction.creationDateTimeTo	maximum creation date time
data.genericTransaction.attributes[key]	A key from attributes map. Example usage: If there is an invoiceId defined in attributes with value of 1234, it can be searched using the query of data.genericTransaction.attributes[invoiceId]=1234

{
  "workflow": {},
  "data": {
    "genericTransactions": [{
      "id": "00000000-0000-0000-0000-000000000000",
      "type": "<generic-transaction-type>",
      "clientId": "00000000-0000-0000-0000-000000000000",
      "accountId": "00000000-0000-0000-0000-000000000000",
      "transactionNumber": "20230613-ABCDEF",
      "amount": 10,
      "currency": "GBP",
      "status": "completed",
      "narrative": "narrative text",
      "creationDateTime": "2023-06-13T00:00:00.000",
      "attributes": {
        "key01": "value01",
        "key02": "value02"
      }
    }]
  },
  "connect": {},
  "metadata": {
    "page": {
      "size": 10,
      "number": 0,
      "totalElements": 1,
      "totalPages": 1
    }
  }
}