TxPUSH Listener Service
This page explains how to implement the TxPUSH Listener service required to receive notifications whenever a new transaction appears on an account. See TxPUSH Services for information about enabling, disabling, or testing TxPUSH notifications.
In order to receive TxPUSH events, an app must define a public RESTful web service that is accessible from the Finicity platform.
Notifications are sent as HTTP POST requests, to the listener URL that was registered in a call to Enable TxPUSH Notifications. If this call includes the header Accept: application/json the notifications will be sent in JSON format; otherwise they will be sent as XML.
While an app is on the Test Drive plan, the TxPUSH Listener service can receive events from testing accounts (accounts on institution 101732) through the standard protocol (http). When an app moves off the Test Drive plan, the TxPUSH Listener service must be configured on a secure protocol (https). In other words, events from testing accounts can be received over http, but events from real-world accounts can only be received over https. This arrangement is to facilitate testing, by requiring SSL configuration only when the app moves into Production.
When an event notification is received, the TxPUSH Listener service must return HTTP 200 (OK) to acknowledge the message. If an event is not acknowledged, the Finicity platform will resend the notice periodically for up to six hours. If the event is never acknowledged within six hours, the notification is cancelled. The transaction itself remains in the Finicity system, and can be retrieved through any of the Transaction services. TxPUSH notifications are sent from IP address 68.142.128.67. To ensure the arrival of notifications, please whitelist this address for inbound traffic.
TxPUSH Callback URL
Lastly, to enable TxPUSH notifications, the client’s TxPUSH Listener will need to be verified.
The API will verify the callback URL by sending a GET request with a query parameter called txpush_verification_code to the callback URL provided by the client in the subscription. The client’s callback URL will be accepted if the response returns the verification CODE value in plain text.
For example, if a client app enables TxPUSH notifications for an account using the callback:
The API will make the following request:
The app’s TxPUSH Listener should respond to that GET request with an HTTP code 200, header Content-Type: text/plain, and a response body containing the verification code in plain text. If the API is not able to connect to the listener, or if the listener does not return the code as specified above, the subscription will be rejected. The resulting response from the API will provide information to help troubleshoot the problem.
Note that HTTP and HTTPS connections are only allowed on the standard ports 80 (HTTP) and 443 (HTTPS). The use of other ports will result with the call failing.
After the listener verifies the connection as described above, the API will proceed to enable TxPUSH notifications for the indicated account.
Event Notification Message
JSON Implementation
The following fields are in an event notification message posted to the callback URL:
| Field Name | Description |
|---|---|
| class | account or transaction |
| type | created (transaction events only) or modified or deleted |
| records | A list of one or more customer account records or transaction records |
Example Account Event Message:
{
"event":{
"class": "account",
"type": "modified",
"records": [
{
"id": "2055",
"number": ">XXXX-XXXXXX-32765",
"name": "Checking",
"balance": 964.23,
"type": "checking",
"aggregationStatusCode": 0,
"status": "active",
"customerId": "41442",
"institutionId": "101732",
"balanceDate": 1444768982,
"aggregationSuccessDate": 1444768982,
"aggregationAttemptDate": 1444768982,
"createdDate": 1422395818,
"lastUpdatedDate": 1444768982
} ]
}
} Example Transaction Event Message:
{
"event": {
"class": "transaction",
"type": "created",
"records": [
{
"amount": -16.52,
"bonusAmount": 0.0,
"accountId": "2055",
"customerId": "41442",
"createdDate": 1422272248,
"description": "TWITTER.COM 234000003654262790",
"escrowAmount": 0.0,
"feeAmount": 0.0,
"id": "84246",
"interestAmount": 0.0,
"postedDate": 1421996400
"principalAmount": 0.0,
"status": "active",
"transactionDate": "1421996400",
"unitQuantity": "0.0",
"unitValue": "0.0"
},
{
"amount": -124.99,
"bonusAmount": 0.0,
"accountId": "2055",
"customerId": "41442",
"createdDate": 1422272248,
"description": "CLICKDESK CA",
"escrowAmount": 0.0,
"feeAmount": 0.0,
"id": "84293",
"interestAmount": 0.0,
"postedDate": 1422082800,
"principalAmount": 0.0,
"status": "active",
"transactionDate": 1422082800,
"unitQuantity": 0.0,
"unitValue": 0.0
} ]
}
} JSON Implementation
The following fields are in an event notification message posted to the callback URL:
| Field Name | Description |
|---|---|
| event | Root element |
| class | account or transaction |
| type | created (transaction events only) or modified or deleted |
| records | A list of one or more customer account records or transaction records |
Example Account Event Message:
<event>
<class>account</class>
<type>modified</type>
<records>
<account>
<id>2055</id>
<number>XXXX-XXXXXX-32765</number>
<name>Checking</name>
<balance>964.23</balance>
<type>checking</type>
<aggregationStatusCode>0</aggregationStatusCode>
<status>active</status>
<customerId>41442</customerId>
<institutionId>101732</institutionId>
<balanceDate>1444768982</balanceDate>
<aggregationSuccessDate>1444768982</aggregationSuccessDate>
<aggregationAttemptDate>1444768982</aggregationAttemptDate>
<createdDate>1422395818</createdDate>
<lastUpdatedDate>1444768982</lastUpdatedDate>
</account>
</records>
</event> Example Transaction Event Message:
<event>
<class>transaction</class>
<type>created</type>
<records>
<transaction>
<amount>-16.52</amount>
<bonusAmount>0.0</bonusAmount>
<accountId>2055</accountId>
<customerId>41442</customerId>
<createdDate>1422272248</createdDate>
<description>TWITTER.COM 234000003654262790</description>
<escrowAmount>0.0</escrowAmount>
<feeAmount>0.0</feeAmount>
<id>84246</id>
<interestAmount>0.0</interestAmount>
<postedDate>1421996400</postedDate>
<principalAmount>0.0</principalAmount>
<status>active</status>
<transactionDate>1421996400</transactionDate>
<unitQuantity>0.0</unitQuantity>
<unitValue>0.0</unitValue>
</transaction>
<transaction>
<amount>-124.99</amount>
<bonusAmount>0.0</bonusAmount>
<accountId>2055</accountId>
<customerId>41442</customerId>
<createdDate>1422272248</createdDate>
<description>CLICKDESK CA</description>
<escrowAmount>0.0</escrowAmount>
<feeAmount>0.0</feeAmount>
<id>84293</id>
<interestAmount>0.0</interestAmount>
<postedDate>1422082800</postedDate>
<principalAmount>0.0</principalAmount>
<status>active</status>
<transactionDate>1422082800</transactionDate>
<unitQuantity>0.0</unitQuantity>
<unitValue>0.0</unitValue>
</transaction>
</records>
</event>