Transactions

A transaction is an individual entry that represents a financial movement within an account. The Transaction resource represents a confirmed financial transaction that were posted to the account, including its source, amount, and direction.

Transactions cannot be created using Unit's API, they are always the result of other activity, in or out of the platform, that resulted in actual movement of funds. For instance, if you originate an ACH Debit payment, a transaction will be created once the payment has been processed and the clearing period has passed. It is for this reason that transactions do not have statuses.

Transactions are final, and cannot be deleted or changed. In order to reverse a transaction (for example, a refund after a card Purchase transaction), a new, opposite, transaction will have to be created (in our example, a Card Reversal transaction).

info

Unit provides a cross-platform suite of flexible and customizable white-label UI components, including an activity component that allows the end customer to see their transactional activity on an account or card level. You may embed the activity component into your app to shorten your time to market and deliver a highly optimized experience to your end customer with minimal engineering investment.

Transaction Types

Unit currently supports the following types of transactions:

Type	Description
Originated ACH	An ACH payment originated from a deposit account.
Received ACH	An ACH payment received by a deposit account.
Returned ACH	An ACH payment returned by the bank.
Returned Received ACH	A received ACH payment that has been returned through Unit.
Dishonored Return ACH	A returned ACH that was dishonored by the receiving bank.
Wire	A wire transaction, either received or sent.
Returned Wire	A returned wire transaction.
Book	A payment between two accounts on the same bank.
Purchase	A purchase via debit card.
ATM	A deposit or a withdrawal of funds from an ATM with a debit card.
Fee	Fees incurred for a transaction.
Fee Reversal	A reversal of a previous fee transaction.
Interest	An Interest payment to a deposit account.
Card Reversal	A reversal of a previous card transaction.
Card Transaction	A transaction that represents various card transactions that are not `Purchase` or `ATM` transactions. Those might be split in the future into different types.
Release	A transaction releasing funds from a batch account.
Adjustment	Manual Adjustment is made in situations where the correction of an amount, or a reverse of a completed transaction is needed.
Dispute	Dispute transaction is created in order to credit or debit a customer for an ongoing card or ACH dispute. For example, when provisional credit is provided, the customer account would be credited using the Dispute Transaction.
Check Deposit	A received check deposit.
Returned Check Deposit	A check deposit returned by the bank.
Payment Canceled	Cancellation of a previously processed ACH payment.
Payment Advance	Payment advance transaction is created in order to `Debit` an org account against a ReceivedPayment that is advanced .
Repaid Payment Advance	Repaid payment advance transaction is created when a ReceivedPayment is `Completed` in order to `Credit` an org account and repay it for a received payment that was advanced.
Chargeback	A transaction that represent a Chargeback.
Reward	A transaction that represent a Reward.
Account Low Balance Closure	Handling of low balance upon account closure.
Negative Balance Coverage	A transaction that occurs when closing an account with negative balance. covering the account negative balance.
Check Payment	A `Debit` transaction that occurs when a Check Payment is processed successfully (`Processed` status).
Returned Check Payment	A `Credit` transaction that occurs when a Check Payment has been returned through Unit (`Returned` status).
Push To Card	A `Debit` transaction that was created from a PushToCard Payment originated from a deposit account.
Push To Card Reversal	A `Credit` transaction that was created in order to reverse a previous Push To Card transaction.
Cash Deposit	A `Credit` transaction that occurs when cash is deposited at a Store Location.

In addition to their own specific fields, all transaction types are guaranteed to contain the following top-level fields:

Field	type	Description
direction	string	The direction in which the funds flow- Debit or Credit.
amount	integer	The amount (cents) of the transaction.
balance	integer	The account balance (cents) after the transaction.
summary	string	Human-friendly summary of the transaction.
createdAt	RFC3339 Date string	The date the transaction was created

note

New transaction types may be added in the future, as we introduce new financial products. To minimize code changes on your side, we recommend using the summary field when displaying transactions to end-customers.

Transaction Summaries

The transaction summary field is used whenever the transaction details are presented. This applies to monthly statements, data exports (e.g. Plaid, Intuit), and the Unit Dashboard. It is recommended that you use that field when displaying transactions within your UI. The table below describes what how the summary field is generated for each of the transaction types.

Transaction type	Summary structure	Example
Originated ACH	<counterparty_name> \| <txn_addenda>	Richard Hendrix \| ACH PYMT
Received ACH	<txn_company_name> \| <txn_description>	Pied Piper INC \| Pied Piper
ReturnedACH	Returned due to: <txn.reason> \| <txn.counterparty_name>	Returned due to: InsufficientFunds \| Richard Hendrix
ReturnedReceivedACH	Returned received ACH transaction #<txn.relatedTransactionId> due to: <tx.reason>	Returned received ACH transaction #1234567 due to: InsufficientFunds
DishonoredACH	Dishonored Return ACH transaction due to: <txn.reason>	Dishonored Return ACH transaction due to: UntimelyReturn
Card Purchase	Purchase from <txn.merchantName> \| address: <txn.merchant_address> \| <txn.cardLast4Digits>	Purchase from 7-ELEVEN, 7-ELEVEN \| Address: ORLANDO, FL, US \| **1234
	Return from <txn.merchantName> \| address: <txn.merchant_address> \| <txn.cardLast4Digits>	Return from 7-ELEVEN, 7-ELEVEN \| Address: ORLANDO, FL, US \| **1234
Card Transaction	<txn.description> \| <tx.cardLast4Digits>	Cash AppCash Out, Visa Direct, CA, US \| *1234
ATM	Withdraw at <txn.atmName> \| address: <txn.address> \| <txn.cardLast4Digits>	Withdraw at Community Bank, 1983 Beach Blvd \| Address: Biloxi, MS, US \| **1234
	Deposit at <txn.atmName>\| address: <txn.address> \| <txn.cardLast4Digits>	Deposit at Community Bank, 1983 Beach Blvd \| Address: Biloxi, MS, US \| **1234
Card Reversal	Reversal for transaction <txn.relatedTransactionId> \| <txn.cardLast4Digits>	Reversal for transaction #5146923 \| **5380
Check Deposit	<txn.description>
Check return	Returned due to: <return reason> \| <description>	Returned due to: Unable to Locate Account \| Pied Piper
Fee	<txn.description>	Physical Card Replacement Fee
Fee Reversal	Reversal fee transaction for <relatedTransaction.id> \| <description>	Reversal fee transaction for #123
Book	Sender: txn.receiver_name \| txn.description	Sender: Richard Hendrix \| Peer payment: Henry
	Receiver: txn.receiver_name \| txn.description	Receiver: Richard Hendrix \| Peer payment: Henry
Batch Release	<txn.description> \| <txn.senderName>	Cash Deposit CVS \| Richard Hendrix
Interchange	<txn.description>	Accel ATM
Interest	<txn.description>	Interest February 2022
Wire	Wire from <sender_name> \| <description>	Wire from SVB FOR BENEFIT OF Pied Piper \| VI FUND I A SERIES OF company ID 12345
	Wire to <beneficiary_name> \| <description>	Wire to SVB FOR BENEFIT OF Pied Piper \| VI FUND I A SERIES OF company ID 12345
ReturnedWire	Returned due to <reason> \| <description>	Returned due to: NAMEMISSMATCH \| AZ -Part Commission
Dispute	Dispute <dispute_id> \| <dispute_reason>	Dispute 3432 \| Final Credit
ChargeBack	<txn_description>
Payment Cancelled	Cancellation of: <txn.id> \| Payment Id: <payment.id>	Cancellation of: 381481 \| Payment Id: 65647
Adjustment	<free form summary>

Get by Id

Get a transaction by transaction id and account id.

Verb	`GET`
Url	`https://api.s.unit.sh/accounts/:accountId/transactions/{transactionId}`
Required Scope	`transactions`
Timeout (Seconds)	`5`

Query Parameters

Name	Type	Default	Description
filter[customerId]	string	(none)	Optional. Filters the result by the specified customer id.
include	string	(empty)	Optional. A comma-separated list of related resources to include in the response. Related resources include: `customer`, `account`. See Getting Related Resources

Response

Response is a JSON:API document.

200 OK

Field	Type	Description
data	A Transaction	A Transaction resource.
included	Array of DepositAccount or CreditAccount or Customer	Array of resources requested by the `include` query parameter.

curl -X GET 'https://api.s.unit.sh/accounts/:accountId/transactions/:transactionId' \
-H "Authorization: Bearer ${TOKEN}"

List

List transaction resources. Filtering and sorting can be applied. Paging is available only when filtering by customer id or account id.

Verb	`GET`
Url	`https://api.s.unit.sh/transactions`
Required Scope	`transactions`
Timeout (Seconds)	`5`

Query Parameters

Name	Type	Default	Description
page[limit]	integer	100	Optional. Maximum number of resources that will be returned. Maximum is 1000 resources. See Pagination.
page[offset]	integer	0	Optional. Number of resources to skip. See Pagination.
filter[accountId]	string	(empty)	Optional. Filters the results by the specified account id.
filter[accountIds][]	string	(empty)	Optional. Filters the results by the specified account ids. Usage example: filter[accountIds][0]=10000&filter[accountIds][1]=10001
filter[customerId]	string	(empty)	Optional. Filters the results by the specified customer id.
filter[query]	string	(empty)	Optional. search term according to the Full-Text Search Rules.
filter[tags]	Tags (JSON)	(empty)	Optional. Filter Transactions by Tags.
filter[since]	RFC3339 Date string	(empty)	Optional. Filters the Transactions that occurred after the specified date. e.g. `2020-01-13T16:01:19.346Z`
filter[until]	RFC3339 Date string	(empty)	Optional. Filters the Transactions that occurred before the specified date. e.g. `2020-01-02T20:06:23.486Z`
filter[cardId]	string	(empty)	Optional. Filters the results by the specified card id.
filter[type][]	string	(empty)	Optional. Filter Transactions by Transaction type. Possible values include: `OriginatedAch`, `ReceivedAch`, `ReturnedAch`, `DishonoredAch`, `Book`, `Purchase`, `Atm`, `Fee`, `Reversal`, `CardTransaction`, `BatchRelease`, `Wire`, `ReturnedWire`, `Dispute`, `Adjustment`, `Interest`, `Reward`, `CheckDeposit`, `ReturnedCheckDeposit`, `PaymentCanceled`, `CustomerRepayment`. Usage example: filter[type][0]=OriginatedAch&filter[type][1]=ReceivedAch
filter[fromAmount]	Integer	(empty)	Optional. Filters the Transactions that have an amount that is higher or equal to the specified amount (in cents). e.g. `5000`
filter[toAmount]	Integer	(empty)	Optional. Filters the Transactions that have an amount that is lower or equal to the specified amount (in cents). e.g. `7000`
filter[direction][]	string	(empty)	Optional. Filter Transactions by direction (`Debit`, `Credit`). Usage example: filter[direction][0]=Debit
filter[excludeFees]	boolean	(empty)	Optional. Filter Fee type Transactions.
filter[accountType]	string	(empty)	Optional. Filter Transactions by account type (`deposit`, `credit`).
sort	string	`sort=createdAt`	Optional. Leave empty or provide `sort=createdAt` for ascending order. Provide `sort=-createdAt` (leading minus sign) for descending order.
include	string	(empty)	Optional. A comma-separated list of related resources to include in the response. Related resources include: `customer`, `account`. See Getting Related Resources

curl -X GET 'https://api.s.unit.sh/transactions?page[limit]=20&page[offset]=10' \
-H "Authorization: Bearer ${TOKEN}"

Response

Response is a JSON:API document.

200 OK

Field	Type	Description
data	Array of Transactions	Array of transaction resources.
included	Array of DepositAccount or CreditAccount or Customer	Array of resources requested by the `include` query parameter.
meta	JSON object that contains pagination data	Optional. Will be defined only when filtered by `customer` or `account` id. Pagination data includes offset, limit and total (estimated total items).

Example Response:
{
  "data": [
    {
      "type": "originatedAchTransaction",
      "id": "337",
      "attributes": {
        "createdAt": "2020-09-06T07:51:02.570Z",
        "direction": "Credit",
        "amount": 10000,
        "balance": 10000,
        "summary": "Counterparty: Unit Inc | Description: Funding",
        "description": "Funding",
        "counterparty": {
          "name": "Unit Inc",
          "routingNumber": "812345678",
          "accountNumber": "1",
          "accountType": "Checking"
        }
      },
      "relationships": {
        "account": {
          "data": {
            "type": "account",
            "id": "10001"
          }
        },
        "customer": {
          "data": {
            "type": "customer",
            "id": "3"
          }
        }
      }
    },
    {
      "type": "feeTransaction",
      "id": "338",
      "attributes": {
        "createdAt": "2020-09-06T07:51:03.094Z",
        "direction": "Debit",
        "amount": 10,
        "balance": 9990,
        "summary": "Fee - Funding"
      },
      "relationships": {
        "account": {
          "data": {
            "type": "account",
            "id": "10001"
          }
        },
        "customer": {
          "data": {
            "type": "customer",
            "id": "3"
          }
        },
        "relatedTransaction": {
          "data": {
            "type": "transaction",
            "id": "337"
          }
        }
      }
    }
  ],
  "meta": {
    "pagination": {
      "total": 2,
      "limit": 100,
      "offset": 0
    }
  }
}

Update Tags

Update Tags Transaction

Verb	`PATCH`
Url	`https://api.s.unit.sh/accounts/:accountId/transactions/:transactionId`
Required Scope	`transactions-write`
Timeout (Seconds)	`5`

Attributes

Name	Type	Description
tags	object	Optional. See Updating Tags.

Response

Response is a JSON:API document.

200 OK

Field	Type	Description
data	A Transaction	A Transaction resource.

Example Request:
{
  "data": {
    "type": "transaction",
    "attributes": {
      "tags": {
        "trackUserId": "1234"
      }
    }
  }
}

Update Book Transaction

Verb	`PATCH`
Url	`https://api.s.unit.sh/transactions/:transactionId`
Required Scope	`transactions-write`
Timeout (Seconds)	`5`

Attributes

Name	Type	Description
summary	string	Optional. Summary of the transaction.
tags	object	Optional. See Updating Tags.

Relationships

Name	Type	Description
account	JSON:API Relationship	The originating or the receiving account.

Response

Response is a JSON:API document.

200 OK

Field	Type	Description
data	A Transaction	A Transaction resource.

Example Request:
{
  "data": {
    "type": "bookTransaction",
    "attributes": {
      "summary": "Counterparty: Unit Inc | Description: Funding",
      "tags": {
        "trackUserId": "1234"
      }
    },
    "relationships": {
      "account": {
        "data": {
          "type": "account",
          "id": "555"
        }
      }
    }
  }
}

Update Chargeback Transaction

Verb	`PATCH`
Url	`https://api.s.unit.sh/transactions/:transactionId`
Required Scope	`transactions-write`
Timeout (Seconds)	`5`

Attributes

Name	Type	Description
summary	string	Optional. Summary of the transaction.
tags	object	Optional. See Updating Tags.

Relationships

Name	Type	Description
account	JSON:API Relationship	The originating or the receiving account.

Response

Response is a JSON:API document.

200 OK

Field	Type	Description
data	A Transaction	A Transaction resource.

Example Request:
{
  "data": {
    "type": "chargebackTransaction",
    "attributes": {
      "summary": "Description: Funding",
      "tags": {
        "trackUserId": "1234"
      }
    },
    "relationships": {
      "account": {
        "data": {
          "type": "account",
          "id": "555"
        }
      }
    }
  }
}

Transactions

Transaction Types​

Transaction Summaries​

Get by Id​

Query Parameters​

Response​

200 OK​

List​

Query Parameters​

Response​

200 OK​

Update Tags​

Attributes​

Response​

200 OK​

Update Book Transaction​

Attributes​

Relationships​

Response​

200 OK​

Update Chargeback Transaction​

Attributes​

Relationships​

Response​

200 OK​

Transaction Types

Transaction Summaries

Get by Id

Query Parameters

Response

200 OK

List

Query Parameters

Response

200 OK

Update Tags

Attributes

Response

200 OK

Update Book Transaction

Attributes

Relationships

Response

200 OK

Update Chargeback Transaction

Attributes

Relationships

Response

200 OK