TxPUSH Services

TxPUSH services allow an app to register a TxPUSH Listener service to receive notifications whenever a new transaction appears on an account.

See TxPUSH Listener Service for details about implementing the TxPUSH Listener service.

See Active Docs to experiment directly with the API.

Available services:

Subscription Record

The following fields are available in a subscription record:

Field Name Description
id The subscription ID
accountId The account being monitored by this subscription
type account or transaction 
callbackUrl The TxPUSH Listener URL where event notifications will be sent
signingKey A signing key that will be used to validate the signature of events received for this subscription

Enable TxPUSH Notifications
POST /v1/customers/{customerId}/accounts/{accountId}/txpush

Register a client app’s TxPUSH Listener to receive TxPUSH notifications related to the given account.

Each call to this service will return two <subscription> records, one with class account and one with class transaction. Account events are sent when values change in the account's fields (such as balance or interestRate). Transaction events are sent whenever a new transaction is posted for the account. For institutions that do not provide TxPUSH services, notifications are sent as soon as Finicity finds a new transaction or new account data through regular aggregation processes.

Before TxPUSH notifications can be sent, the listener's domain must be approved by Finicity for receiving notifications. To obtain this approval, send an email to support@finicity.com. The listener's URL must be secure (https) for any real-world account.

JSON Implementation

Request Details: 

Parameter Type Description
Finicity-App-Key HTTP header Finicity-App-Key from Developer Portal
Finicity-App-Token HTTP header Token returned from Partner Authentication
Content-Type HTTP header application/json
Accept HTTP header application/json
customerId path

The Finicity ID of the customer who owns the account

accountId path The Finicity ID of the account whose events will be sent to the TxPUSH Listener
callbackUrl JSON Field The TxPUSH Listener URL to receive TxPUSH notifications (must use https protocol for any real-world account)

Success: HTTP 201 (Created)

Example Request:

POST https://api.finicity.com/aggregation/v1/customers/41442/accounts/2055/txpush
{
"callbackUrl": "https://www.mydomain.com/txpush/listener"
}

Using curl:

curl -v -H "Finicity-App-Key:APP_KEY" -H "Finicity-App-Token:ACCESS_TOKEN" -H "Content-Type:application/json" -H "Accept:application/json" -X POST "https://api.finicity.com/aggregation/v1/customers/41442/accounts/2055/txpush" -d '{ "callbackUrl": "https://www.mydomain.com/txpush/listener" }'

Response Details:

XML Name Description
subscription subscription record.

Example Response:

{
"subscriptions": [
{
"id": 7462,
"accountId": 2055,
"type": "account",
"callbackUrl": "https://www.mydomain.com/txpush/listener",
"signingKey": "zg4U0v1IvTzFEHIXzJMxPHnfUwWZAMVpXrUuNuL9IvZI0QzkDdwp39IAKuNOFxOVqCOgHLMS1Zpe4ZL40NX83aJkqI6v0Ez5B7BLBtvr7Ag11kPH3uG1taTeOV0CTyI4LOg7ohSHn0DqaRu2aBq26KI90nYe0CecTCzzhu4yMXL43JV8YfydAexNdkzfg8tY44MlhBPUh2neHW2EFTT2ja4s4Ul10JgID03un8WBSrIm2adHw3QYJB4jk4k1e"
},
{
"id": 7463,
"accountId": 2055,
"type": "transaction",
"callbackUrl": "https://www.mydomain.com/txpush/listener",
"signingKey": "zg4U0v1IvTzFEHIXzJMxPHnfUwWZAMVpXrUuNuL9IvZI0QzkDdwp39IAKuNOFxOVqCOgHLMS1Zp7aZL40NX8ekJkqI6v0Ez5B7BLBtvr7Ag11kPH3uG1taTeOV0CTyI4LOg7ohSHn0DqaRu2aBq26KI90nYe0CecTCzzhu4yMXL43JV8YfydAexNdkzfg8tY44MlhBPUh2neHW2EFTT2ja4s4Ul10JgID03un8WBSrIm2adHw3QYJB6K84k1e"
} ]
}

XML Implementation

Request Details: 

Parameter Type Description
Finicity-App-Key HTTP header Finicity-App-Key from Developer Portal
Finicity-App-Token HTTP header Token returned from Partner Authentication
Content-Type HTTP header application/xml
Accept HTTP header application/xml
customerId path

The Finicity ID of the customer who owns the account

accountId path The Finicity ID of the account whose events will be sent to the TxPUSH Listener
subscription XML element Root element
callbackUrl XML element The TxPUSH Listener URL to receive TxPUSH notifications (must use https protocol for any real-world account)

Success: HTTP 201 (Created)

Example Request:

POST https://api.finicity.com/aggregation/v1/customers/41442/accounts/2055/txpush
<subscription>
<callbackUrl>https://www.mydomain.com/txpush/listener</callbackUrl>
</subscription>

Using curl:

curl -v -H "Finicity-App-Key:APP_KEY" -H "Finicity-App-Token:ACCESS_TOKEN" -H "Content-Type:application/xml" -H "Accept:application/xml" -X POST "https://api.finicity.com/aggregation/v1/customers/41442/accounts/2055/txpush" -d '<subscription> <callbackUrl>https://www.mydomain.com/txpush/listener</callbackUrl> </subscription>'

Response Details:

XML Name Description
subscriptions Root element
subscription subscription record.

Example Response:

<subscriptions>
<subscription>
<id>7462</id>
<accountId>2055</accountId>
<type>account</type>
<callbackUrl>https://www.mydomain.com/txpush/listener</callbackUrl>
<signingKey>zg4U0v1IvTzFEHIXzJMxPHnfUwWZAMVpXrUuNuL9IvZI0QzkDdwp39IAKuNOFxOVqCOgHLMS1Zpe4ZL40NX83aJkqI6v0Ez5B7BLBtvr7Ag11kPH3uG1taTeOV0CTyI4LOg7ohSHn0DqaRu2aBq26KI90nYe0CecTCzzhu4yMXL43JV8YfydAexNdkzfg8tY44MlhBPUh2neHW2EFTT2ja4s4Ul10JgID03un8WBSrIm2adHw3QYJB4jk4k1e</signingKey>
</subscription>
<subscription>
<id>7463</id>
<accountId>2055</accountId>
<type>transaction</type>
<callbackUrl>https://www.mydomain.com/txpush/listener</callbackUrl>
<signingKey>zg4U0v1IvTzFEHIXzJMxPHnfUwWZAMVpXrUuNuL9IvZI0QzkDdwp39IAKuNOFxOVqCOgHLMS1Zp7aZL40NX8ekJkqI6v0Ez5B7BLBtvr7Ag11kPH3uG1taTeOV0CTyI4LOg7ohSHn0DqaRu2aBq26KI90nYe0CecTCzzhu4yMXL43JV8YfydAexNdkzfg8tY44MlhBPUh2neHW2EFTT2ja4s4Ul10JgID03un8WBSrIm2adHw3QYJB6K84k1e</signingKey>
</subscription>
</subscriptions>

Disable TxPUSH Notifications
DELETE /v1/customers/{customerId}/accounts/{accountId}/txpush

Disable all TxPUSH notifications for the indicated account. No more notifications will be sent for account or transaction events.

Request Details: 

Parameter Type Description
Finicity-App-Key HTTP header Finicity-App-Key from Developer Portal
Finicity-App-Token HTTP header Token returned from Partner Authentication
customerId path

The ID of the customer who owns the account

accountId path The Finicity ID of the account whose events will be sent to the TxPUSH Listener

Success: HTTP 204 (No Content)

Example Request:

DELETE https://api.finicity.com/aggregation/v1/customers/41442/accounts/2055/txpush

Using curl:

curl -v -H "Content-Type:application/xml" -H "Finicity-App-Key:APP_KEY" -H "Finicity-App-Token:ACCESS_TOKEN" -X DELETE "https://api.finicity.com/aggregation/v1/customers/41442/accounts/2055/txpush" -d ''

Delete TxPUSH Subscription
DELETE /v1/customers/{customerId}/subscriptions/{subscriptionId}

Delete a specific subscription for a class of events (account or transaction events) related to an account. No more notifications will be sent for these events.

Request Details: 

Parameter Type Description
Finicity-App-Key HTTP header Finicity-App-Key from Developer Portal
Finicity-App-Token HTTP header Token returned from Partner Authentication
customerId path

The ID of the customer who owns the account

subscriptionId path The ID of the specific subscription to be deleted (returned from Enable TxPUSH Notifications

Success: HTTP 204 (No Content)

Example Request:

DELETE https://api.finicity.com/aggregation/v1/customers/41442/subscriptions/76431

Using curl:

curl -v -H "Content-Type:application/xml" -H "Finicity-App-Key:APP_KEY" -H "Finicity-App-Token:ACCESS_TOKEN" -X DELETE "https://api.finicity.com/aggregation/v1/customers/41442/subscriptions/76431" -d ''

Add Transaction for Testing Account
POST /v1/customers/{customerId}/accounts/{accountId}/transactions

Inject a transaction into the transaction list for a testing account. This allows an app to trigger TxPUSH notifications for the account in order to test the app’s TxPUSH Listener service. This causes the platform to send one transaction event and one account event (showing that the account balance has changed). This service is only supported for testing accounts (accounts on institution 101732).

JSON Implementation

Request Details: 

Parameter Type Default Description
Finicity-App-Key HTTP header   Finicity-App-Key from Developer Portal
Finicity-App-Token HTTP header   Token returned from Partner Authentication
Content-Type HTTP header   application/json
Accept HTTP header  

application/json

customerId path  

The ID of the customer who owns the account

accountId path   The Finicity ID of the account whose events will be sent to the TxPUSH Listener
amount JSON field   The amount of the transaction
description JSON field   The description of the transaction
status JSON field active active or pending (optional)
postedDate JSON field Right now An optional timestamp for the transaction's posted date value for this transaction (see Handling Dates and Times)
transactionDate JSON field Right now An optional timestamp for the transaction's posted date value for this transaction (see Handling Dates and Times)

Success: HTTP 201 (Created)

Example Request:

POST https://api.finicity.com/aggregation/v1/customers/41442/accounts/2055/transactions
{
"amount": -4.25,
"description": "Lunch",
"postedDate": 1444253131,
"transactionDate": 1444080324
}

Using curl:

curl -v -H "Finicity-App-Key:APP_KEY" -H "Finicity-App-Token:ACCESS_TOKEN" -H "Content-Type:application/json" -H "Accept:application/json" -X POST "https://api.finicity.com/aggregation/v1/customers/41442/accounts/2055/transactions" -d '{ "amount": 67.89, "description": "Another Description", "postedDate": 1478131200, "transactionDate": 1478131200 }'

Response Details:

Field Name Description
id The ID of the new transaction record
createdDate A timestamp of when the transaction was added (see Handling Dates and Times)

Example Response:

{
"id": 712054,
"createdDate": 1444259433
}

XML Implementation

Request Details: 

Parameter Type Default Description
Finicity-App-Key HTTP header   Finicity-App-Key from Developer Portal
Finicity-App-Token HTTP header   Token returned from Partner Authentication
Content-Type HTTP header   application/xml
Accept HTTP header   application/xml
customerId path  

The ID of the customer who owns the account

accountId path   The Finicity ID of the account whose events will be sent to the TxPUSH Listener
transaction XML element   Root element
amount XML element   The amount of the transaction
description XML element   The description of the transaction
status XML element active active or pending (optional)
postedDate XML element Right now An optional timestamp for the transaction's posted date value for this transaction (see Handling Dates and Times)
transactionDate XML element Right now An optional timestamp for the transaction's posted date value for this transaction (see Handling Dates and Times)

Success: HTTP 201 (Created)

Example Request:

POST https://api.finicity.com/aggregation/v1/customers/41442/accounts/2055/transactions
<transaction>
<amount>-4.25</amount>
<description>Lunch</description>
<postedDate>1444253131</postedDate>
<transactionDate>1444080324</transactionDate>
</transaction>

Using curl:

curl -v -H "Finicity-App-Key:APP_KEY" -H "Finicity-App-Token:ACCESS_TOKEN" -H "Content-Type:application/xml" -H "Accept:application/xml" -X POST "https://api.finicity.com/aggregation/v1/customers/41442/accounts/2055/transactions" -d '<transaction> <amount>-4.25</amount> <description>Lunch</description> <postedDate>1444253131</postedDate> <transactionDate>1444080324</transactionDate> </transaction>'

Response Details:

XML Name Description
transaction Root element
id The ID of the new transaction record
createdDate A timestamp of when the transaction was added (see Handling Dates and Times)

Example Response:

<transaction>
<id>712054</id>
<createdDate>1444259433</createdDate>
</transaction>

 

Have more questions? Submit a request

Comments

Powered by Zendesk