Before you start developing your features using the WealthOS API, please make sure that the following steps are complete:

• Set-up your own environment unique to your organisation using the link we have provided
• Follow the step-by-step guide to configuring your environment
• Sign-up and obtain keys for sandbox environments of all 3rd party integrations you require from the market place of available integrations in WealthOS
• Setup the keys of the 3rd party integrations within the WealthOS Admin UI

Once you have set yourself up, you can add other users who will be able to collaborate with you.

---

The WealthOS API is a RESTful API that provides synchronous communication between your application and the WealthOS platform. For some calls where WealthOS communicates with a 3rd party application (e.g. KYC providers, Payment providers, Custodians) thus causing asynchronicity in communication, WealthOS also provides anebsocket API so you do not have to build a polling function to retrieve responses.

Your API URLs will be in the following formats:

RESTful API - https://{unique_tenancy_identifier}.sandbox.wealthos.cloud/tenant/{endpoint}/v1

E.g. https://acorn-gb.sandbox.wealthos.cloud/investors/v1

Websocket API - wss://{unique_tenancy_identifier}-ws.sandbox.wealthos.cloud/ws/

E.g. wss://acorn-gb-ws.sandbox.wealthos.cloud/ws/

The Websocket API is used by WealthOS to push asynchronous notifications to your application.

---

The wealth management organisation is granted a secret key that they must use in their API calls to interact with the WealthOS platform securely. This key must be stored securely only in your application server side code. It grants the highest level of access privileges to the WealthOS platform.

You may test your keys by calling on the following endpoints.

RESTful API

To test the secret key: Perform a GET call on ~/tenant/test/hello-world-be

Socket API

In order to authenticate a Websocket API call, a query parameter x-token must be included within the URL.

x-token = your organisation’s secret key

Full URL must read as follows:

wss://{unique_tenancy_identifier}-ws.sandbox.wealthos.cloud/ws?x-token=<api_secret_key>

---

Some of the capabilities exposed via WealthOS tenant API needs to be idempotant (from the perspective of the system). For those requests an additional field request_id is required to be sent with the request. The purpose of the request_id is to give an unique ID for the request, so the system can differentiate requests. Advantage of the request_id is the system can check whether the request have already reached the system. If a request (that should be idempotant) has already reached the system, the duplicate request will be rejected.

Sample response

{
  "status": 400,
  "body": {
    "message" : "duplicate request", 
    "status" : "COMPLETE|PROCESSING", 
    "response" : "<stringified original response body>"
  }
}

The request_id stored for idempotency checks will be deleted after 1 hour after which point a message with the same request_id will be considered as a new request.

---

WealthOS maintains versioning for reference data entities stored within the platform which can be updated by the Wealth Manager BE. This is to ensure integrity of data in the event the same entity is being updated by multiple users via the API.

When requesting for an entity via the API the system will return the latest reference_version which must be provided when the Wealth Manager BE is updating an entity. If the received reference_version is different to the latest reference_version in the system, the update will be rejected.

With each sucessful update done to the entity via the API the system will increment the reference_version.

---

Currently there are limits to the number of requests that can be made to the WealthOS API. Following are these limits:

• Average requests per second 500
• Burst requests 1000
• Total requests per day 10,000

---

• How do I see my API keys and how do I re-new the keys?

  • Your API keys are displayed in the developer section of the WOS Admin GUI. You have to be of user type 'developer' or 'admin' to see this.

• Is it mandatory to connect to the web socket

  • Right now this is optional. However it is highly recommended to do so, because the wealth manager BE can avoid polling (Remember: the REST API calls have a daily quota) for certain important events.

---

Web socket API is used by the WOS system to notify (push) asynchronous events to the Wealth Manager BE

Your Socket API URL would be wss://{socket api root}/ws

For example lets assume your env is gb and tenant ID is acorn. Then,

• Socket API Root: acorn-gb-ws.sandbox.wealthos.cloud

• Socket API URL: wss://acorn-gb-ws.sandbox.wealthos.cloud/ws

WealthOS requires to authenticate the web socket connection before allowing you to communicate with the system through the socket. For that purpose WealthOS socket API expects a query parameter x-token to be attached with the socket URL.

x-token is the ApiSecretKey given you by the WealthOS system

So the actual connection URL must look like

wss://acme-gb-ws.sandbox.wealthos.cloud/ws?x-token=<api_secret_key>

WealthOS socket api uses the concept of channels to group messages exchanged through web socket. A single socket connection may be used to handle one or many channels. Users are advised to implement a proper load balancing scheme.

Messages sent via the channels will be strictly ordered by the event generation time. However, there is no guarantee of ordering messages across channels.

A generic data message passed through the socket looks like,

{
    type: "a string tag that identifies the message"
    resend: "[optional] Indicates whether this is a resend message. Resends can be sent during explicit recovery servicing or due to server recovering from errors"
    ch: "channel name" 
    payload: { 
        .... 
    }
    id: "unique ID for this message"
    ts: "unique sequence number of message"
    
}

Note: The unique sequence number ts is a strictly monotonically increasing timestamp (milliseconds elapsed since January 1, 1970, 00:00:00 UTC). This is unique per channel.

Sent from client to server to subscribe to a channel.

• Channel name should be specified in the ch attribute.
• Unique request ID must be sent in the req_id attribute.

{
    "type": "subscription",
    "ch": "channel to be subscribed",
    "req_id": "request ID",
    "from_ts": past sequence number / Timestamp value (milliseconds)
}

Server responds with a subscribe message which echoes the request. In addition, a status field indicates the subscription status (success or failed) and aneason field indicating the reason in the case of a failure.

{
    "type": "subscription",
    "ch": "subscribed channel",
    "req_id": "request ID",
    "status": "ACK"
}

{
    "type": "subscription",
    "ch": "subscribed channel",
    "req_id": "request ID",
    "status": "NACK",
    "reason": "Error Message"
}

Sent from client to server to unsubscribe from a channel.

• Channel name should be specified in the ch attribute.
• Unique request ID must be sent in the req_id attribute.

{
    "type": "unsubscription",
    "ch": "channel to be unsubscribed",
    "req_id": "request ID"
}

Server responds with a unsubscribe message which echoes the request. In addition, a status field indicates the unsubscription status (success or failed) and aneason field indicating the reason in the case of a failure.

{
    "type": "unsubscription",
    "ch": "channel to be unsubscribed",
    "req_id": "request ID",
    "status": "ACK"
}

{
    "type": "unsubscription",
    "ch": "channel to be unsubscribed",
    "req_id": "request ID",
    "status": "NACK",
    "reason": "Error Message"
}

NOTE

• Subscribing to an already subscribed channel will be rejected.
• Client is expected to re-try, if no response is received within 60 secs

The ws client must send a 'heart-beat' to the server every 60 seconds to keep the socket connection alive. Server will reply back with heat-beat (HB). Server will disconnect the ws connection if no HBs are recived for 3 HB intervals (i.e. between 2 to 3 minutes). Client should also disconnet if no data or hb message is received for 3 minutes

{
    "type": "hb",
    "ch": "system"
}

The ws client can send a past sequence number with the subscription to receive missed updates from the provided sequence number onwards.

{
    "type": "subscription",
    "ch": "channel to be subscribed",
    "req_id": "request ID",
    "from_ts": "past sequence number"
}

Server responds with a subscribe message which echoes the request. Then the ws client will receive past socket updates from the provided sequence number onwards.

{
    "type": "subscription",
    "ch": "subscribed channel",
    "req_id": "request ID",
    "status": "ACK",
    "from_ts": 1625660972000
}
{
    "type": "investor_status",
    "ch": "investors",
    "payload": {
        "investor_id" : "<investor_id>",
        "status" : "'fail' | 'success'", 
        "error" : "",  
        "event": "'kyc.started' | 'kyc.completed'" 
    },
    "id": "fd232671-d47b-4ae2-a4c4-0a37258ffae5",
    "ts": 1625660972222,
    "resend": true
}

NOTE

• If the provided sequence number equals -1, Then the system will send all the past socket updates to the client.
• System only accepts integer type sequence number values.

• investors
• payments
• transactions
• holdings
• reconciliations
• notifications

publish investors

This channel publishes investor related updates.

Message

The investor channel publishes the following message types:

• investor_status : This message type is used to communicate updates to the KYC/AML status of an investor

Payload

Name	Type	Description	Accepted values
type	string	message type	investor_status
ch	string	channel name	investors
payload.investor_id	string	unique ID of investor
payload.status	string		fail , success
payload.error	string	error text. Populated only on failure
payload.event	string	KYC status. Populated only if request is sucessful	kyc.started, kyc.completed

Examples

{
    "type": "investor_status",
    "ch": "investors",
    "payload": {
        "investor_id" : "inv-XUT11265",
        "status" : "success", 
        "error" : "",  
        "event": "kyc.completed" 
    },
    "id": "fd232671-d47b-4ae2-a4c4-0a37258ffae5",
    "ts": 1625660972222
}

publish payments

This channel publishes payment status related updates

Message

The payments channel publishes the following message types:

• payment_update : This message type is used to communicate updates to the status of the payment.
• bulk_payment_update : This message type is used to communicate updates to the status of the bulk payment.

Payment update message

Payload

Name	Type	Description	Accepted values
type	string		payment_update
ch	string		payments
payload.transaction_id	string	Unique ID of the payment
payload.pot_id	string	ID of the pot the payment is directed to
payload.reason	string	This field populated only when payment intent status is failed or cancelled, with reason for cancellation or failure
payload.status	string		pending_confirmation, processing, succeeded, cancelled, failed

Examples

{
    "type": "payment_update",
    "ch": "payments",
    "payload": {
        "transaction_id" : "80784c92-8f9d-4150-b83c-dc",
        "pot_id" : "pot-GYQ5423100",
        "status" : "succeeded"
    },
    "id": "fd232671-d47b-4ae2-a4c4-0a37258ffae5",
    "ts": 1625660972222
}

Bulk payment update message

Payload

Name	Type	Description	Accepted values
type	string		bulk_payment_update
ch	string		payments
payload.batch_id	string	Unique ID of the bulk payment
payload.status	string		pending, payments_creation_failed, payments_created, payments_settlement_in_progress, payments_settled, payments_partially_settled, payments_settlement_failed, processing
payload.erroneous_payments	object	Information of payments in the batch that cannot be accepted
payload.fields.payment_id	string	Unique ID of the individual payment
payload.fields.error	string	Reason for failure or rejection of the individual payment

Examples

{
    "type": "bulk_payment_update",
    "ch": "payments",
    "payload": {
        "batch_id" : "BULKPAY-HSVY5840",
        "status" : "payments_created"
    },
    "id": "fd232671-d47b-4ae2-a4c4-0a37258ffae5",
    "ts": 1625660972222
}

publish transactions

This channel publishes various transaction related updates.

Message

The transactions channel publishes the following message types:

• transaction_initiated : This message type is used to communicate a new transaction created within the system (e.g. a scheduled fee deduction, individual transactions of a portfolio rebalance etc.)
• transaction_updated : This message type is used to communicate an update to a transaction.
• external_transaction_added : This message type is used to communicate a new transaction created in the system via an external party (e.g. transaction created by a custodian).
• transaction_failed : This message type is used to notify the user of a transaction failure.

Payload

For further information regarding the description of fields in the payload, mandatory fields and conditionally returned fields etc. please refer GET pending & past transactions of a pot.

Name	Type	Description	Accepted values
type	string		transaction_updated,transaction_initiated,external_transaction_added
ch	string		transactions
payload.transaction_id	string	Unique ID of the transaction
payload.parent_transaction_id	string	Parent Transaction ID
payload.external_transaction_reference	string	External Transaction Reference
payload.pot_id	string	Pot ID of the transaction
payload.investment_product_id	string	Invetment Prouct ID or cash
payload.client_order_id	string	(Optional) Order identifier assigned by the wealth manager
payload.primary_transaction_type	string	Primary Transaction Type	Fees,Buy,Sell,Transfers,Income,Tax,Contribution,Withdrawal,Corporate actions
payload.sub_transaction_type	string	Sub Transaction Type	Dividend Reinvestment,Interest Reinvestment,Reinvestment,Buy,Sell Cancel,Switch Buy,Sell,Buy Cancel,Switch Sell,Lump sum, Lump sum - non relievable, Employer contribution,Employee contribution,Regular contribution, Regular contribution - non relievable, Regular contribution - Employer, Payment in for fees,Internal Transfer - Cash In,Internal Transfer - Stock In,Internal Transfer - Cash Out,Internal Transfer - Stock Out,Stock Transfer In,Cash Transfer In,Stock Transfer Out,Cash Transfer Out,Commission,Ancillary fee,Management fee,Fee credit,Fee rebate,Advisor ongoing fee,One-off advisor fee,Commission rebate,Custody fees,Dividends,Distributions,Interest,Other income,Takeovers, Mergers & Name Changes - Create,Takeovers, Mergers & Name Changes - Extinguish,Rights Expiry,Rights Exercise,Warrant Exercise,Fixed Income Maturity - Receive Capital, Fixed Income Maturity - Extinguish Bond Units,Fund Merger - Create New Fund Units,Fund Merger - Extinguish Old Fund Units,Rights Issue,Stock Dividend,Spin-Off,Warrant Issue,Stock Split,Fee Tax,Tax Relief,GST,HST,PST,QST,Withholding Tax,PAYE Tax,Non-resident Tax,Penalty,Contribution Refund,Income Withdrawal,Reversal,Withdrawal,Miscellaneous Corporate Action Exercise - Buy,Miscellaneous Corporate Action Exercise - Sell, Contribution Bonus, Fee Sell
payload.type	string	Type of the transaction	pending,archived
payload.sub_type	string	Sub type of the transaction	instructed,confirmed,priced,rejected,settled,cancelled, scheduled, ready_to_submit, submitted, failed
payload.currency	string	Currency of the pot
payload.direction	string	Direction of the transaction	in,out
payload.transaction_quantity	string	Quantity of the investment product transaction. This will be empty for cash transactions
payload.transaction_value	string	Value of the transaction
payload.execution_price	string	Executed price of the buy, sell transaction
payload.trade_date	date	Will indicate the date where this transaction was effected
payload.settlement_date	date	Intendent settlement date of the pending transaction or actual the settled day of the transaction
payload.created_at	time	Transaction created date
payload.updated_at	time	Transaction last updated date
payload.additional_external_details	Object	Additional external details of the transaction, This may be populated in reconciliation process
payload.origin	string	Origin of the transaction	api, admin_ui, file_upload, system
payload.source_id	string	transactions created for payments intents - employer contributions for SIPP Accumulation Products
payload.reason	string	This field populated only when status is failed or canceled, with reason for cancellation or failure

Examples

{
    "type": "transaction_updated",
    "ch": "transactions",
    "object": {
         "pot_id":"pot-GYQ5423100",
         "transaction_id":"80784c92-8f9d-4150-b83c-dc",
         "investment_product_id":"GB0000495209",
         "primary_transaction_type":"Buy",
         "sub_transaction_type":"Buy",
         "type":"archived",
         "sub_type":"settled",
         "currency":"GBP",
         "direction":"in",
         "transaction_quantity":"20",
         "transaction_value":"129.69",
         "execution_price":"6.45",
         "trade_date":"2021-08-06",
         "settlement_date":"2021-08-06",
         "origin": "admin_ui",
         "source_id": "cem-ASP43560",
         "created_at":"2021-08-06T09:25:44.251Z",
         "updated_at":"2021-08-06T09:27:18.003Z",
         "external_transaction_reference": "117709248888833"
     },
    "id":"8e754ef9-5d63-4c2a-9f43-ac42f588e122",
    "ts":1628244517263
}

publish holdings

This channel publishes holdings related updates.

Message

The holdings channel publishes the following message types:

• holding_updated : This message type is used to communicate an update to the units of an investment product holding, or value of a cash holding.

Payload

For further information regarding the description of fields in the payload, mandatory fields and conditionally returned fields etc. please refer GET current holdings of a pot.

Name	Type	Description	Accepted values
type	string		holding_updated
ch	string		holdings
payload.pot_id	string	ID of the pot the payment is directed to
payload.investment_product_id	string	Investment product ID or 'cash' for cash
payload.currency	string	Currency of the pot
payload.total_quantity	string	Total Quantity of the investment product holding. This value is empty for cash holdings
payload.free_quantity	string	Free Quantity of the investment product holding. This value is empty for cash holdings
payload.locked_quantity	string	Locked Quantity of the investment product holding. This value is empty for cash holdings
payload.total_value	string	Total Value of the holding
payload.free_value	string	Free Value of the holding
payload.locked_value	string	Locked Value of the holding
payload.investment_product_name	string	Name of the investment product
payload.price	string	Price of the holding
payload.price_date	time	The time which the price is updated
payload.average_book_cost	string	Per-unit book cost for a particular holding (applicable for investment product holdings only)
payload.cost_of_holding	string	Total book cost for the total units currently held within the pot (applicable for investment product holdings only)
payload.settled_cash_position	string	Settled cash amount within the pot (applicable for cash holdings only)
payload.additional_external_details	Object	Additional external details of the holding, This may be populated in reconciliation process

Examples

{
    "type": "holding_updated",
    "ch": "holdings",
    "payload": {
         "pot_id":"pot-GYQ5423100",
         "investment_product_id":"GB0000495209",
         "currency":"GBP",
         "total_quantity":"20",
         "free_quantity":"20",
         "locked_quantity":"0",
         "total_value":"137.358",
         "free_value":"137.358",
         "locked_value":"0",
         "investment_product_name":"BlackRock European Dynamic Fund A Accumulation",
         "price":"6.8679",
         "price_date":"2021-08-06T09:27:37.512Z",
         "average_book_cost": "5",
         "cost_of_holding": "100"        
    },
    "id":"8e754ef9-5d63-4c2a-9f43-ac42f588e122",
    "ts":1628244517263
}

publish reconciliations

The reconciliations channel publishes the following message types:

• investor_summary : This message type is used to communicate a summary of investor reconciliation process.
• investor_mismatch : This message type is used to communicate all mismatches in each investor reconciliations process.
• pot_summary : This message type is used to communicate a summary of pot reconciliation process.
• pot_mismatch : This message type is used to communicate all mismatches in each pot reconciliations process.
• transaction_summary : This message type is used to communicate a summary of transaction reconciliation process.
• transaction_mismatch : This message type is used to communicate mismatches in each transaction reconciliations process.
• transaction_ingestion_failure : This message type is used to communicate ingestion failures in each transaction reconciliations process.
• transaction_ignored : This message type is used to communicate all ignored transactions in each transaction reconciliations process.
• holdings_summary : This message type is used to communicate a summary of holding reconciliation process.
• holdings_mismatch : This message type is used to communicate all mismatches in each holding reconciliations process.

Investor summary message

Payload

Name	Type	Description	Accepted values
type Required	string		investor_summary
ch Required	string		reconciliations
payload.job_id Required	string	Unique ID of reconciliation process
payload.job_name Required	string	type of reconciliations
payload.date Required	string	date and time
payload.total_records Required	number	total record count
payload.mismatched_records Required	number	mismatched record count
payload.incoming_records Required	number	incoming record count
payload.no_incoming_records Required	number	no incoming record count

Examples

{
    "type":"investor_summary",
    "ch":"reconciliations",
        "payload":
        {
            "job_id":"hydrangea-dc-210806-1628240463777",
            "job_name":"Investor Details",
            "date":"2021-08-09T06:49:34.227Z",
            "total_records":1,
            "mismatched_records":1,
            "incoming_records": 0,
            "no_incoming_records": 0
        },
    "id":"e1c7797f-f590-4490-a452-01894b33d014",
    "ts":1628244517823
}

Investor mismatch message

Payload

Name	Type	Description	Accepted values
type Required	string		investor_mismatch
ch Required	string		reconciliations
payload.job_id Required	string	Unique ID of reconciliation process
payload.date Required	string	date and time
payload.record_id Required	string	unique ID of a record
payload.investor_id	string	unique ID of the investor being reconciled (if available)
payload.record_status Required	string	record status	reconciled, unreconciled, not_found, key_unavailable
payload.fields	object	mismatched fields with field, incoming_value, available_value and status
payload.fields.field Required	string	Name of the fields
payload.fields.incoming_value	string	Incoming value for the field
payload.fields.available_value	string	Available value for the field
payload.fields.status	string	status of the field	mismatched, matched

Examples

{
    "type":"investor_mismatch",
    "ch":"reconciliations",
    "payload":
    {
        "job_id":"hydrangea-dc-210806-1628240463777",
        "date":"2021-08-09T06:49:34.227Z",
        "record_id":"F180010Q",
        "record_status":"not_found",
        "fields":
        [
            {"field":"first_name","incoming_value":"David","available_value": "Dane", "status":"mismatched"},
            {"field":"last_name","incoming_value":"Brown", "available_value": "Black", "status":"mismatched"}
        ]
    },
    "id":"8e754ef9-5d63-4c2a-9f43-ac42f588e122",
    "ts":1628244517263
}

Pot summary message

Payload

Name	Type	Description	Accepted values
type Required	string		pot_summary
ch Required	string		reconciliations
payload.job_id Required	string	Unique ID of reconciliation process
payload.job_name Required	string	type of reconciliations
payload.date Required	string	date and time
payload.total_records Required	number	total record count
payload.mismatched_records Required	number	mismatched record count
payload.incoming_records Required	number	incoming record count
payload.no_incoming_records Required	number	no incoming record count

Examples

{
    "type": "pot_summary",
    "ch": "reconciliations",
    "payload": {
        "job_id": "dev14_recon_pot_200",
        "job_name": "Pot Details",
        "date": "2021-09-02T10:07:40.578Z",
        "total_records": 91,
        "mismatched_records": 41,
        "incoming_records": 0,
        "no_incoming_records": 0
    },
    "id": "c574d276-de4b-4014-80f3-80e54d31d3da",
    "ts": 1630577304480
}

Pot mismatch message

Payload

Name	Type	Description	Accepted values
type Required	string		pot_mismatch
ch Required	string		reconciliations
payload.job_id Required	string	Unique ID of reconciliation process
payload.date Required	string	date and time
payload.record_id Required	string	unique ID of a record
payload.pot_id	string	unique ID of the pot being reconciled (if available)
payload.record_status Required	string	record status	reconciled, unreconciled, not_found, key_unavailable
payload.fields	object	mismatched fields
payload.fields.field Required	string	Name of the fields
payload.fields.incoming_value	string	Incoming value for the field
payload.fields.available_value	string	Available value for the field
payload.fields.status	string	status of the field	matched, mismatched

Examples

{
    "type": "pot_mismatch",
    "ch": "reconciliations",
    "payload": {
        "job_id": "dev14_recon_pot_200",
        "date": "2021-09-02T10:07:40.578Z",
        "record_id": "53_RWM",
        "record_status": "not_found",
        "fields": [
            {"field": "custodian_account_reference","incoming_value": "F3A0023Q","status": "mismatched"},
            {"field": "pot_currency","incoming_value": "GBP","status": "mismatched"}
 
        ]
    },
    "id": "7722f072-4e8d-48ec-ad4f-4543e64fb536",
    "ts": 1630577304156
}

Transaction summary message

Payload

Name	Type	Description	Accepted values
type Required	string		transaction_summary
ch Required	string		reconciliations
payload.job_id Required	string	Unique ID of reconciliation process
payload.job_name Required	string	Name of the reconciliations job
payload.date Required	string	date and time
payload.total_records Required	number	total record count
payload.mismatched_records Required	number	mismatched record count
payload.updated_records Required	number	updated record count
payload.unable_to_ingest Required	number	ingestion failed record count
payload.ignored_records Required	number	ignored record count
payload.incoming_records Required	number	incoming record count
payload.no_incoming_records Required	number	no incoming record count

Examples

{
    "type": "transaction_summary",
    "ch": "reconciliations",
    "payload": {
        "job_id": "dev10_cat_inv_178",
        "job_name": "Transaction Details",
        "date": "2021-08-18T09:08:27.171Z",
        "total_records": 8,
        "mismatched_records": 1,
        "updated_records": 4,
        "unable_to_ingest": 1,
        "ignored_records": 1,
        "incoming_records": 7,
        "no_incoming_records": 1
    },
    "id": "7d3614c7-3f63-4930-88df-062c5059047d",
    "ts": 1629277726128
}

Transaction mismatch message

Payload

Name	Type	Description	Accepted values
type Required	string		transaction_mismatch
ch Required	string		reconciliations
payload.job_id Required	string	Unique ID of reconciliation process
payload.date Required	string	date and time
payload.record_id Required	string	unique ID of a record
payload.external_transaction_reference	string	External transaction reference (if available)
payload.transaction_ids	object	Transaction IDs of mismatched records (if available)
payload.pot_id	string	Pot ID of the transaction (if available)
payload.record_status Required	string	record status	unreconciled,not_found,key_unavailable, multiple_found, no_incoming_record, updated
payload.fields	object	mismatched fields
payload.fields.field Required	string	Name of the fields
payload.fields.incoming_value	string	Incoming value for the field
payload.fields.available_value	string	Available value for the field
payload.fields.status	string	status of the field	matched, mismatched, key_value_missing

Examples

{
    "type":"transaction_mismatch",
    "ch":"reconciliations",
    "payload":{"job_id":"peony-transaction_reconciliations-1630493472846",
    "date":"2021-09-01T10:51:18.577Z",
    "record_id":"2_RWM",
    "external_transaction_reference":"117709248888833",
    "transaction_ids": [ "80784c92-8f9d-4150-b83c-dc" ],
    "pot_id":"pot-GYQ5423100",
    "record_status":"unreconciled",
    "fields":[
    {
        "field":"primary_transaction_type",
        "incoming_value":"Buy",
        "available_value":"Corporate actions",
        "status":"mismatched"
    },
    {
        "field":"sub_transaction_type",
        "incoming_value":"Buy",
        "available_value":"Stock Split",
        "status":"mismatched"
    },
    {
        "field":"execution_price",
        "incoming_value":null,
        "status":"mismatched"
    },
    {
        "field":"trade_date",
        "incoming_value":"2021-08-31",
        "status":"mismatched"
    },
    {
        "field":"settlement_date",
        "incoming_value":"2021-09-02",
        "status":"mismatched"
    }
    ]
},
    "id":"0b3aa3b1-b14c-44ee-ac47-656149645ba9",
    "ts":1630493491292
}

Transaction ingestion failure message

Payload

Name	Type	Description	Accepted values
type Required	string		transaction_ingestion_failure
ch Required	string		reconciliations
payload.job_id Required	string	Unique ID of reconciliation process
payload.date Required	string	date and time
payload.record_id Required	string	unique ID of a record
payload.external_transaction_reference	string	External transaction reference
payload.pot_id	string	Pot ID of the transaction (if available)
payload.record_status Required	string	record status	unable_to_ingest
payload.fields Required	object	fields
payload.fields.field Required	string	Name of the fields
payload.fields.incoming_value Required	string	Incoming value for the field
payload.fields.status Required	string	status of the field	unrecognised, key_value_missing

Examples

{
    "type": "transaction_ingestion_failure",
    "ch": "reconciliations",
    "payload": {
        "job_id": "peony-transaction_reconciliations-1630657432163",
        "date": "2021-09-03T08:23:54.373Z",
        "record_id": "3_RWM",
        "external_transaction_reference": "331738147053699",
        "record_status": "unable_to_ingest",
        "fields": [
            {
                "field": "custodian_account_reference",
                "incoming_value": "F3A0000A",
                "status": "unrecognised"
            },
            {
                "field": "pot_currency",
                "incoming_value": "GBP",
                "status": "unrecognised"
            },
            {
                "field": "investment_product_id",
                "incoming_value": "CA1358251",
                "status": "unrecognised"
            }
        ]
    },
    "id": "718f9758-e2b0-4a07-9cc6-8a6cb5aae419",
    "ts": 1630657439928
}

Transaction ignored failure message

Payload

Name	Type	Description	Accepted values
type Required	string		transaction_ignored
ch Required	string		reconciliations
payload.job_id Required	string	Unique ID of reconciliation process
payload.date Required	string	date and time
payload.record_id Required	string	unique ID of a record
payload.record_status Required	string	record status	ignored

Examples

{
    "type": "transaction_ignored",
    "ch": "reconciliations",
    "payload": {
        "job_id": "peony-transaction_reconciliations-1630657867836",
        "date": "2021-09-03T08:31:08.191Z",
        "record_id": "3_RWM",
        "record_status": "ignored"
    },
    "id": "8a82df6b-d34a-4eb9-91a1-b98cd18aa4e2",
    "ts": 1630657913417
}    

Holding summary message

Payload

Name	Type	Description	Accepted values
type Required	string		holdings_summary
ch Required	string		reconciliations
payload.job_id Required	string	Unique ID of reconciliation process
payload.job_name Required	string	type of reconciliations
payload.date Required	string	date and time
payload.total_records Required	number	total record count
payload.mismatched_records Required	number	mismatched record count
payload.incoming_records Required	number	incoming record count
payload.no_incoming_records Required	number	no incoming record count

Examples

{
    "type":"holdings_summary",
    "ch":"reconciliations",
        "payload":
        {
            "job_id":"cat-holding_reconciliations-1631619829926",
            "job_name":"Holdings Details",
            "date":"2021-08-09T06:49:34.227Z",
            "total_records":10,
            "mismatched_records":5,
            "incoming_records": 0,
            "no_incoming_records": 0
        },
    "id":"e1c7797f-f590-4490-a452-01894b33d014",
    "ts":1628244517823
}

Holding mismatch message

Payload

Name	Type	Description	Accepted values
type Required	string		holding_mismatch
ch Required	string		reconciliations
payload.job_id Required	string	Unique ID of reconciliation process
payload.date Required	string	date and time
payload.record_id Required	string	unique ID of a record
payload.pot_id	string	unique ID of the pot being reconciled (if available)
payload.investment_product_id	string	unique ID of the investment product being reconciled (if available)
payload.record_status Required	string	record status	reconciled, unreconciled, not_found, key_unavailable
payload.fields	object	mismatched fields with field, incoming_value, available_value and status
payload.fields.field Required	string	Name of the fields
payload.fields.incoming_value	string	Incoming value for the field
payload.fields.available_value	string	Available value for the field
payload.fields.status	string	status of the field	mismatched, matched, updated

Examples

{
    "type":"holding_mismatch",
    "ch":"reconciliations",
    "payload":
    {
        "job_id":"cat-holding_reconciliations-1631619829926",
        "date":"2021-08-09T06:49:34.227Z",
        "record_id":"RWM_9_sr",
        "pot_id": "pot-GYQ5423100",
        "investment_product_id": "pqr",
        "record_status":"not_found",
        "fields":
        [
            {"field":"custodian_account_reference","incoming_value":"F180010Q","status":"mismatched"},
            {"field":"free_value","incoming_value":0, "status":"mismatched"}
        ]
    },
    "id":"8e754ef9-5d63-4c2a-9f43-ac42f588e122",
    "ts":1628244517263
}

publish notifications

This channel publishes general notifications.

Message

The notifications channel publishes the following message types:

• recurring_contribution_activated : This message type is used to communicate activation of recurring contribution requests
• recurring_contribution_cancelled : This message type is used to communicate cancellation of recurring contribution requests
• recurring_contribution_rejected : This message type is used to communicate rejection of recurring contribution requests
• recurring_contribution_authorization_url_received : This message type is used to communicate that the authorization url is received for the recurring contribution
• recurring_contribution_resumed : This message type is used to communicate resuming of recurring contribution requests
• recurring_contribution_finished : This message type is used to communicate completion of recurring contribution requests
• recurring_contribution_updated : This message type is used to communicate updates (mandate transferr, mandate replacement) of recurring contribution requests
• HMRC_LISA_investor_creation_failed : This message type is used to communicate rejection of HMRC LISA investor creation requests
• HMRC_LISA_account_creation_failed : This message type is used to communicate rejection of HMRC LISA investor account creation requests
• HMRC_LISA_account_creation_successful : This message type is used to communicate completion of HMRC LISA investor and account creation requests

Recurring contribution activation message

Payload

Name	Type	Description	Accepted values
type Required	string		recurring_contribution_activated
ch Required	string		notifications
payload.status Required	string	Status of the recurring contribution
payload.contribution_name Required	string	User given identifier for the contribution
payload.pot_id Required	string	Pot ID of investor to direct the payment
payload.investor_id Required	string	Investor ID of the investor making the contribution
payload.amount Required	string	Amount as a numeral string with two decimal points
payload.sub_transaction_type Required	string	Sub transaction type for recurring contribution	Regular contribution, Regular contribution - non relievable, Regular contribution - Employer
payload.currency Required	string	Currency configured for the pot
payload.payment_type Required	string	Type of payment
payload.service_provider Required	string	Service provider managing the recurring payment subscription
payload.purpose Required	string	Purpose of the recurring contribution	cash, invest
payload.source_id	string	Only for payments intents for employer contributions made towards SIPP Accumulation Products
payload.payment_schedule Required	object	Parameters based on payment schedules
payload.payment_schedule.interval_unit Required	string	Repeating interval unit of recurring payment	monthly
payload.payment_schedule.interval Required	number	Repeating interval of recurring payment
payload.payment_schedule.date	number	Date the payment is expected to be triggered if frequency is monthly
payload.payment_schedule.start_date Required	string	Date to initiate the recurring payments
payload.payment_schedule.end_date	string	Date to conclude the recurring payments, if count is not provided
payload.payment_schedule.count	number	No of recurring payments to trigger before concluding the payments, if an end date is not provided
payload.contribution_id Required	string	System generated unique ID
payload.service_provider_params Required	object	Parameters based on service provider
payload.service_provider_params.status Required	string	Status transitions depend on the service provider
payload.service_provider_params.reason Required	string	Reason for disabling/cancelling the contribution

Examples

{
    "type": "recurring_contribution_activated",
    "ch": "notifications",
    "payload": {
        "status": "Active",
        "contribution_name": "GIA contribution-1",
        "pot_id": "pot-XWL3805770",
        "investor_id": "inv-QRY29279",
        "amount": "1000060.12",
        "sub_transaction_type": "Regular contribution",
        "currency": "GBP",
        "payment_type": "direct_debit",
        "service_provider": "gocardless",
        "purpose": "cash",
        "payment_schedule": {
            "interval_unit": "monthly",
            "interval": 7,
            "date": 1,
            "start_date": "2024-04-02T00:00:00.000Z",
            "end_date": "2024-04-03T00:00:00.000Z"
        },
        "contribution_id": "RCB-GC-JSJ6709",
        "service_provider_params": {
            "status": "Subscription created",
            "authorization_reference" : "EV0159P7DZB2P6",
            "contribution_reference" : "BRQ00030E3DXA4P",
            "request_id" : "BRF00014ZXYN5V4F05M90GZEQCARE84K",
            "authorization_url": "https://authexample.gocardless-sandbox.com"
        }
    },
    "id": "952c7d0a-ecc6-4538-86f4-ad021f6855d0",
    "ts": 1683086449658,
    "resend": true
}

Recurring contribution cancellation message

Payload

Name	Type	Description	Accepted values
type Required	string		recurring_contribution_cancelled
ch Required	string		notifications
payload.status Required	string	Status of the recurring contribution
payload.contribution_name Required	string	User given identifier for the contribution
payload.pot_id Required	string	Pot ID of investor to direct the payment
payload.investor_id Required	string	Investor ID of the investor making the contribution
payload.amount Required	string	Amount as a numeral string with two decimal points
payload.sub_transaction_type Required	string	Sub transaction type for recurring contribution	Regular contribution, Regular contribution - non relievable, Regular contribution - Employer
payload.currency Required	string	Currency configured for the pot
payload.payment_type Required	string	Type of payment
payload.service_provider Required	string	Service provider managing the recurring payment subscription
payload.purpose Required	string	Purpose of the recurring contribution	cash, invest
payload.source_id	string	Only for payments intents for employer contributions made towards SIPP Accumulation Products
payload.payment_schedule Required	object	Parameters based on payment schedules
payload.payment_schedule.interval_unit Required	string	Repeating interval unit of recurring payment	monthly
payload.payment_schedule.interval Required	number	Repeating interval of recurring payment
payload.payment_schedule.date	number	Date the payment is expected to be triggered if frequency is monthly
payload.payment_schedule.start_date Required	string	Date to initiate the recurring payments
payload.payment_schedule.end_date	string	Date to conclude the recurring payments, if count is not provided
payload.payment_schedule.count	number	No of recurring payments to trigger before concluding the payments, if an end date is not provided
payload.contribution_id Required	string	System generated unique ID
payload.service_provider_params Required	object	Parameters based on service provider
payload.service_provider_params.status Required	string	Status transitions depend on the service provider
payload.service_provider_params.reason Required	string	Reason for disabling/cancelling the contribution

Examples

{
    "type": "recurring_contribution_cancelled",
    "ch": "notifications",
    "payload": {
        "status": "Cancelled",
        "contribution_name": "GIA contribution-1",
        "pot_id": "pot-XWL3805770",
        "investor_id": "inv-QRY29279",
        "amount": "1000060.12",
        "sub_transaction_type": "Regular contribution",
        "currency": "GBP",
        "payment_type": "direct_debit",
        "service_provider": "gocardless",
        "purpose": "cash",
        "payment_schedule": {
            "interval_unit": "monthly",
            "interval": 7,
            "date": 1,
            "start_date": "2024-04-02T00:00:00.000Z",
            "end_date": "2024-04-03T00:00:00.000Z"
        },
        "contribution_id": "RCB-GC-JSJ6709",
        "service_provider_params": {
            "status": "Subscription cancelled",
            "authorization_reference" : "EV0159P7DZB2P6",
            "contribution_reference" : "BRQ00030E3DXA4P",
            "request_id" : "BRF00014ZXYN5V4F05M90GZEQCARE84K",
            "authorization_url": "https://authexample.gocardless-sandbox.com",
            "reason" : "The mandate for this subscription was cancelled at a bank branch."
        }
    },
    "id": "952c7d0a-ecc6-4538-86f4-ad021f6855d0",
    "ts": 1683086449658,
    "resend": true
}

Recurring contribution rejection message

Payload

Name	Type	Description	Accepted values
type Required	string		recurring_contribution_rejected
ch Required	string		notifications
payload.status Required	string	Status of the recurring contribution
payload.contribution_name Required	string	User given identifier for the contribution
payload.pot_id Required	string	Pot ID of investor to direct the payment
payload.investor_id Required	string	Investor ID of the investor making the contribution
payload.amount Required	string	Amount as a numeral string with two decimal points
payload.sub_transaction_type Required	string	Sub transaction type for recurring contribution	Regular contribution, Regular contribution - non relievable, Regular contribution - Employer
payload.currency Required	string	Currency configured for the pot
payload.payment_type Required	string	Type of payment
payload.service_provider Required	string	Service provider managing the recurring payment subscription
payload.purpose Required	string	Purpose of the recurring contribution	cash, invest
payload.source_id	string	Only for payments intents for employer contributions made towards SIPP Accumulation Products
payload.payment_schedule Required	object	Parameters based on payment schedules
payload.payment_schedule.interval_unit Required	string	Repeating interval unit of recurring payment	monthly
payload.payment_schedule.interval Required	number	Repeating interval of recurring payment
payload.payment_schedule.date	number	Date the payment is expected to be triggered if frequency is monthly
payload.payment_schedule.start_date Required	string	Date to initiate the recurring payments
payload.payment_schedule.end_date	string	Date to conclude the recurring payments, if count is not provided
payload.payment_schedule.count	number	No of recurring payments to trigger before concluding the payments, if an end date is not provided
payload.contribution_id Required	string	System generated unique ID
payload.service_provider_params Required	object	Parameters based on service provider
payload.service_provider_params.status Required	string	Status transitions depend on the service provider
payload.service_provider_params.reason Required	string	Reason for disabling/cancelling the contribution

Examples

{
    "type": "recurring_contribution_rejected",
    "ch": "notifications",
    "payload": {
        "status": "Rejected",
        "contribution_name": "GIA contribution-1",
        "pot_id": "pot-XWL3805770",
        "investor_id": "inv-QRY29279",
        "amount": "1000060.12",
        "sub_transaction_type": "Regular contribution",
        "currency": "GBP",
        "payment_type": "direct_debit",
        "service_provider": "gocardless",
        "purpose": "cash",
        "payment_schedule": {
            "interval_unit": "monthly",
            "interval": 7,
            "date": 1,
            "start_date": "2024-04-02T00:00:00.000Z",
            "end_date": "2024-04-03T00:00:00.000Z"
        },
        "contribution_id": "RCB-GC-JSJ6709",
        "service_provider_params": {
            "status": "Pending service provider setup",
            "reason": "One of your parameters was incorrectly typed"
        }
    },
    "id": "952c7d0a-ecc6-4538-86f4-ad021f6855d0",
    "ts": 1683086449658,
    "resend": true
}

Recurring contribution authorization url received message

Payload

Name	Type	Description	Accepted values
type Required	string		recurring_contribution_authorization_url_received
ch Required	string		notifications
payload.status Required	string	Status of the recurring contribution
payload.contribution_name Required	string	User given identifier for the contribution
payload.pot_id Required	string	Pot ID of investor to direct the payment
payload.investor_id Required	string	Investor ID of the investor making the contribution
payload.amount Required	string	Amount as a numeral string with two decimal points
payload.sub_transaction_type Required	string	Sub transaction type for recurring contribution	Regular contribution, Regular contribution - non relievable, Regular contribution - Employer
payload.currency Required	string	Currency configured for the pot
payload.payment_type Required	string	Type of payment
payload.service_provider Required	string	Service provider managing the recurring payment subscription
payload.purpose Required	string	Purpose of the recurring contribution	cash, invest
payload.source_id	string	Only for payments intents for employer contributions made towards SIPP Accumulation Products
payload.payment_schedule Required	object	Parameters based on payment schedules
payload.payment_schedule.interval_unit Required	string	Repeating interval unit of recurring payment	monthly
payload.payment_schedule.interval Required	number	Repeating interval of recurring payment
payload.payment_schedule.date	number	Date the payment is expected to be triggered if frequency is monthly
payload.payment_schedule.start_date Required	string	Date to initiate the recurring payments
payload.payment_schedule.end_date	string	Date to conclude the recurring payments, if count is not provided
payload.payment_schedule.count	number	No of recurring payments to trigger before concluding the payments, if an end date is not provided
payload.contribution_id Required	string	System generated unique ID
payload.service_provider_params Required	object	Parameters based on service provider
payload.service_provider_params.status Required	string	Status transitions depend on the service provider
payload.service_provider_params.request_id Required	string	Request ID used to create a contribution with the service provider
payload.service_provider_params.authorization_url Required	string	Authorization URL sent by service provider to setup customer reference data and bank account information

Examples

{
    "type": "recurring_contribution_rejected",
    "ch": "notifications",
    "payload": {
        "status": "Pending",
        "contribution_name": "Sanjali SIPP contribution",
        "pot_id": "pot-XWL3805775",
        "investor_id": "inv-NNO44399",
        "amount": "1000",
        "sub_transaction_type": "Regular contribution",
        "currency": "GBP",
        "payment_type": "direct_debit",
        "service_provider": "gocardless",
        "purpose": "cash",
        "payment_schedule": {
            "interval_unit": "monthly",
            "interval": 1,
            "start_date": "Thu Jun 01 2023 00:00:00 GMT+0000 (Coordinated Universal Time)",
            "date": 1,
            "count": 10
        },
        "financial_product_id": "sipp_accumulation",
        "contribution_id": "RCB-GC-JDJ4807",
        "service_provider_params": {
            "status": "Pending service provider setup",
            "request_id": "BRQ0003R0RBM2BK",
            "authorization_url": "https://pay-sandbox.gocardless.com/billing/static/flow?id=BRF0001BM491H7NWGZ6W2Z5NMVV7GP4T"
        }
    },
    "id": "852c7d0a-ecc6-4538-86f4-ad021f6855k0",
    "ts": 1684086449658,
    "resend": true
}

Recurring contribution resume message

Payload

Name	Type	Description	Accepted values
type Required	string		recurring_contribution_resumed
ch Required	string		notifications
payload.status Required	string	Status of the recurring contribution
payload.contribution_name Required	string	User given identifier for the contribution
payload.pot_id Required	string	Pot ID of investor to direct the payment
payload.investor_id Required	string	Investor ID of the investor making the contribution
payload.amount Required	string	Amount as a numeral string with two decimal points
payload.sub_transaction_type Required	string	Sub transaction type for recurring contribution	Regular contribution, Regular contribution - non relievable, Regular contribution - Employer
payload.currency Required	string	Currency configured for the pot
payload.payment_type Required	string	Type of payment
payload.service_provider Required	string	Service provider managing the recurring payment subscription
payload.purpose Required	string	Purpose of the recurring contribution	cash, invest
payload.source_id	string	Only for payments intents for employer contributions made towards SIPP Accumulation Products
payload.payment_schedule Required	object	Parameters based on payment schedules
payload.payment_schedule.interval_unit Required	string	Repeating interval unit of recurring payment	monthly
payload.payment_schedule.interval Required	number	Repeating interval of recurring payment
payload.payment_schedule.date	number	Date the payment is expected to be triggered if frequency is monthly
payload.payment_schedule.start_date Required	string	Date to initiate the recurring payments
payload.payment_schedule.end_date	string	Date to conclude the recurring payments, if count is not provided
payload.payment_schedule.count	number	No of recurring payments to trigger before concluding the payments, if an end date is not provided
payload.contribution_id Required	string	System generated unique ID
payload.service_provider_params Required	object	Parameters based on service provider
payload.service_provider_params.status Required	string	Status transitions depend on the service provider
payload.service_provider_params.reason Required	string	Reason for disabling/cancelling the contribution

Examples

{
    "type": "recurring_contribution_resumed",
    "ch": "notifications",
    "payload": {
        "status": "Active",
        "contribution_name": "GIA contribution-1",
        "pot_id": "pot-XWL3805770",
        "investor_id": "inv-QRY29279",
        "amount": "1000060.12",
        "sub_transaction_type": "Regular contribution",
        "currency": "GBP",
        "payment_type": "direct_debit",
        "service_provider": "gocardless",
        "purpose": "cash",
        "payment_schedule": {
            "interval_unit": "monthly",
            "interval": 7,
            "date": 1,
            "start_date": "2024-04-02T00:00:00.000Z",
            "end_date": "2024-04-03T00:00:00.000Z"
        },
        "contribution_id": "RCB-GC-JSJ6709",
        "service_provider_params": {
            "status": "Subscription resumed",
            "authorization_reference" : "EV0159P7DZB2P6",
            "contribution_reference" : "BRQ00030E3DXA4P",
            "request_id" : "BRF00014ZXYN5V4F05M90GZEQCARE84K",
            "authorization_url": "https://authexample.gocardless-sandbox.com"
        }
    },
    "id": "952c7d0a-ecc6-4538-86f4-ad021f6855d0",
    "ts": 1683086449658,
    "resend": true
}

Recurring contribution completion message

Payload

Name	Type	Description	Accepted values
type Required	string		recurring_contribution_finished
ch Required	string		notifications
payload.status Required	string	Status of the recurring contribution
payload.contribution_name Required	string	User given identifier for the contribution
payload.pot_id Required	string	Pot ID of investor to direct the payment
payload.investor_id Required	string	Investor ID of the investor making the contribution
payload.amount Required	string	Amount as a numeral string with two decimal points
payload.sub_transaction_type Required	string	Sub transaction type for recurring contribution	Regular contribution, Regular contribution - non relievable, Regular contribution - Employer
payload.currency Required	string	Currency configured for the pot
payload.payment_type Required	string	Type of payment
payload.service_provider Required	string	Service provider managing the recurring payment subscription
payload.purpose Required	string	Purpose of the recurring contribution	cash, invest
payload.source_id	string	Only for payments intents for employer contributions made towards SIPP Accumulation Products
payload.payment_schedule Required	object	Parameters based on payment schedules
payload.payment_schedule.interval_unit Required	string	Repeating interval unit of recurring payment	monthly
payload.payment_schedule.interval Required	number	Repeating interval of recurring payment
payload.payment_schedule.date	number	Date the payment is expected to be triggered if frequency is monthly
payload.payment_schedule.start_date Required	string	Date to initiate the recurring payments
payload.payment_schedule.end_date	string	Date to conclude the recurring payments, if count is not provided
payload.payment_schedule.count	number	No of recurring payments to trigger before concluding the payments, if an end date is not provided
payload.contribution_id Required	string	System generated unique ID
payload.service_provider_params Required	object	Parameters based on service provider
payload.service_provider_params.status Required	string	Status transitions depend on the service provider
payload.service_provider_params.reason Required	string	Reason for disabling/cancelling the contribution

Examples

{
    "type": "recurring_contribution_finished",
    "ch": "notifications",
    "payload": {
        "status": "Finished",
        "contribution_name": "GIA contribution-1",
        "pot_id": "pot-XWL3805770",
        "investor_id": "inv-QRY29279",
        "amount": "1000060.12",
        "sub_transaction_type": "Regular contribution",
        "currency": "GBP",
        "payment_type": "direct_debit",
        "service_provider": "gocardless",
        "purpose": "cash",
        "payment_schedule": {
            "interval_unit": "monthly",
            "interval": 7,
            "date": 1,
            "start_date": "2024-04-02T00:00:00.000Z",
            "end_date": "2024-04-03T00:00:00.000Z"
        },
        "contribution_id": "RCB-GC-JSJ6709",
        "service_provider_params": {
            "status": "Subscription finished",
            "authorization_reference" : "EV0159P7DZB2P6",
            "contribution_reference" : "BRQ00030E3DXA4P",
            "request_id" : "BRF00014ZXYN5V4F05M90GZEQCARE84K",
            "authorization_url": "https://authexample.gocardless-sandbox.com",
            "reason" : "The subscription has finished."
        }
    },
    "id": "952c7d0a-ecc6-4538-86f4-ad021f6855d0",
    "ts": 1683086449658,
    "resend": true
}

Recurring contribution update message

Payload

Name	Type	Description	Accepted values
type Required	string		recurring_contribution_updated
ch Required	string		notifications
payload.status Required	string	Status of the recurring contribution
payload.contribution_name Required	string	User given identifier for the contribution
payload.pot_id Required	string	Pot ID of investor to direct the payment
payload.investor_id Required	string	Investor ID of the investor making the contribution
payload.amount Required	string	Amount as a numeral string with two decimal points
payload.sub_transaction_type Required	string	Sub transaction type for recurring contribution	Regular contribution, Regular contribution - non relievable, Regular contribution - Employer
payload.currency Required	string	Currency configured for the pot
payload.payment_type Required	string	Type of payment
payload.service_provider Required	string	Service provider managing the recurring payment subscription
payload.purpose Required	string	Purpose of the recurring contribution	cash, invest
payload.source_id	string	Only for payments intents for employer contributions made towards SIPP Accumulation Products
payload.payment_schedule Required	object	Parameters based on payment schedules
payload.payment_schedule.interval_unit Required	string	Repeating interval unit of recurring payment	monthly
payload.payment_schedule.interval Required	number	Repeating interval of recurring payment
payload.payment_schedule.date	number	Date the payment is expected to be triggered if frequency is monthly
payload.payment_schedule.start_date Required	string	Date to initiate the recurring payments
payload.payment_schedule.end_date	string	Date to conclude the recurring payments, if count is not provided
payload.payment_schedule.count	number	No of recurring payments to trigger before concluding the payments, if an end date is not provided
payload.contribution_id Required	string	System generated unique ID
payload.service_provider_params Required	object	Parameters based on service provider
payload.service_provider_params.status Required	string	Status transitions depend on the service provider
payload.service_provider_params.reason Required	string	Reason for disabling/cancelling the contribution

Examples

{
    "type": "recurring_contribution_updated",
    "ch": "notifications",
    "payload": {
        "status": "Active",
        "contribution_name": "GIA contribution-1",
        "pot_id": "pot-XWL3805770",
        "investor_id": "inv-QRY29279",
        "amount": "1000060.12",
        "sub_transaction_type": "Regular contribution",
        "currency": "GBP",
        "payment_type": "direct_debit",
        "service_provider": "gocardless",
        "purpose": "cash",
        "payment_schedule": {
            "interval_unit": "monthly",
            "interval": 7,
            "date": 1,
            "start_date": "2024-04-02T00:00:00.000Z",
            "end_date": "2024-04-03T00:00:00.000Z"
        },
        "contribution_id": "RCB-GC-JSJ6709",
        "service_provider_params": {
            "status": "Mandate replaced",
            "authorization_reference" : "EV1059P8HGJ6P6",
            "contribution_reference" : "BRQ00030E3DXA4P",
            "request_id" : "BRF00014ZXYN5V4F05M90GZEQCARE84K",
            "authorization_url": "https://authexample.gocardless-sandbox.com"
        }
    },
    "id": "952c7d0a-ecc6-4538-86f4-ad021f6855d0",
    "ts": 1683086449658,
    "resend": true
}

HMRC LISA investor creation failed message

Payload

Name	Type	Description	Accepted values
type Required	string		HMRC_LISA_investor_creation_failed
ch Required	string		notifications
payload.investor_id Required	string	Investor ID of the investor account
payload.account_id Required	string	Account ID of the investor account
payload.hmrc_data Required	object	HMRC related data
payload.hmrc_data.status Required	string	Indicate the status of the LISA investor and investor account creation with HMRC
payload.hmrc_data.reason Required	string	Reason for failure

Examples

{
    "type": "HMRC_LISA_investor_creation_failed",
    "ch": "notifications",
    "payload": {
        "investor_id": "inv-QRY29279",
        "account_id": "LISAC1699158978930",
        "hmrc_data": {
            "status": "hmrc_investor_creation_failed",
            "reason": "The HMRC request contains invalid or missing data"
        }
    },
    "id": "952c7d0a-ecc6-4538-86f4-ad021f6855d0",
    "ts": 1683086449658,
    "resend": true
}

HMRC LISA account creation failed message

Payload

Name	Type	Description	Accepted values
type Required	string		HMRC_LISA_account_creation_failed
ch Required	string		notifications
payload.investor_id Required	string	Investor ID of the investor account
payload.account_id Required	string	Account ID of the investor account
payload.hmrc_data Required	object	HMRC related data
payload.hmrc_data.status Required	string	Indicate the status of the LISA investor and investor account creation with HMRC
payload.hmrc_data.reason Required	string	Reason for failure

Examples

{
    "type": "HMRC_LISA_account_creation_failed",
    "ch": "notifications",
    "payload": {
        "investor_id": "inv-QRY29279",
        "account_id": "LISAC1699158978930",
        "hmrc_data": {
            "status": "hmrc_account_creation_failed",
            "reason": "The HMRC request contains invalid or missing data"
        }
    },
    "id": "952c7d0a-ecc6-4538-86f4-ad021f6855d0",
    "ts": 1683086449658,
    "resend": true
}

HMRC LISA account creation successful message

Payload

Name	Type	Description	Accepted values
type Required	string		HMRC_LISA_account_creation_successful
ch Required	string		notifications
payload.investor_id Required	string	Investor ID of the investor account
payload.account_id Required	string	Account ID of the investor account
payload.hmrc_data Required	object	HMRC related data
payload.hmrc_data.status Required	string	Indicate the status of the LISA investor and investor account creation with HMRC
payload.hmrc_data.lisa_investor_reference Required	object	HMRC LISA investor reference

Examples

{
    "type": "HMRC_LISA_account_creation_successful",
    "ch": "notifications",
    "payload": {
        "investor_id": "inv-QRY29279",
        "account_id": "LISAC1699158978930",
        "hmrc_data": {
            "status": "hmrc_account_creation_successful",
            "lisa_investor_reference": "5305636328" 
        }
    },
    "id": "952c7d0a-ecc6-4538-86f4-ad021f6855d0",
    "ts": 1683086449658,
    "resend": true
}

Test methods are used for easier testing of connectivity, keys and tokens. Since they are not tied to a speific functionality you can use them freely

The Investor endpoint allows you to create investors, update investors and retrieve investor records in bulk or individually. If a KYC/AML service has been set-up through the system (e.g. Onfido), then the investor will be verified using this service.

When retrieving the investor, the following fields will provide information regarding the investor’s status that can be used for deciding on what subsequent investor action must be permitted.

• dealing_status: Normally set to Active once KYC/AML passes, however may be independently set by administrators if required.

• kyc_aml_status - the status of the KYC/AML check.

• Status - ultimate status of the investor derived from dealing_status and kcy_aml_status.

If the system is not set-up to manage the KYC/AML service then the wealth manager must specify the kyc_aml_status and dealing_status on investor creation and update. The status of the investor will be consider active only when the kyc_aml_status : "clear" and dealing_status : "active"