> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.thepennyinc.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.thepennyinc.com/_mcp/server. # List control account transactions GET https://sandbox.api.thepennyinc.com/accounts/control/{account_id}/transactions List transactions belonging to a control account. Required permissions: `account:read`, `transaction:list`. Reference: https://docs.thepennyinc.com/api-reference/penny-banking/accounts/control/transactions/list ## Authentication - `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer `, where token is your auth token. ## Servers - `https://sandbox.api.thepennyinc.com` (Sandbox — safe for testing, no real money movement., default) - `https://live.api.thepennyinc.com` (Live — real businesses, real money movement.) ## Request ### Path parameters - `account_id` (string, required) — The ID of the Control Account. ### Query parameters - `page_size` (integer, optional, default: 100) — Maximum number of results to return per page. Defaults to 100. - `next_page_token` (string, optional, nullable) — Pagination key used to retrieve the next page of results. - `stage_time_greater_than_equal_to` (string, optional, nullable) — Lower time bound for Stage Time, inclusive. - `stage_time_greater_than` (string, optional, nullable) — Lower time bound for Stage Time, exclusive. - `stage_time_equal_to` (string, optional, nullable) — Exact timestamp for Stage Time. - `stage_time_less_than_equal_to` (string, optional, nullable) — Upper time bound for Stage Time, inclusive. - `stage_time_less_than` (string, optional, nullable) — Upper time bound for Stage Time, exclusive. ### Headers - `X-Penny-As-Business` (string, optional, nullable) — Act on behalf of another business that has granted you access. Requires the `business:act_as` permission. ## Response ### 200 A paginated list of transactions. - `items` (list of Transaction, required) — The list of items returned by the API. - `count` (integer, required) — The total number of items returned in this response. - `next_page_token` (string, optional, nullable) — A token for retrieving the next page of results, if applicable. ## Errors ### 400 Bad Request Error The request was malformed: a required field is missing or a value has the wrong type or format. - `type` (string, required) — The name of the exception that was raised. - `message` (string, required) — A human-readable description of the error. - `details` (map from string to any, optional, nullable) — Structured context about the error, if any. - `trace_id` (string, optional, nullable) — Identifier for correlating this error with server-side logs. - `errors` (list of map from string to any, optional, nullable) — Sub-errors that contributed to this failure, if any. ### 401 Unauthorized Error Authentication failed. - `type` (string, required) — The name of the exception that was raised. - `message` (string, required) — A human-readable description of the error. - `details` (map from string to any, optional, nullable) — Structured context about the error, if any. - `trace_id` (string, optional, nullable) — Identifier for correlating this error with server-side logs. - `errors` (list of map from string to any, optional, nullable) — Sub-errors that contributed to this failure, if any. ### 403 Forbidden Error The caller does not have permission to perform this action. - `type` (string, required) — The name of the exception that was raised. - `message` (string, required) — A human-readable description of the error. - `details` (map from string to any, optional, nullable) — Structured context about the error, if any. - `trace_id` (string, optional, nullable) — Identifier for correlating this error with server-side logs. - `errors` (list of map from string to any, optional, nullable) — Sub-errors that contributed to this failure, if any. ### 422 Unprocessable Entity Error The request was well-formed but could not be processed because it breaks a business rule. - `type` (string, required) — The name of the exception that was raised. - `message` (string, required) — A human-readable description of the error. - `details` (map from string to any, optional, nullable) — Structured context about the error, if any. - `trace_id` (string, optional, nullable) — Identifier for correlating this error with server-side logs. - `errors` (list of map from string to any, optional, nullable) — Sub-errors that contributed to this failure, if any. ### 429 Too Many Requests Error Too many requests; retry after the Retry-After header. - `type` (string, required) — The name of the exception that was raised. - `message` (string, required) — A human-readable description of the error. - `details` (map from string to any, optional, nullable) — Structured context about the error, if any. - `trace_id` (string, optional, nullable) — Identifier for correlating this error with server-side logs. - `errors` (list of map from string to any, optional, nullable) — Sub-errors that contributed to this failure, if any. ### 500 Internal Server Error An unexpected error occurred. - `type` (string, required) — The name of the exception that was raised. - `message` (string, required) — A human-readable description of the error. - `details` (map from string to any, optional, nullable) — Structured context about the error, if any. - `trace_id` (string, optional, nullable) — Identifier for correlating this error with server-side logs. - `errors` (list of map from string to any, optional, nullable) — Sub-errors that contributed to this failure, if any. ## Types ### Transaction The client-facing representation of a transaction. - `transaction_id` (string, required) — The unique identifier Penny assigns to this transaction. - `account_id` (string, required) — The unique identifier of the account affected by this transaction. - `business_id` (string, required) — The unique identifier of the business this transaction belongs to. - `business_entity_id` (string, required) — The unique identifier of the business entity this transaction belongs to. - `program_id` (string, required) — The unique identifier of the program this transaction belongs to. - `version` (integer, required) — The revision number within the current processing stage. It starts at 1 when the transaction enters a stage and increases when the record is updated without advancing to the next stage. - `version_time` (datetime, required) — The date and time this revision was recorded. - `stage` (integer, required) — The transaction's processing step number. It increases when a new event advances the transaction through its lifecycle. - `stage_time` (datetime, required) — The date and time the transaction entered its current stage. - `status` (enum, required) — The current lifecycle status of the transaction. - Allowed values: `created`, `declined`, `approved`, `cancelled`, `expired`, `partially_settled`, `settled`, `reversed`, `failed`, `deprecated` - `direction` (enum, required) — Whether funds move into (`inbound`) or out of (`outbound`) the account. - Allowed values: `inbound`, `outbound` - `type` (enum, required) — The client-visible category of the transaction. - Allowed values: `payment`, `transfer` - `base_amount` (string, required) — The transaction amount in the account's settlement currency. - `base_amount_currency` (enum, required) — The three-letter ISO 4217 currency code of the settlement amount. - Allowed values: `USD` - `channel` (TransactionChannel, required) — How the transaction was conducted. - `counterparty` (TransactionCounterparty, required) — The party on the opposite side of the transaction. - `message` (string, optional, nullable) — Additional context about the current status, when available. - `client_reference` (string, optional, nullable) — Your own reference for this transaction, as supplied when the underlying movement was initiated. Penny stores it and never interprets it, and it can be used to look this transaction up. Present only where a reference was supplied. - `original_amount` (string, optional, nullable) — The amount in the currency in which the transaction was presented. Present when that currency differs from the settlement currency. - `original_amount_currency` (enum, optional, nullable) — The three-letter ISO 4217 currency code of the presented amount. Present together with `original_amount`. - Allowed values: `AFN`, `EUR`, `ALL`, `DZD`, `USD`, `AOA`, `XCD`, `XAD`, `ARS`, `AMD`, `AWG`, `AUD`, `AZN`, `BSD`, `BHD`, `BDT`, `BBD`, `BYN`, `BZD`, `XOF`, `BMD`, `INR`, `BTN`, `BOB`, `BOV`, `BAM`, `BWP`, `NOK`, `BRL`, `BND`, `BIF`, `CVE`, `KHR`, `XAF`, `CAD`, `KYD`, `CLP`, `CLF`, `CNY`, `COP`, `COU`, `KMF`, `CDF`, `NZD`, `CRC`, `CUP`, `XCG`, `CZK`, `DKK`, `DJF`, `DOP`, `EGP`, `SVC`, `ERN`, `SZL`, `ETB`, `FKP`, `FJD`, `XPF`, `GMD`, `GEL`, `GHS`, `GIP`, `GTQ`, `GBP`, `GNF`, `GYD`, `HTG`, `HNL`, `HKD`, `HUF`, `ISK`, `IDR`, `XDR`, `IRR`, `IQD`, `ILS`, `JMD`, `JPY`, `JOD`, `KZT`, `KES`, `KPW`, `KRW`, `KWD`, `KGS`, `LAK`, `LBP`, `LSL`, `ZAR`, `LRD`, `LYD`, `CHF`, `MOP`, `MKD`, `MGA`, `MWK`, `MYR`, `MVR`, `MRU`, `MUR`, `XUA`, `MXN`, `MXV`, `MDL`, `MNT`, `MAD`, `MZN`, `MMK`, `NAD`, `NPR`, `NIO`, `NGN`, `OMR`, `PKR`, `PAB`, `PGK`, `PYG`, `PEN`, `PHP`, `PLN`, `QAR`, `RON`, `RUB`, `RWF`, `SHP`, `WST`, `STN`, `SAR`, `RSD`, `SCR`, `SLE`, `SGD`, `XSU`, `SBD`, `SOS`, `SSP`, `LKR`, `SDG`, `SRD`, `SEK`, `CHE`, `CHW`, `SYP`, `TWD`, `TJS`, `TZS`, `THB`, `TOP`, `TTD`, `TND`, `TRY`, `TMT`, `UGX`, `UAH`, `AED`, `USN`, `UYU`, `UYI`, `UYW`, `UZS`, `VUV`, `VES`, `VED`, `VND`, `YER`, `ZMW`, `ZWG`, `XBA`, `XBB`, `XBC`, `XBD`, `XTS`, `XXX`, `XAU`, `XPD`, `XPT`, `XAG`, `CNH`, `SLL` ### TransactionChannel How the transaction was conducted. - CardChannel: CardChannel - InternalChannel: InternalChannel - BankChannel: BankChannel ### TransactionCounterparty The party on the opposite side of the transaction. - CardCounterParty: CardCounterParty - TransferCounterParty: TransferCounterParty - BusinessCounterParty: BusinessCounterParty ### CardChannel A transaction made with a Penny-issued card. - `card_id` (string, required) — The unique identifier of the card used for this transaction. - `cardholder_id` (string, required) — The unique identifier of the cardholder who used the card. - `processing_details` (CardProcessingDetails, required) — Details about how the card payment was initiated and processed. - `scheme_details` (CardSchemeDetails, required) — Client-relevant attributes supplied by the card network. - `type` ("card", optional, default: card) — Identifies this channel as a card transaction. ### InternalChannel A transaction conducted between two Penny-managed accounts. - `type` ("internal", optional, default: internal) — Identifies this channel as an internal transfer. ### BankChannel A transaction conducted through a linked external bank account, such as an incoming ACH credit. - `linked_account_id` (string, required) — The unique identifier of the linked account involved in the transaction. - `type` ("bank", optional, default: bank) — Identifies this channel as a bank transaction. ### CardCounterParty The merchant and acquirer involved in a card transaction. - `merchant` (Merchant, required) — The merchant associated with the card transaction. - `acquirer` (AcquirerDetails, required) — The acquiring bank that processed the payment for the merchant. - `type` ("card", optional, default: card) — Identifies this counterparty as a card merchant. ### TransferCounterParty The other Penny-managed account involved in an internal transfer. - `account_id` (string, required) — The unique identifier of the account on the other side of the transfer. - `type` ("transfer", optional, default: transfer) — Identifies this counterparty as an internal transfer account. ### BusinessCounterParty The receiving or sending business involved in a transaction. - `business_id` (string, required) — The unique identifier of the counterparty business. - `business_entity_id` (string, required) — The unique identifier of the counterparty business entity. - `business_name` (string, required) — The display name of the counterparty business. - `type` ("business", optional, default: business) — Identifies this counterparty as a business. ### CardProcessingDetails Client-relevant details about how a card payment was processed. - `card_product_id` (string, required) — The unique identifier of the product under which the card was issued. - `pan_entry_mode` (string, optional, nullable) — How the card details were provided, such as by contactless tap, chip, or manual entry. - `type` (string, optional, nullable) — The payment environment, such as e-commerce or point of service. - `card_class` (string, optional, nullable) — The card classification, such as consumer or commercial. ### CardSchemeDetails Client-relevant card-network attributes for a payment. - `network` (string, required) — The card network that processed the payment. - `funding_type` (string, optional, nullable) — How the card is funded, such as prepaid, debit, or credit. - `product_type` (string, optional, nullable) — The network's product category, such as consumer or corporate. ### Merchant External representation of a merchant associated with a transaction. - `merchant_id` (string, required) — The card network's own merchant identifier, reported on the transaction at authorization time. - `code` (string, required) — Four-digit merchant category code (MCC). - `name` (string, required) — Display name of the merchant. - `category` (string, optional, nullable) — Merchant category description. - `city` (string, optional, nullable) — City where the merchant is located. - `country` (enum, optional, nullable) — ISO 3166-1 alpha-2 country code of the merchant location. - Allowed values: `AW`, `AF`, `AO`, `AI`, `AX`, `AL`, `AD`, `AE`, `AR`, `AM`, `AS`, `AQ`, `TF`, `AG`, `AU`, `AT`, `AZ`, `BI`, `BE`, `BJ`, `BQ`, `BF`, `BD`, `BG`, `BH`, `BS`, `BA`, `BL`, `BY`, `BZ`, `BM`, `BO`, `BR`, `BB`, `BN`, `BT`, `BV`, `BW`, `CF`, `CA`, `CC`, `CH`, `CL`, `CN`, `CI`, `CM`, `CD`, `CG`, `CK`, `CO`, `KM`, `CV`, `CR`, `CU`, `CW`, `CX`, `KY`, `CY`, `CZ`, `DE`, `DJ`, `DM`, `DK`, `DO`, `DZ`, `EC`, `EG`, `ER`, `EH`, `ES`, `EE`, `ET`, `FI`, `FJ`, `FK`, `FR`, `FO`, `FM`, `GA`, `GB`, `GE`, `GG`, `GH`, `GI`, `GN`, `GP`, `GM`, `GW`, `GQ`, `GR`, `GD`, `GL`, `GT`, `GF`, `GU`, `GY`, `HK`, `HM`, `HN`, `HR`, `HT`, `HU`, `ID`, `IM`, `IN`, `IO`, `IE`, `IR`, `IQ`, `IS`, `IL`, `IT`, `JM`, `JE`, `JO`, `JP`, `KZ`, `KE`, `KG`, `KH`, `KI`, `KN`, `KR`, `KW`, `LA`, `LB`, `LR`, `LY`, `LC`, `LI`, `LK`, `LS`, `LT`, `LU`, `LV`, `MO`, `MF`, `MA`, `MC`, `MD`, `MG`, `MV`, `MX`, `MH`, `MK`, `ML`, `MT`, `MM`, `ME`, `MN`, `MP`, `MZ`, `MR`, `MS`, `MQ`, `MU`, `MW`, `MY`, `YT`, `NA`, `NC`, `NE`, `NF`, `NG`, `NI`, `NU`, `NL`, `NO`, `NP`, `NR`, `NZ`, `OM`, `PK`, `PA`, `PN`, `PE`, `PH`, `PW`, `PG`, `PL`, `PR`, `KP`, `PT`, `PY`, `PS`, `PF`, `QA`, `RE`, `RO`, `RU`, `RW`, `SA`, `SD`, `SN`, `SG`, `GS`, `SH`, `SJ`, `SB`, `SL`, `SV`, `SM`, `SO`, `PM`, `RS`, `SS`, `ST`, `SR`, `SK`, `SI`, `SE`, `SZ`, `SX`, `SC`, `SY`, `TC`, `TD`, `TG`, `TH`, `TJ`, `TK`, `TM`, `TL`, `TO`, `TT`, `TN`, `TR`, `TV`, `TW`, `TZ`, `UG`, `UA`, `UM`, `UY`, `US`, `UZ`, `VA`, `VC`, `VE`, `VG`, `VI`, `VN`, `VU`, `WF`, `WS`, `YE`, `ZA`, `ZM`, `ZW` - `subdivision` (string, optional, nullable) — ISO 3166-2 subdivision code of the merchant location (e.g. 'US-CA'). - `zip_code` (string, optional, nullable) — Postal or ZIP code of the merchant location. ### AcquirerDetails The acquiring bank that processed a card payment for the merchant. - `id` (string, required) — The unique identifier of the acquiring bank. - `name` (string, optional, nullable) — The name of the acquiring bank, when available. ## Examples **Response** ```json { "items": [ { "transaction_id": "transaction_01937a7d-ad6b-77ca-8046-ad6b7ca046ce", "account_id": "account_019372e3-b8dc-7de2-80b6-b8dcde20b6c9", "business_id": "business_01937b95-484e-75af-8c68-484e5afc68d3", "business_entity_id": "business_entity_01937c9d-3a1e-72b0-8881-3a1e2b088159", "program_id": "program_019377de-7f88-7f02-894f-7f88f0294fcb", "version": 1, "version_time": "2024-01-15T10:30:00Z", "stage": 2, "stage_time": "2024-01-15T10:30:00Z", "status": "approved", "direction": "outbound", "type": "payment", "base_amount": "108.50", "base_amount_currency": "USD", "channel": { "card_id": "card_019375de-a2a0-7f31-884a-a2a0f3184abd", "cardholder_id": "cardholder_01937e19-4ebb-75bd-8250-4ebb5bd25085", "processing_details": { "card_class": "consumer", "card_product_id": "card_product_01937f5d-a015-7a55-818b-a015a5518b97", "pan_entry_mode": "contactless", "type": "point_of_service" }, "scheme_details": { "funding_type": "prepaid", "network": "visa", "product_type": "consumer" }, "type": "card" }, "counterparty": { "acquirer": { "id": "acq_01j8xyzabc", "name": "First National Merchant Services" }, "merchant": { "category": "Grocery Stores, Supermarkets", "city": "San Francisco", "code": "5411", "country": "US", "merchant_id": "WFM-0481726", "name": "Whole Foods Market", "subdivision": "US-CA", "zip_code": "94105" }, "type": "card" }, "message": "Card payment approved", "client_reference": "payroll-run-2026-09-invoice-4471", "original_amount": "100.00", "original_amount_currency": "EUR" } ], "count": 1, "next_page_token": "string" } ``` **SDK Code** ```python import requests url = "https://sandbox.api.thepennyinc.com/accounts/control/account_id/transactions" headers = { "X-Penny-As-Business": "business_01a083e2-82ed-7a5c-9d1e-3b6f0c2a4d71", "Authorization": "Bearer " } response = requests.get(url, headers=headers) print(response.json()) ``` ```javascript const url = 'https://sandbox.api.thepennyinc.com/accounts/control/account_id/transactions'; const options = { method: 'GET', headers: { 'X-Penny-As-Business': 'business_01a083e2-82ed-7a5c-9d1e-3b6f0c2a4d71', Authorization: 'Bearer ' } }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://sandbox.api.thepennyinc.com/accounts/control/account_id/transactions" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("X-Penny-As-Business", "business_01a083e2-82ed-7a5c-9d1e-3b6f0c2a4d71") req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://sandbox.api.thepennyinc.com/accounts/control/account_id/transactions") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["X-Penny-As-Business"] = 'business_01a083e2-82ed-7a5c-9d1e-3b6f0c2a4d71' request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://sandbox.api.thepennyinc.com/accounts/control/account_id/transactions") .header("X-Penny-As-Business", "business_01a083e2-82ed-7a5c-9d1e-3b6f0c2a4d71") .header("Authorization", "Bearer ") .asString(); ``` ```php request('GET', 'https://sandbox.api.thepennyinc.com/accounts/control/account_id/transactions', [ 'headers' => [ 'Authorization' => 'Bearer ', 'X-Penny-As-Business' => 'business_01a083e2-82ed-7a5c-9d1e-3b6f0c2a4d71', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://sandbox.api.thepennyinc.com/accounts/control/account_id/transactions"); var request = new RestRequest(Method.GET); request.AddHeader("X-Penny-As-Business", "business_01a083e2-82ed-7a5c-9d1e-3b6f0c2a4d71"); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "X-Penny-As-Business": "business_01a083e2-82ed-7a5c-9d1e-3b6f0c2a4d71", "Authorization": "Bearer " ] let request = NSMutableURLRequest(url: NSURL(string: "https://sandbox.api.thepennyinc.com/accounts/control/account_id/transactions")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```