payment_token

uuid

required

200 OK

object

Base class for all transaction types in the ledger service

status

string

enum

required

The status of the transaction

PENDING``SETTLED``DECLINED``REVERSED``CANCELED``RETURNED

token

uuid

required

Unique identifier for the transaction

created

date-time

required

ISO 8601 timestamp of when the transaction was created

updated

date-time

required

ISO 8601 timestamp of when the transaction was last updated

family

const

enum

required

PAYMENT - Payment Transaction

PAYMENT

category

string

enum

required

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

string

Currency of the transaction in ISO 4217 format

result

string

enum

required

Transaction result

APPROVED``DECLINED

method_attributes

required

Method-specific attributes

AchMethodAttributesWireMethodAttributes AchMethodAttributes object

financial_account_token

uuid

required

Financial account token

external_bank_account_token

uuid | null

External bank account token

direction

string

enum

required

Transfer direction

CREDIT``DEBIT

source

string

enum

required

Transaction source

LITHIC``EXTERNAL``CUSTOMER

method

string

enum

required

Transfer method

ACH_NEXT_DAY``ACH_SAME_DAY``WIRE

settled_amount

integer

required

Settled amount in cents

pending_amount

integer

required

Pending amount in cents

events

array of objects

required

List of transaction events

events*

object

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

amount

integer

required

Amount of the financial event that has been settled in the currency's smallest unit (e.g., cents).

created

date-time

required

Date and time when the financial event occurred. UTC time zone.

detailed_results

array of strings

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

string

enum

required

APPROVED financial events were successful while DECLINED financial events were declined by user, Lithic, or the network.

APPROVED``DECLINED

token

uuid

required

Globally unique identifier.

type

string

enum

required

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

string | null

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

string

required

Transaction descriptor

user_defined_id

string | null

User-defined identifier

expected_release_date

date | null

Expected release date for the transaction

related_account_tokens

required

Related account tokens for the transaction

Related Account Tokensnull Related Account Tokens object

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

object

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

Has additional fields

`400 A parameter in the query given in the request does not match the valid queries for the endpoint.

`401 | | | | --- | --- | | User has not been authenticated | Invalid or missing API key | | API key is not active | The API key used is no longer active | | Could not find API key | The API key provided is not associated with any user | | Please provide API key in Authorization header | The Authorization header is not in the request | | Please provide API key in the form Authorization: [api-key] | The Authorization header is not formatted properly | | Insufficient privileges. Issuing API key required | Write access requires an Issuing API key. Reach out at lithic.com/contact | | Insufficient privileges to create virtual cards. | Creating virtual cards requires an additional privilege |

`404 The specified resource was not found.

`429 Client has exceeded the number of allowed requests in a given time period. | | | | --- | --- | | Rate limited, too many requests per second | User has exceeded their per second rate limit | | Rate limited, reached daily limit | User has exceeded their daily rate limit | | Rate limited, too many keys tried | One IP has queried too many different API keys |

Updated 3 months ago

ShellNodeRubyPHPPython

xxxxxxxxxx

curl --request GET \
     --url https://sandbox.lithic.com/v1/payments/payment_token \
     --header 'accept: application/json'

xxxxxxxxxx

{

"status": "PENDING",

"token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",

"created": "2026-07-18T00:25:39.662Z",

"updated": "2026-07-18T00:25:39.662Z",

"family": "string",

"category": "ACH",

"currency": "USD",

"result": "APPROVED",

"method_attributes": {
    "sec_code": "CCD",
    "return_reason_code": "string",
    "ach_hold_period": 0,
    "retries": 0,
    "company_id": "string",
    "receipt_routing_number": "string",
    "trace_numbers": [\
      "string"\\n    ],
    "addenda": "string",
    "override_company_name": "string"
  },

"financial_account_token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",

"external_bank_account_token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",

"direction": "CREDIT",

"source": "LITHIC",

"method": "ACH_NEXT_DAY",

"settled_amount": 500,

"pending_amount": 200,

"events": [\
    {\
      "amount": 0,\
      "created": "2026-07-18T00:25:39.662Z",\
      "detailed_results": [\
        "APPROVED"\
      ],\
      "result": "APPROVED",\
      "token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",\
      "type": "ACH_ORIGINATION_CANCELLED",\
      "external_id": "string"\
    }\
  ],

"descriptor": "string",

"user_defined_id": "string",

"expected_release_date": "2026-07-18",

"related_account_tokens": {
    "business_account_token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "account_token": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  },

"type": "ORIGINATION_CREDIT",

"tags": {
    "risk-level": "high"
  }
}