Skip to main content

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:

TypeDescription
Originated ACHAn ACH payment originated from a deposit account.
Received ACHAn ACH payment received by a deposit account.
Returned ACHAn ACH payment returned by the bank.
Returned Received ACHA received ACH payment that has been returned through Unit.
Dishonored Return ACHA returned ACH that was dishonored by the receiving bank.
WireA wire transaction, either received or sent.
Returned WireA returned wire transaction.
BookA payment between two accounts on the same bank.
PurchaseA purchase via debit card.
ATMA deposit or a withdrawal of funds from an ATM with a debit card.
FeeFees incurred for a transaction.
Fee ReversalA reversal of a previous fee transaction.
InterestAn Interest payment to a deposit account.
Card ReversalA reversal of a previous card transaction.
Card TransactionA transaction that represents various card transactions that are not Purchase or ATM transactions. Those might be split in the future into different types.
ReleaseA transaction releasing funds from a batch account.
AdjustmentManual Adjustment is made in situations where the correction of an amount, or a reverse of a completed transaction is needed.
DisputeDispute 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 DepositA received check deposit.
Returned Check DepositA check deposit returned by the bank.
Payment CanceledCancellation of a previously processed ACH payment.
Payment AdvancePayment advance transaction is created in order to Debit an org account against a ReceivedPayment that is advanced .
Repaid Payment AdvanceRepaid 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.
ChargebackA transaction that represent a Chargeback.
RewardA transaction that represent a Reward.
Account Low Balance ClosureHandling of low balance upon account closure.
Negative Balance CoverageA transaction that occurs when closing an account with negative balance. covering the account negative balance.
Check PaymentA Debit transaction that occurs when a Check Payment is processed successfully (Processed status).
Returned Check PaymentA Credit transaction that occurs when a Check Payment has been returned through Unit (Returned status).
Push To CardA Debit transaction that was created from a PushToCard Payment originated from a deposit account.
Push To Card ReversalA Credit transaction that was created in order to reverse a previous Push To Card transaction.
Cash DepositA 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:

FieldtypeDescription
directionstringThe direction in which the funds flow- Debit or Credit.
amountintegerThe amount (cents) of the transaction.
balanceintegerThe account balance (cents) after the transaction.
summarystringHuman-friendly summary of the transaction.
createdAtRFC3339 Date stringThe 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 typeSummary structureExample
Originated ACH<counterparty_name> | <txn_addenda>Richard Hendrix | ACH PYMT
Received ACH<txn_company_name> | <txn_description>Pied Piper INC | Pied Piper
ReturnedACHReturned due to: <txn.reason> | <txn.counterparty_name>Returned due to: InsufficientFunds | Richard Hendrix
ReturnedReceivedACHReturned received ACH transaction #<txn.relatedTransactionId> due to: <tx.reason>Returned received ACH transaction #1234567 due to: InsufficientFunds
DishonoredACHDishonored Return ACH transaction due to: <txn.reason>Dishonored Return ACH transaction due to: UntimelyReturn
Card PurchasePurchase 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 App*Cash Out, Visa Direct, CA, US | **1234
ATMWithdraw 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 ReversalReversal for transaction <txn.relatedTransactionId> | <txn.cardLast4Digits>Reversal for transaction #5146923 | **5380
Check Deposit<txn.description>
Check returnReturned due to: <return reason> | <description>Returned due to: Unable to Locate Account | Pied Piper
Fee<txn.description>Physical Card Replacement Fee
Fee ReversalReversal fee transaction for <relatedTransaction.id> | <description>Reversal fee transaction for #123
BookSender: txn.receiver_name | txn.descriptionSender: Richard Hendrix | Peer payment: Henry
Receiver: txn.receiver_name | txn.descriptionReceiver: 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
WireWire 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
ReturnedWireReturned due to <reason> | <description>Returned due to: NAMEMISSMATCH | AZ -Part Commission
DisputeDispute <dispute_id> | <dispute_reason>Dispute 3432 | Final Credit
ChargeBack<txn_description>
Payment CancelledCancellation 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.

VerbGET
Urlhttps://api.s.unit.sh/accounts/:accountId/transactions/{transactionId}
Required Scopetransactions
Timeout (Seconds)5

Query Parameters

NameTypeDefaultDescription
filter[customerId]string(none)Optional. Filters the result by the specified customer id.
includestring(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

FieldTypeDescription
dataA TransactionA Transaction resource.
includedArray of DepositAccount or CreditAccount or CustomerArray 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.

VerbGET
Urlhttps://api.s.unit.sh/transactions
Required Scopetransactions
Timeout (Seconds)5

Query Parameters

NameTypeDefaultDescription
page[limit]integer100Optional. Maximum number of resources that will be returned. Maximum is 1000 resources. See Pagination.
page[offset]integer0Optional. Number of resources to skip. See Pagination.
filter[accountId]string(empty)Optional. Filters the results by the specified account id.
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, Dispute, Adjustment, Interest, Reward, CheckDeposit, ReturnedCheckDeposit, PaymentCanceled, CustomerRepayment. Usage example: filter[type][0]=OriginatedAch&filter[type][1]=ReceivedAch
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, Dispute, Adjustment, Interest, CheckDeposit, ReturnedCheckDeposit, PaymentCanceled. 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).
sortstringsort=createdAtOptional. Leave empty or provide sort=createdAt for ascending order. Provide sort=-createdAt (leading minus sign) for descending order.
includestring(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

FieldTypeDescription
dataArray of TransactionsArray of transaction resources.
includedArray of DepositAccount or CreditAccount or CustomerArray of resources requested by the include query parameter.
metaJSON object that contains pagination dataOptional. Will be defined only when filtered by customer or account id. Pagination data includes offset, limit and total (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

VerbPATCH
Urlhttps://api.s.unit.sh/accounts/:accountId/transactions/:transactionId
Required Scopetransactions-write
Timeout (Seconds)5

Attributes

NameTypeDescription
tagsobjectOptional. See Updating Tags.

Response

Response is a JSON:API document.

200 OK

FieldTypeDescription
dataA TransactionA Transaction resource.
Example Request:
{
"data": {
"type": "transaction",
"attributes": {
"tags": {
"trackUserId": "1234"
}
}
}
}

Update Book Transaction

Update Book Transaction

VerbPATCH
Urlhttps://api.s.unit.sh/transactions/:transactionId
Required Scopetransactions-write
Timeout (Seconds)5

Attributes

NameTypeDescription
summarystringOptional. Summary of the transaction.
tagsobjectOptional. See Updating Tags.

Relationships

NameTypeDescription
accountJSON:API RelationshipThe originating or the receiving account.

Response

Response is a JSON:API document.

200 OK

FieldTypeDescription
dataA TransactionA 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

Update Chargeback Transaction

VerbPATCH
Urlhttps://api.s.unit.sh/transactions/:transactionId
Required Scopetransactions-write
Timeout (Seconds)5

Attributes

NameTypeDescription
summarystringOptional. Summary of the transaction.
tagsobjectOptional. See Updating Tags.

Relationships

NameTypeDescription
accountJSON:API RelationshipThe originating or the receiving account.

Response

Response is a JSON:API document.

200 OK

FieldTypeDescription
dataA TransactionA Transaction resource.
Example Request:
{
"data": {
"type": "chargebackTransaction",
"attributes": {
"summary": "Description: Funding",
"tags": {
"trackUserId": "1234"
}
},
"relationships": {
"account": {
"data": {
"type": "account",
"id": "555"
}
}
}
}
}