Transfer funds within Lithic

Transfer Schema

This schema describes the parameters for a transfer transaction.

Parameters

amount
Type: integer
Required: Yes
Amount to be transferred in the currency’s smallest unit (e.g., cents for USD). This should always be a positive value.
from
Type: uuid
Required: Yes
Globally unique identifier for the financial account or card that will send the funds. Accepted type dependent on the program's use case.
memo
Type: string
Required: No
Optional descriptor for the transfer.
to
Type: uuid
Required: Yes
Globally unique identifier for the financial account or card that will receive the funds. Accepted type dependent on the program's use case.
token
Type: uuid
Required: Yes
Customer-provided token that will serve as an idempotency token. This token will become the transaction token.

Success Response

`200 OK`

Type: object

category
Type: string
Enum:
Status types:
- TRANSFER - Internal transfer of funds between financial accounts in your program.
created
Type: date-time
Date and time when the transfer occurred. UTC time zone.
currency
Type: string
3-character alphabetic ISO 4217 code for the settling currency of the transaction.
descriptor
Type: string
A string that provides a description of the transfer; may be useful to display to users.
events
Type: array of objects
A list of all financial events that have modified this transfer.
event
Type: object
Financial Event
- amount
  Type: integer
  Amount of the financial event that has been settled in the currency's smallest unit (e.g., cents).
- created
  Type: date-time
  Date and time when the financial event occurred. UTC time zone.
- result
  Type: string
  Enum:
  APPROVED | DECLINED
- token
  Type: uuid
  Globally unique identifier.
- type
  Type: string
  Enum for specific event types (e.g., TRANSFER, AUTHORIZATION, etc.).
from_balance
Type: array of objects
The updated balance of the sending financial account.
- balance
  Type: object
  - available_amount
    Type: integer
    Required: Yes
    Funds available for spend in the currency's smallest unit.
  - created
    Type: date-time
    Required: Yes
    Date and time when the balance was first created.
  - currency
    Type: string
    Required: Yes
    3-character alphabetic ISO 4217 code for the local currency of the balance.
  - financial_account_token
    Type: uuid
    Required: Yes
    Globally unique identifier for the financial account that holds this balance.
  - financial_account_type
    Type: string
    Required: Yes
    Type of financial account (e.g., CARD, ISSUING).
  - last_transaction_event_token
    Type: uuid | null
    Required: Yes
    Globally unique identifier for the last financial transaction event that impacted this balance.
  - last_transaction_token
    Type: uuid | null
    Required: Yes
    Globally unique identifier for the last financial transaction that impacted this balance.
  - pending_amount
    Type: integer
    Required: Yes
    Funds not available for spend due to card authorizations or pending ACH release.
  - total_amount
    Type: integer
    Required: Yes
    The sum of available and pending balance.
  - updated
    Type: date-time
    Required: Yes
    Date and time when the balance was last updated.
pending_amount
Type: integer
Pending amount of the transaction in the currency's smallest unit.
result
Type: string
Enum:
APPROVED | DECLINED
settled_amount
Type: integer
Amount of the transaction that has been settled in the currency's smallest unit.
status
Type: string
Enum for status types (e.g., SETTLED, PENDING).
to_balance
Type: array of objects
The updated balance of the receiving financial account.
- balance
  Type: object (similar structure as from_balance)
token
Type: uuid
Globally unique identifier for the transfer event.
updated
Type: date-time
Date and time when the financial transaction was last updated.

Error Responses

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 or invalid API key.
404
The specified resource was not found.
429
Client has exceeded the number of allowed requests in a given time period.

Example Curl Request

curl --request POST \
     --url https://sandbox.lithic.com/v1/transfer \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{  \
       "amount": 0,  \
       "from": "3fa85f64-5717-4562-b3fc-2c963f66afa6",  \
       "memo": "string",  \
       "to": "3fa85f64-5717-4562-b3fc-2c963f66afa6",  \
       "token": "3fa85f64-5717-4562-b3fc-2c963f66afa6"  \
     }'

Example JSON Response

{  
  "category": "TRANSFER",  
  "created": "2026-07-18T00:25:15.297Z",  
  "currency": "string",  
  "descriptor": "string",  
  "events": [{  
    "amount": 0,  
    "created": "2026-07-18T00:25:15.297Z",  
    "result": "APPROVED",  
    "token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",  
    "type": "ACH_ORIGINATION_CANCELLED"  
  }],  
  "from_balance": [{  
    "available_amount": 0,  
    "created": "2026-07-18T00:25:15.297Z",  
    "currency": "string",  
    "financial_account_token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",  
    "financial_account_type": "CARD",  
    "last_transaction_event_token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",  
    "last_transaction_token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",  
    "pending_amount": 0,  
    "total_amount": 0,  
    "updated": "2026-07-18T00:25:15.297Z"  
  }],  
  "pending_amount": 0,  
  "result": "APPROVED",  
  "settled_amount": 0,  
  "status": "DECLINED",  
  "to_balance": [{  
    "available_amount": 0,  
    "created": "2026-07-18T00:25:15.297Z",  
    "currency": "string",  
    "financial_account_token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",  
    "financial_account_type": "CARD",  
    "last_transaction_event_token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",  
    "last_transaction_token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",  
    "pending_amount": 0,  
    "total_amount": 0,  
    "updated": "2026-07-18T00:25:15.297Z"  
  }],  
  "token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",  
  "updated": "2026-07-18T00:25:15.297Z"  
}