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.

TxPUSH Listener Service

In order to receive TxPUSH events, an app must define a public RESTful web service that is accessible from the Finicity platform.

Before TxPUSH notifications can be received, the listener's domain must be approved by Finicity for receiving notifications. To obtain this approval, send an email to support@finicity.com.

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.

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 currentState or modified or deleted 
records A list of one or more customer account records or transaction records

Example Account Event Message:

{
"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",
subaccount": {
"name": "Ron Smith",
"number": "XXXX-XXXXXX-90210"
},
"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",
"subaccount": {
"name": "J Green",
"number": "XXXX-XXXXXX-23687"
},
"transactionDate": 1422082800,
"unitQuantity": 0.0,
"unitValue": 0.0
} ]
}

XML Implementation

The following fields are in an event notification message posted to the callback URL:

XML Name Description
event Root element
class account or transaction
type created (transaction events only) or currentState 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>
<subaccount>
<name>Ron Smith</name>
<number>XXXX-XXXXXX-90210</number>
</subaccount>
<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>
<subaccount>
<name>J Green</name>
<number>XXXX-XXXXXX-23687</number>
</subaccount>
<transactionDate>1422082800</transactionDate>
<unitQuantity>0.0</unitQuantity>
<unitValue>0.0</unitValue>
</transaction>
</records>
</event>

Message Signing

All TxPUSH notifications are signed using the signing key associated with the event's subscription. The TxPUSH Listener should verify the signature to ensure that the event has not been spoofed. TLS provides replay protection. The verification process follows these steps:

  1. Create a new empty string, known here as the signing string.
  2. Append the text content-type.
  3. Append the value of the content-type header from the HTTP request (all lower-case).
  4. Append the text host.
  5. Append the value of the host header from the HTTP request (all lower-case).
  6. Base64 encode the request body.
  7. Append the resulting Base64 encoded string to the signing string.
  8. Using HMAC SHA256, create the signature. For this algorithm, the key is the signingKey returned from Enable TxPUSH Notifications , and the value is the signing string.
  9. Base64 encode the resulting HMAC value.
  10. 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.

Example of Signing Key Validation

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

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: 

Step Result
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 host header 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:
PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiIHN0YW5kYWxvbmU9InllcyI/Pgo8ZXZlbnQ+CiAgPGNsYXNzPmFjY291bnQ8L2NsYXNzPgogIDx0eXBlPm1vZGlmaWVkPC90eXBlPgogIDxyZWNvcmRzPgogICAgPGFjY291bnQ+CiAgICAgIDxpZD4yMDU1PC9pZD4KICAgICAgLi4uICAgIDwvYWNjb3VudD4KICA8L3JlY29yZHM+CjwvZXZlbnQ+

7. Append the resulting Base64-encoded string to the signing string.

Signing string:
content-typeapplication/xmlhostapi.finicity.comPD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiIHN0YW5kYWxvbmU9InllcyI/Pgo8ZXZlbnQ+CiAgPGNsYXNzPmFjY291bnQ8L2NsYXNzPgogIDx0eXBlPm1vZGlmaWVkPC90eXBlPgogIDxyZWNvcmRzPgogICAgPGFjY291bnQ+CiAgICAgIDxpZD4yMDU1PC9pZD4KICAgICAgLi4uICAgIDwvYWNjb3VudD4KICA8L3JlY29yZHM+CjwvZXZlbnQ+

8. Using HMAC SHA256, create the signature. For this algorithm, the key is the signingKey returned from Enable TxPUSH Notifications , and the value is the signing string.

HMAC value:
La5d/LouNlfLaguMg57pU4sLuLsjk9cUk4ePaGtPMe0=

9. Base64 encode the resulting HMAC value.

Final signature:
TGE1ZC9Mb3VObGZMYWd1TWc1N3BVNHNMdUxzams5Y1VrNGVQYUd0UE1lMD0=

10. 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 

 

Have more questions? Submit a request

Comments

Powered by Zendesk