Lithic Financial Account API
The Financial Account API from Lithic — 9 operation(s) for financial account.
OpenAPI Specification
openapi: 3.1.0
info:
contact:
email: support@lithic.com
description: 'The Lithic Developer API is designed to provide a predictable programmatic interface for accessing your Lithic account through an API and transaction webhooks.
Note that your API key is a secret and should be treated as such. Don''t share it with anyone, including us. We will never ask you for it.
'
termsOfService: https://lithic.com/legal/terms
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.txt
title: Lithic Developer 3DS Financial Account API
version: 1.0.0
servers:
- description: Sandbox environment that provides key functionality mirroring production
url: https://sandbox.lithic.com
security:
- ApiKeyAuth: []
tags:
- name: Financial Account
paths:
/v1/financial_accounts:
get:
description: Retrieve information on your financial accounts including routing and account number.
operationId: getFinancialAccounts
parameters:
- description: List financial accounts for a given account_token or business_account_token
in: query
name: account_token
schema:
format: uuid
type: string
- description: List financial accounts for a given business_account_token
in: query
name: business_account_token
schema:
format: uuid
type: string
- description: List financial accounts of a given type
in: query
name: type
schema:
enum:
- ISSUING
- OPERATING
- RESERVE
- SECURITY
- EARLY_DIRECT_DEPOSIT_FLOAT
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/financial-accounts-response'
description: OK
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
summary: List financial accounts
tags:
- Financial Account
post:
description: Create a new financial account
operationId: createFinancialAccount
parameters:
- $ref: '#/components/parameters/idempotencyKey'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateFinancialAccountRequest'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/financial-account-response'
description: OK
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
summary: Create financial account
tags:
- Financial Account
/v1/financial_accounts/{financial_account_token}:
get:
description: Get a financial account
operationId: getFinancialAccountByToken
parameters:
- in: path
name: financial_account_token
required: true
schema:
format: uuid
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/financial-account-response'
description: OK
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
summary: Get financial account
tags:
- Financial Account
patch:
description: Update a financial account
operationId: updateFinancialAccountByToken
parameters:
- in: path
name: financial_account_token
required: true
schema:
format: uuid
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateFinancialAccountRequest'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/financial-account-response'
description: OK
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
summary: Update financial account
tags:
- Financial Account
/v1/financial_accounts/{financial_account_token}/credit_configuration:
get:
description: Get an Account's credit configuration
operationId: getAccountCreditConfiguration
parameters:
- $ref: '#/components/parameters/financialAccountToken'
summary: Get account credit configuration
tags:
- Financial Account
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/financial-account-credit-config-response'
patch:
description: Update an account's credit configuration
operationId: patchAccountCreditConfiguration
summary: Update account credit configuration
tags:
- Financial Account
parameters:
- $ref: '#/components/parameters/financialAccountToken'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/financial-account-credit-config-request'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/financial-account-credit-config-response'
/v1/financial_accounts/{financial_account_token}/financial_transactions:
get:
description: List the financial transactions for a given financial account.
operationId: getFinancialTransactions
parameters:
- description: Financial Transaction category to be returned.
in: query
name: category
schema:
enum:
- ACH
- CARD
- INTERNAL
- TRANSFER
type: string
- description: Financial Transaction result to be returned.
in: query
name: result
schema:
enum:
- APPROVED
- DECLINED
type: string
- description: Financial Transaction status to be returned.
in: query
name: status
schema:
enum:
- DECLINED
- EXPIRED
- PENDING
- RETURNED
- SETTLED
- VOIDED
type: string
- $ref: '#/components/parameters/beginTime'
- $ref: '#/components/parameters/endTime'
- $ref: '#/components/parameters/endingBefore'
- $ref: '#/components/parameters/financialAccountToken'
- $ref: '#/components/parameters/startingAfter'
responses:
'200':
content:
application/json:
schema:
properties:
data:
items:
$ref: '#/components/schemas/financial-account-transaction'
type: array
has_more:
description: More data exists.
type: boolean
required:
- data
- has_more
type: object
description: OK
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
summary: List financial transactions
tags:
- Financial Account
/v1/financial_accounts/{financial_account_token}/financial_transactions/{financial_transaction_token}:
get:
description: Get the financial transaction for the provided token.
operationId: getFinancialTransactionByToken
parameters:
- $ref: '#/components/parameters/financialAccountToken'
- $ref: '#/components/parameters/financialTransactionToken'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/financial-account-transaction'
description: OK
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
summary: Get financial transaction
tags:
- Financial Account
/v1/financial_accounts/{financial_account_token}/register_account_number:
post:
description: Register account number
operationId: registerAccountNumber
parameters:
- $ref: '#/components/parameters/financialAccountToken'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/register_account_number_request'
responses:
'200':
description: OK
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
summary: Register Account Number
tags:
- Financial Account
/v1/financial_accounts/{financial_account_token}/update_status:
post:
description: Update financial account status
operationId: updateFinancialAccountStatus
summary: Update financial account status
tags:
- Financial Account
parameters:
- $ref: '#/components/parameters/financialAccountToken'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/update-financial-account-status-request'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/financial-account-response'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
/v1/account_activity:
get:
operationId: listAccountActivity
summary: List Account Activity
description: Retrieve a list of transactions across all public accounts.
parameters:
- name: status
in: query
description: Filter by transaction status
schema:
enum:
- DECLINED
- EXPIRED
- PENDING
- RETURNED
- REVERSED
- SETTLED
- VOIDED
- name: result
in: query
description: Filter by transaction result
schema:
enum:
- APPROVED
- DECLINED
- name: financial_account_token
in: query
description: Filter by financial account token
schema:
type: string
format: uuid
- name: business_account_token
in: query
description: Filter by business account token
schema:
type: string
format: uuid
- name: account_token
in: query
description: Filter by account token
schema:
type: string
format: uuid
- name: category
in: query
description: Filter by transaction category
schema:
$ref: '#/components/schemas/transaction_category'
- $ref: '#/components/parameters/beginTime'
- $ref: '#/components/parameters/endingBefore'
- $ref: '#/components/parameters/endTime'
- $ref: '#/components/parameters/pageSize'
- $ref: '#/components/parameters/startingAfter'
responses:
'200':
description: Successful response with unified transaction data
content:
application/json:
schema:
$ref: '#/components/schemas/base-transactions-response'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/error'
tags:
- Financial Account
/v1/account_activity/{transaction_token}:
get:
operationId: getAccountActivity
summary: Get Single Transaction from Account Activity
description: Retrieve a single transaction
parameters:
- name: transaction_token
in: path
required: true
description: The unique identifier for the transaction
schema:
type: string
format: uuid
responses:
'200':
description: Successful response with the requested account activity
content:
application/json:
schema:
$ref: '#/components/schemas/base-transaction-response'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'404':
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/error'
tags:
- Financial Account
components:
schemas:
base_transaction:
title: base_transaction
description: Base class for all transaction types in the ledger service
type: object
properties:
status:
$ref: '#/components/schemas/transaction_status'
description: The status of the transaction
token:
type: string
description: Unique identifier for the transaction
format: uuid
created:
type: string
description: ISO 8601 timestamp of when the transaction was created
format: date-time
updated:
type: string
description: ISO 8601 timestamp of when the transaction was last updated
format: date-time
required:
- status
- token
- created
- updated
hold_event:
title: Hold Event
description: Event representing a lifecycle change to a hold
type: object
properties:
token:
type: string
format: uuid
type:
$ref: '#/components/schemas/hold_event_type'
result:
$ref: '#/components/schemas/transaction_result'
detailed_results:
type: array
items:
$ref: '#/components/schemas/detailed_results'
amount:
type: integer
description: Amount in cents
created:
type: string
format: date-time
memo:
type:
- string
- 'null'
settling_transaction_token:
type:
- string
- 'null'
format: uuid
description: Transaction token of the payment that settled this hold (only populated for HOLD_SETTLED events)
required:
- token
- type
- result
- detailed_results
- amount
- created
- memo
- settling_transaction_token
financial-transaction:
title: Financial Transaction
description: Financial transaction with inheritance from unified base transaction
allOf:
- $ref: '#/components/schemas/base_transaction'
- type: object
properties:
family:
type: string
const: INTERNAL
description: INTERNAL - Financial Transaction
category:
$ref: '#/components/schemas/transaction_category'
description: Transaction category
result:
$ref: '#/components/schemas/transaction_result'
description: Transaction result
currency:
type: string
description: Currency of the transaction, represented in ISO 4217 format
example: USD
settled_amount:
type: integer
description: Settled amount in cents
example: 200
pending_amount:
type: integer
description: Pending amount in cents
example: 500
events:
type: array
items:
$ref: '#/components/schemas/financial_event'
description: List of transaction events
descriptor:
type: string
description: Transaction descriptor
financial_account_token:
type: string
format: uuid
description: Financial account token associated with the transaction
example: 0cc87075-57cf-4607-8722-f42e2cb2c0cd
required:
- category
- currency
- family
- result
- settled_amount
- pending_amount
- events
- descriptor
- financial_account_token
service_location:
title: Service Location
description: Where the cardholder received the service, when different from the card acceptor location. This is populated from network data elements such as Mastercard DE-122 SE1 SF9-14 and Visa F34 DS02.
type: object
properties:
street_address:
description: Street address of service location.
type:
- string
- 'null'
city:
description: City of service location.
type:
- string
- 'null'
state:
description: State/province code of service location, ISO 3166-2.
type:
- string
- 'null'
country:
description: Country code of service location, ISO 3166-1 alpha-3.
type:
- string
- 'null'
postal_code:
description: Postal code of service location.
type:
- string
- 'null'
required:
- street_address
- city
- state
- country
- postal_code
financial-account-credit-config:
title: Financial Account Credit Config
type:
- object
- 'null'
properties:
credit_limit:
type:
- integer
- 'null'
external_bank_account_token:
type:
- string
- 'null'
format: uuid
credit_product_token:
type:
- string
- 'null'
description: Globally unique identifier for the credit product
tier:
type:
- string
- 'null'
description: Tier assigned to the financial account
auto_collection_configuration:
oneOf:
- type: 'null'
- $ref: '#/components/schemas/auto-collection-configuration-response'
required:
- credit_limit
- external_bank_account_token
- credit_product_token
- tier
- auto_collection_configuration
pos_entry_mode:
title: Point of Sale Entry Mode
type: object
properties:
card:
type: string
enum:
- NOT_PRESENT
- PREAUTHORIZED
- PRESENT
- UNKNOWN
description: Card presence indicator
cardholder:
type: string
enum:
- DEFERRED_BILLING
- ELECTRONIC_ORDER
- INSTALLMENT
- MAIL_ORDER
- NOT_PRESENT
- PREAUTHORIZED
- PRESENT
- REOCCURRING
- TELEPHONE_ORDER
- UNKNOWN
description: Cardholder presence indicator
pan:
type: string
enum:
- AUTO_ENTRY
- BAR_CODE
- CONTACTLESS
- CREDENTIAL_ON_FILE
- ECOMMERCE
- ERROR_KEYED
- ERROR_MAGNETIC_STRIPE
- ICC
- KEY_ENTERED
- MAGNETIC_STRIPE
- MANUAL
- OCR
- SECURE_CARDLESS
- UNKNOWN
- UNSPECIFIED
description: Method of entry for the PAN
pin_entered:
type: boolean
description: Indicates whether the cardholder entered the PIN. True if the PIN was entered.
required:
- card
- cardholder
- pan
- pin_entered
book_transfer_type:
type: string
enum:
- ATM_BALANCE_INQUIRY
- ATM_WITHDRAWAL
- ATM_DECLINE
- INTERNATIONAL_ATM_WITHDRAWAL
- INACTIVITY
- STATEMENT
- MONTHLY
- QUARTERLY
- ANNUAL
- CUSTOMER_SERVICE
- ACCOUNT_MAINTENANCE
- ACCOUNT_ACTIVATION
- ACCOUNT_CLOSURE
- CARD_REPLACEMENT
- CARD_DELIVERY
- CARD_CREATE
- CURRENCY_CONVERSION
- INTEREST
- LATE_PAYMENT
- BILL_PAYMENT
- CASH_BACK
- ACCOUNT_TO_ACCOUNT
- CARD_TO_CARD
- DISBURSE
- BILLING_ERROR
- LOSS_WRITE_OFF
- EXPIRED_CARD
- EARLY_DERECOGNITION
- ESCHEATMENT
- INACTIVITY_FEE_DOWN
- PROVISIONAL_CREDIT
- DISPUTE_WON
- SERVICE
- TRANSFER
- COLLECTION
description: Type of the book transfer
title: Book Transfer Type
external_resource:
title: ExternalResource
type: object
required:
- external_resource_type
- external_resource_token
properties:
external_resource_type:
$ref: '#/components/schemas/external_resource_type'
external_resource_token:
type: string
description: Token identifying the external resource
external_resource_sub_token:
type: string
description: Token identifying the external resource sub-resource
description: External resource associated with the management operation
additionalProperties: false
external_payment_event:
title: External Payment Event
type: object
properties:
amount:
type: integer
type:
$ref: '#/components/schemas/external_payment_event_type'
result:
$ref: '#/components/schemas/transaction_result'
detailed_results:
type: array
items:
$ref: '#/components/schemas/detailed_results'
created:
type: string
format: date-time
token:
type: string
format: uuid
memo:
type: string
effective_date:
type: string
format: date
required:
- amount
- type
- result
- detailed_results
- created
- token
- memo
- effective_date
payment_event:
title: Payment Event
description: 'Note: Inbound wire transfers are coming soon (availability varies by partner bank). Wire-related fields below are a preview. To learn more, contact your customer success manager.
Payment Event'
type: object
properties:
amount:
description: Amount of the financial event that has been settled in the currency's smallest unit (e.g., cents).
type: integer
created:
description: Date and time when the financial event occurred. UTC time zone.
type: string
format: date-time
detailed_results:
description: More detailed reasons for the event
type: array
items:
type: string
enum:
- APPROVED
- DECLINED
- FUNDS_INSUFFICIENT
- ACCOUNT_INVALID
- PROGRAM_TRANSACTION_LIMIT_EXCEEDED
- PROGRAM_DAILY_LIMIT_EXCEEDED
- PROGRAM_MONTHLY_LIMIT_EXCEEDED
result:
description: APPROVED financial events were successful while DECLINED financial events were declined by user, Lithic, or the network.
type: string
enum:
- APPROVED
- DECLINED
token:
description: Globally unique identifier.
type: string
format: uuid
type:
$ref: '#/components/schemas/payment_event_type'
external_id:
description: 'Payment event external ID. For ACH transactions, this is the ACH trace number.
For inbound wire transfers, this is the IMAD (Input Message Accountability Data).
'
type:
- string
- 'null'
required:
- amount
- created
- result
- token
- type
pos:
title: Point of Sale
type: object
properties:
entry_mode:
$ref: '#/components/schemas/pos_entry_mode'
terminal:
$ref: '#/components/schemas/pos_terminal'
required:
- entry_mode
- terminal
AchMethodAttributes:
type: object
properties:
sec_code:
type: string
enum:
- CCD
- PPD
- WEB
- TEL
- CIE
- CTX
description: SEC code for ACH transaction
return_reason_code:
type:
- string
- 'null'
description: Return reason code if the transaction was returned
ach_hold_period:
type:
- integer
- 'null'
minimum: 0
description: Number of days the ACH transaction is on hold
retries:
type:
- integer
- 'null'
minimum: 0
description: Number of retries attempted
company_id:
type:
- string
- 'null'
description: Company ID for the ACH transaction
receipt_routing_number:
type:
- string
- 'null'
description: Receipt routing number
trace_numbers:
type: array
items:
type: string
default: []
description: Trace numbers for the ACH transaction
addenda:
type:
- string
- 'null'
description: Addenda information
override_company_name:
type:
- string
- 'null'
maxLength: 512
description: Value to override the configured company name with. Can only be used if allowed to override
required:
- sec_code
tags:
title: Tags
description: Key-value pairs for tagging resources. Tags allow you to associate arbitrary metadata with a resource for your own purposes.
type: object
additionalProperties:
type: string
example:
risk-level: high
external_payment_category:
title: External Payment Category
type: string
enum:
- EXTERNAL_WIRE
- EXTERNAL_ACH
- EXTERNAL_CHECK
- EXTERNAL_FEDNOW
- EXTERNAL_RTP
- EXTERNAL_TRANSFER
CreateFinancialAccountRequest:
properties:
account_token:
format: uuid
title: Account token to create the new account under
type: string
nickname:
maxLength: 256
title: Nickname of the financial account
type: string
type:
enum:
- OPERATING
title: Account Type
type: string
is_for_benefit_of:
title: Is For Benefit Of
type: boolean
required:
- nickname
- type
title: CreateFinancialAccountRequest
type: object
external_payment_response:
title: External Payment Response
allOf:
- $ref: '#/components/schemas/base_transaction'
- type: object
properties:
family:
type: string
const: EXTERNAL_PAYMENT
description: EXTERNAL_PAYMENT - External Payment Response
result:
$ref: '#/components/schemas/transaction_result'
category:
$ref: '#/components/schemas/external_payment_category'
settled_amount:
type: integer
pending_amount:
type: integer
currency:
type: string
events:
type: array
items:
$ref: '#/components/schemas/external_payment_event'
user_defined_id:
type:
- string
- 'null'
financial_account_token:
type: string
format: uuid
payment_type:
$ref: '#/components/schemas/external_payment_direction'
required:
- result
- category
- family
- settled_amount
- pending_amount
- currency
- events
- financial_account_token
- payment_type
network_specific_data:
title: Network Specific Data
type: object
properties:
mastercard:
$ref: '#/components/schemas/mastercard_network_specific_data'
visa:
$ref: '#/components/schemas/visa_network_specific_data'
required:
- mastercard
- visa
hold_status:
title: Hold Status
description: Status of a hold transaction
type: string
enum:
- PENDING
- SETTLED
- EXPIRED
- VOIDED
transaction_category:
title: Transaction Category
description: 'Note: Inbound wire transfers are coming soon (availability varies by partner bank). The WIRE category is a preview. To learn more, contact your customer success manager.'
type: string
enum:
- ACH
- WIRE
- BALANCE_OR_FUNDING
- FEE
- REWARD
- ADJUSTMENT
- DERECOGNITION
- DISPUTE
- CARD
- EXTERNAL_ACH
- EXTERNAL_CHECK
- EXTERNAL_FEDNOW
- EXTERNAL_RTP
- EXTERNAL_TRANSFER
- EXTERNAL_WIRE
- MANAGEMENT_ADJUSTMENT
- MANAGEMENT_DISPUTE
- MANAGEMENT_FEE
- MANAGEMENT_REWARD
- MANAGEMENT_DISBURSEMENT
- HOLD
- PROGRAM_FUNDING
financial-account-substatus:
title: Financial Account Substatus
description: Substatus for the financial account
type: string
enum:
- CHARGED_OFF_DELINQUENT
- CHARGED_OFF_FRAUD
- END_USER_REQUEST
- BANK_REQUEST
- DELINQUENT
- INTEREST_AND_FEES_PAUSED
currency:
description: 3-character alphabetic ISO 4217 currency
example: USD
title: Currency
type: string
update-financial-account-status-request:
title: Update financial account status request
type: object
properties:
status:
$re
# --- truncated at 32 KB (115 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/lithic/refs/heads/main/openapi/lithic-financial-account-api-openapi.yml