payment_token

uuid

required

``202 Accepted

object

Base class for all transaction types in the ledger service

status

• type: string
• enum
• required
• Description: The status of the transaction

PENDING, SETTLED, DECLINED, REVERSED, CANCELED, RETURNED

token

• type: uuid
• required
• Description: Unique identifier for the transaction

created

• type: date-time
• required
• Description: ISO 8601 timestamp of when the transaction was created

updated

• type: date-time
• required
• Description: ISO 8601 timestamp of when the transaction was last updated

family

• const
• enum
• required
• Description: PAYMENT - Payment Transaction

PAYMENT

category

• type: string
• enum
• required
• Description: Transaction category

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

currency

• type: string
• Description: Currency of the transaction in ISO 4217 format

result

• type: string
• enum
• required
• Description: Transaction result

APPROVED, DECLINED

method_attributes

• required
• Description: Method-specific attributes

AchMethodAttributes, WireMethodAttributes

AchMethodAttributes

• type: object

• financial_account_token

  • type: uuid
  • required
  • Description: Financial account token

• external_bank_account_token

  • type: uuid | null
  • Description: External bank account token

• direction

  • type: string
  • enum
  • required
  • Description: Transfer direction

CREDIT, DEBIT

• source
  • type: string
  • enum
  • required
  • Description: Transaction source

LITHIC, EXTERNAL, CUSTOMER

• method
  • type: string
  • enum
  • required
  • Description: Transfer method

ACH_NEXT_DAY, ACH_SAME_DAY, WIRE

• settled_amount

  • type: integer
  • required
  • Description: Settled amount in cents

• pending_amount

  • type: integer
  • required
  • Description: Pending amount in cents

• events

  • type: array of objects
  • required
  • Description: List of transaction events

events* (object)

Payment Event

• amount

  • type: integer
  • required
  • Description: Amount of the financial event that has been settled in the currency's smallest unit (e.g., cents).

• created

  • type: date-time
  • required
  • Description: Date and time when the financial event occurred. UTC time zone.

• detailed_results

  • type: array of strings
  • Description: More detailed reasons for the event

APPROVED, DECLINED, FUNDS_INSUFFICIENT, ACCOUNT_INVALID, PROGRAM_TRANSACTION_LIMIT_EXCEEDED, PROGRAM_DAILY_LIMIT_EXCEEDED, PROGRAM_MONTHLY_LIMIT_EXCEEDED

• result
  • type: string
  • enum
  • required
  • Description: Approved financial events were successful while Declined financial events were declined by user, Lithic, or the network.

APPROVED, DECLINED

• token

  • type: uuid
  • required
  • Description: Globally unique identifier.

• type

  • type: string
  • enum
  • required
  • Description: Note: Inbound wire transfers are coming soon (availability varies by partner bank). Wire-related event types below are a preview. To learn more, contact your customer success manager.

Event types:

ACH events:

• ACH_ORIGINATION_INITIATED - ACH origination received and pending approval/release from an ACH hold.
• ACH_ORIGINATION_REVIEWED - ACH origination has completed the review process.
• ACH_ORIGINATION_CANCELLED - ACH origination has been cancelled.
• ACH_ORIGINATION_PROCESSED - ACH origination has been processed and sent to the Federal Reserve.
• ACH_ORIGINATION_SETTLED - ACH origination has settled.
• ACH_ORIGINATION_RELEASED - ACH origination released from pending to available balance.
• ACH_ORIGINATION_REJECTED - ACH origination was rejected and not sent to the Federal Reserve.
• ACH_RECEIPT_PROCESSED - ACH receipt pending release from an ACH holder.
• ACH_RECEIPT_SETTLED - ACH receipt funds have settled.
• ACH_RECEIPT_RELEASED - ACH receipt released from pending to available balance.
• ACH_RECEIPT_RELEASED_EARLY - ACH receipt released early from pending to available balance.
• ACH_RETURN_INITIATED - ACH initiated return for an ACH receipt.
• ACH_RETURN_PROCESSED - ACH receipt returned by the Receiving Depository Financial Institution.
• ACH_RETURN_SETTLED - ACH return settled by the Receiving Depository Financial Institution.
• ACH_RETURN_REJECTED - ACH return was rejected by the Receiving Depository Financial Institution.

Wire transfer events:

• WIRE_TRANSFER_INBOUND_RECEIVED - Inbound wire transfer received from the Federal Reserve and pending release to available balance.
• WIRE_TRANSFER_INBOUND_SETTLED - Inbound wire transfer funds released from pending to available balance.
• WIRE_TRANSFER_INBOUND_BLOCKED - Inbound wire transfer blocked and funds frozen for regulatory review.

Wire return events:

• WIRE_RETURN_OUTBOUND_INITIATED - Outbound wire return initiated to return funds from an inbound wire transfer.
• WIRE_RETURN_OUTBOUND_SENT - Outbound wire return sent to the Federal Reserve and pending acceptance.
• WIRE_RETURN_OUTBOUND_SETTLED - Outbound wire return accepted by the Federal Reserve and funds returned to sender.
• WIRE_RETURN_OUTBOUND_REJECTED - Outbound wire return rejected by the Federal Reserve.

ACH_ORIGINATION_CANCELLED, ACH_ORIGINATION_INITIATED, ACH_ORIGINATION_PROCESSED, ACH_ORIGINATION_REJECTED, ACH_ORIGINATION_RELEASED, ACH_ORIGINATION_REVIEWED, ACH_ORIGINATION_SETTLED, ACH_RECEIPT_PROCESSED, ACH_RECEIPT_RELEASED, ACH_RECEIPT_RELEASED_EARLY, ACH_RECEIPT_SETTLED, ACH_RETURN_INITIATED, ACH_RETURN_PROCESSED, ACH_RETURN_REJECTED, ACH_RETURN_SETTLED, WIRE_TRANSFER_INBOUND_RECEIVED, WIRE_TRANSFER_INBOUND_SETTLED, WIRE_TRANSFER_INBOUND_BLOCKED, WIRE_RETURN_OUTBOUND_INITIATED, WIRE_RETURN_OUTBOUND_SENT, WIRE_RETURN_OUTBOUND_SETTLED, WIRE_RETURN_OUTBOUND_REJECTED

external_id

• type: string | null
• 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).

descriptor

• type: string
• required
• Description: Transaction descriptor

user_defined_id

• type: string | null
• Description: User-defined identifier

expected_release_date

• type: date | null
• Description: Expected release date for the transaction

related_account_tokens

• required
• Description: Related account tokens for the transaction

Related Account Tokens

• type: object

• type

  • type: string
  • enum

ORIGINATION_CREDIT, ORIGINATION_DEBIT, RECEIPT_CREDIT, RECEIPT_DEBIT, WIRE_INBOUND_PAYMENT, WIRE_INBOUND_ADMIN, WIRE_OUTBOUND_PAYMENT, WIRE_OUTBOUND_ADMIN, WIRE_INBOUND_DRAWDOWN_REQUEST

tags

• type: object
• Description: Key-value pairs for tagging resources. Tags allow you to associate arbitrary metadata with a resource for your own purposes.

Has additional fields

balance

• type: object

• available_amount

  • type: integer
  • required
  • Description: Funds available for spend in the currency's smallest unit (e.g., cents for USD)

• created

  • type: date-time
  • required
  • Description: Date and time for when the balance was first created.

• currency

  • type: string
  • required
  • Description: 3-character alphabetic ISO 4217 code for the local currency of the balance.

• financial_account_token

  • type: uuid
  • required
  • Description: Globally unique identifier for the financial account that holds this balance.

• financial_account_type

  • type: string
  • enum
  • required
  • Description: Type of financial account.

CARD, ISSUING, OPERATING, PROGRAM_RECEIVABLES, RESERVE, SECURITY

• last_transaction_event_token

  • type: uuid | null
  • required
  • Description: Globally unique identifier for the last financial transaction event that impacted this balance.

• last_transaction_token

  • type: uuid | null
  • required
  • Description: Globally unique identifier for the last financial transaction that impacted this balance.

• pending_amount

  • type: integer
  • required
  • Description: Funds not available for spend due to card authorizations or pending ACH release. Shown in the currency's smallest unit (e.g., cents for USD).

• total_amount

  • type: integer
  • required
  • Description: The sum of available and pending balance in the currency's smallest unit (e.g., cents for USD).

• updated

  • type: date-time
  • required
  • Description: Date and time for when the balance was last updated.