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:

https://my.callback.com/txpush

The API will make the following request:


GET
https://my.callback.com/txpush?txpush_verification_code=CODE

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 NameDescription
classaccount or transaction
typecreated (transaction events only) or modified or deleted
recordsA list of one or more customer account records or transaction records

Example Account Event Message:

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:

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 NameDescription
eventRoot element
classaccount or transaction
typecreated (transaction events only) or modified or deleted
recordsA list of one or more customer account records or transaction records

Example Account Event Message:

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:

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>

Example of Signing Key Validation

If the following notification message is posted to the listener app:

Example Transaction Event Message:
 POST https://example.domain.com/txpush/listener

Content-Type: application/xml

Host: api.finicity.com

x-txpush-signature: TGE1ZC9Mb3VObGZMYWd1TWc1N3BVNHNMdUxzams5Y1VrNGVQYUd0UE1lMD0=

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<event>

  <type>modified</type>

  <class>account</class>

  <records>

    <account>

      <id>2055</id>

      ...

    </account>

  </records>

</event>

…and the signingKey for this subscription is:

1234567890

…then the signature validation sequence is this:

StepResult
1. Create a new empty string, known here as the signing string. Signing string:
2. Append the text content-type. Signing string:
content-type
3. Append the value of the Content-Type header from the HTTP request (all lower-case). Signing string:
content-typeapplication/xml
4. Append the text host.Signing string:
content-typeapplication/xmlhost
5. Append the value of the hostheader from the HTTP request (all lower-case).Signing string:
content-typeapplication/xmlhostapi.finicity.com
6. Base64 encode the XML document (the request body).Base64 result:
PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiIHN0YW5kYWxvbmU9In

llcyI/Pgo8ZXZlbnQ+CiAgPGNsYXNzPmFjY291bnQ8L2NsYXNzPgogIDx0eXBl

ZGlmaWVkPC90eXBlPgogIDxyZWNvcmRzPgogICAgPGFjY291bnQ+CiAgICAgIDxp

ZD4yMDU1PC9pZD4KICAgICAgLi4uICAgIDwvYWNjb3VudD4KICA8L3JlY29yZHM

+CjwvZXZlbnQ+

7. Append the resulting Base64-encoded string to the signing string.Signing string:
content-typeapplication/xmlhostapi.finicity.comPD94bWwgdmVyc2lvbj0

iMS4wIiBlbmNvZGluZz0iVVRGLTgiIHN0YW5kYWxvbmU9InllcyI/Pgo8ZXZl

bnQ+CiAgPGNsYXNzPmFjY291bnQ8L2NsYXNzPgogIDx0eXBlPm1vZGlmaWVkPC

90eXBlPgogIDxyZWNvcmRzPgogICAgPGFjY291bnQ+CiAgICAgIDxpZD4yMDU1

8. Using HMAC SHA256, create the signature. For this algorithm, the key is thesigningKeyreturned from Enable TxPUSH Notifications , and the value is the signing string.HMAC value:
La5d/LouNlfLaguMg57pU4sLuLsjk9cUk4ePaGtPMe0=
9. Base64 encode the resulting HMAC value.Base64-encoded signature:
TGE1ZC9Mb3VObGZMYWd1TWc1N3BVNHNMdUxzams5Y1VrNGVQYUd0UE1lMD0=
10. UrlEncode the signature value.Final signature:
TGE1ZC9Mb3VObGZMYWd1TWc1N3BVNHNMdUxzams5Y1VrNGVQYUd0UE1lMD0%3D
11. Compare the result to the value of the request’s HTTP Header x-txpush-signature. If the values are the same, the notification is valid. If not, ignore the notification.Comparison result:
true