Base class for all transaction types in the ledger service

Properties

event_type

• Type: const, enum
• Required: Yes
• Description: The type of event that occurred.
  • Allowed: book_transfer_transaction.updated

status

• Type: string, enum
• Required: Yes
• Description: The status of the transaction
  • Allowed: PENDING, SETTLED, DECLINED, REVERSED, CANCELED, RETURNED

token

• Type: uuid
• Required: Yes
• Description: Unique identifier for the transaction

created

• Type: date-time
• Required: Yes
• Description: ISO 8601 timestamp of when the transaction was created

updated

• Type: date-time
• Required: Yes
• Description: ISO 8601 timestamp of when the transaction was last updated

family

• Type: const, enum
• Required: Yes
• Description: TRANSFER - Book Transfer Transaction
  • Allowed: TRANSFER

result

• Type: string, enum
• Required: Yes
• Description:
  • Allowed: APPROVED, DECLINED

category

• Type: string, enum
• Required: Yes
• Description:
  • Allowed: ADJUSTMENT, BALANCE_OR_FUNDING, DERECOGNITION, DISPUTE, FEE, INTERNAL, REWARD, PROGRAM_FUNDING, TRANSFER

currency

• Type: string
• Required: Yes
• Description: 3-character alphabetic ISO 4217 code for the settling currency of the transaction

settled_amount

• Type: integer
• Required: Yes
• Description: Amount of the transaction that has been settled in the currency's smallest unit (e.g., cents)

pending_amount

• Type: integer
• Required: Yes
• Description: Pending amount of the transaction in the currency's smallest unit (e.g., cents), including any acquirer fees. The value of this field will go to zero over time once the financial transaction is settled.

events

• Type: array of objects
• Required: Yes
• Description: A list of all financial events that have modified this transfer

events[*]

• Type: object
  • Description: Book transfer Event
  • Properties:
    • amount:
      • Type: integer
      • Required: Yes
      • Description: Amount of the financial event that has been settled in the currency's smallest unit (e.g., cents).
    • type:
      • Type: string, enum
      • Required: Yes
      • Description: Type of the book transfer
        • Allowed: 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, PAYMENT_FEE, CASH_BACK, ACCOUNT_TO_ACCOUNT, CARD_TO_CARD, DISBURSE, BILLING_ERROR, LOSS_WRITE_OFF, EXPIRED_CARD, EARLY_DERECOGNITION, SCHEATMENT, INACTIVITY_FEE_DOWN, PROVISIONAL_CREDIT, DISPUTE_WON, SERVICE_TRANSFER, COLLECTION
    • result:
      • Type: string, enum
      • Required: Yes
      • Description: Accepted values.
        • Allowed: APPROVED, DECLINED
    • created:
      • Type: date-time
      • Required: Yes
      • Description: Date and time when the financial event occurred. UTC time zone.
    • token:
      • Type: uuid
      • Required: Yes
      • Description: Globally unique identifier.
    • subtype:
      • Type: string
      • Required: Yes
      • Description: The program specific subtype code for the specified category/type.
    • memo:
      • Type: string
      • Required: Yes
      • Description: Memo for the transfer.
    • detailed_results:
      • Type: array of objects
      • Required: Yes
      • Allowed: APPROVED, FUNDS_INSUFFICIENT

from_financial_account_token

• Type: uuid
• Required: Yes
• Description: Globally unique identifier for the financial account or card that will send the funds. Accepted type dependent on the program's use case

to_financial_account_token

• Type: uuid
• Required: Yes
• Description: Globally unique identifier for the financial account or card that will receive the funds. Accepted type dependent on the program's use case

external_id

• Type: string, nullable
• Description: External ID defined by the customer

transaction_series

• Type: object
• Description: A series of transactions that are grouped together
  • Properties:
    • external_resource:
      • Type: object
      • Description: An external resource associated with the transfer

external_resource

• Type: object
• Required: Yes
• Description: Details associated with the transfer
  • external_resource_type : string
  • external_resource_token : string
  • external_resource_sub_token : string

Response Example

{
  "status": "PENDING",
  "token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "created": "2026-07-18T00:26:00.313Z",
  "updated": "2026-07-18T00:26:00.313Z",
  "family": "string",
  "result": "APPROVED",
  "category": "ADJUSTMENT",
  "currency": "USD",
  "settled_amount": 500,
  "pending_amount": 1000,
  "events": [
    {
      "amount": 0,
      "type": "ATM_BALANCE_INQUIRY",
      "result": "APPROVED",
      "created": "2026-07-18T00:26:00.313Z",
      "token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "subtype": "string",
      "memo": "string",
      "detailed_results": [
        "APPROVED"
      ]
    }
  ],
  "from_financial_account_token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "to_financial_account_token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "external_id": "string",
  "transaction_series": {
    "type": "FEE",
    "related_transaction_token": "123e4567-e89b-12d3-a456-426614174000",
    "related_transaction_event_token": "123e4567-e89b-12d3-a456-426614174000"
  },
  "external_resource": {
    "external_resource_type": "STATEMENT",
    "external_resource_token": "string",
    "external_resource_sub_token": "string"
  },
  "event_type": "book_transfer_transaction.updated"
}