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

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

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
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
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 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, 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
excludeFeesboolean(empty)Optional. Filter Fee type Transactions.
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 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#

Update 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"      }    }  }}