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 Book Transfer API version: 1.0.0 servers: - description: Sandbox environment that provides key functionality mirroring production url: https://sandbox.lithic.com security: - ApiKeyAuth: [] tags: - name: Book Transfer paths: /v1/transfer: post: deprecated: true description: Transfer funds between two financial accounts or between a financial account and card operationId: postTransfer requestBody: content: application/json: schema: properties: amount: description: Amount to be transferred in the currency’s smallest unit (e.g., cents for USD). This should always be a positive value. type: integer from: description: Globally unique identifier for the financial account or card that will send the funds. Accepted type dependent on the program's use case. format: uuid type: string memo: description: Optional descriptor for the transfer. type: string to: description: Globally unique identifier for the financial account or card that will receive the funds. Accepted type dependent on the program's use case. format: uuid type: string token: description: Customer-provided token that will serve as an idempotency token. This token will become the transaction token. format: uuid type: string required: - amount - from - to type: object required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/Transfer' description: OK '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/TooManyRequests' summary: Transfer funds within Lithic tags: - Book Transfer /v1/book_transfers: get: description: List book transfers parameters: - description: Book Transfer category to be returned. in: query name: category schema: $ref: '#/components/schemas/book_transfer_category' - description: Globally unique identifier for the financial account or card that will send the funds. Accepted type dependent on the program's use case. in: query name: financial_account_token schema: format: uuid type: string - in: query name: business_account_token required: false schema: format: uuid title: Business Account Token type: string - in: query name: account_token required: false schema: format: uuid title: Account Token type: string - description: Book transfer result to be returned. in: query name: result schema: enum: - APPROVED - DECLINED type: string - description: Book transfer status to be returned. in: query name: status schema: enum: - DECLINED - SETTLED type: string - $ref: '#/components/parameters/beginTime' - $ref: '#/components/parameters/endingBefore' - $ref: '#/components/parameters/endTime' - $ref: '#/components/parameters/pageSize' - $ref: '#/components/parameters/startingAfter' operationId: getBookTransfers responses: '200': content: application/json: schema: properties: data: items: $ref: '#/components/schemas/book-transfer-transaction' title: Data type: array has_more: title: 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' '429': $ref: '#/components/responses/TooManyRequests' summary: List book transfers tags: - Book Transfer post: description: Book transfer funds between two financial accounts or between a financial account and card operationId: postBookTransfers requestBody: content: application/json: schema: $ref: '#/components/schemas/create_book_transfer_request' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/book-transfer-transaction' description: OK '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/TooManyRequests' summary: Create book transfer tags: - Book Transfer /v1/book_transfers/{book_transfer_token}: get: description: Get book transfer by token parameters: - description: Id of the book transfer to retrieve in: path name: book_transfer_token required: true schema: format: uuid type: string operationId: getBookTransfer responses: '200': content: application/json: schema: $ref: '#/components/schemas/book-transfer-transaction' description: OK '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/TooManyRequests' summary: Get book transfer by token tags: - Book Transfer /v1/book_transfers/{book_transfer_token}/retry: post: description: Retry a book transfer that has been declined parameters: - description: Token of the book transfer to retry in: path name: book_transfer_token required: true schema: format: uuid type: string operationId: retryBookTransfer requestBody: content: application/json: schema: $ref: '#/components/schemas/retry_book_transfer_request' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/book-transfer-transaction' description: OK '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/TooManyRequests' summary: Retry book transfer tags: - Book Transfer /v1/book_transfers/{book_transfer_token}/reverse: post: description: Reverse a book transfer parameters: - description: Id of the book transfer to retrieve in: path name: book_transfer_token required: true schema: format: uuid type: string operationId: reverseBookTransfer requestBody: content: application/json: schema: properties: memo: description: Optional descriptor for the reversal. type: string maxLength: 512 type: object required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/book-transfer-transaction' description: OK '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/TooManyRequests' summary: Reverse book transfer tags: - Book Transfer 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 book-transfer-transaction: title: Book Transfer Transaction description: Book transfer transaction allOf: - $ref: '#/components/schemas/base_transaction' - type: object properties: family: type: string const: TRANSFER description: TRANSFER - Book Transfer Transaction result: $ref: '#/components/schemas/transaction_result' category: $ref: '#/components/schemas/book_transfer_category' currency: type: string description: 3-character alphabetic ISO 4217 code for the settling currency of the transaction example: USD settled_amount: type: integer description: Amount of the transaction that has been settled in the currency's smallest unit (e.g., cents) example: 500 pending_amount: type: integer 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. ' example: 1000 events: type: array items: $ref: '#/components/schemas/book_transfer_event' description: A list of all financial events that have modified this transfer from_financial_account_token: type: string format: uuid 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: string format: uuid 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: description: External ID defined by the customer oneOf: - type: string - type: 'null' transaction_series: description: A series of transactions that are grouped together oneOf: - $ref: '#/components/schemas/transaction_series' - type: 'null' external_resource: description: An external resource associated with the transfer oneOf: - $ref: '#/components/schemas/external_resource' - type: 'null' required: - family - result - category - currency - settled_amount - pending_amount - events - from_financial_account_token - to_financial_account_token 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 retry_book_transfer_request: title: Retry Book Transfer Request type: object properties: retry_token: description: Customer-provided token that will serve as an idempotency token. This token will become the transaction token. format: uuid type: string required: - retry_token external_resource_type: title: ExternalResourceType type: string enum: - STATEMENT - COLLECTION - DISPUTE - UNKNOWN description: Type of external resource associated with the management operation 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 financial_event_type: title: Financial Event Type type: string enum: - ACH_ORIGINATION_CANCELLED - ACH_ORIGINATION_INITIATED - ACH_ORIGINATION_PROCESSED - ACH_ORIGINATION_RELEASED - ACH_ORIGINATION_REJECTED - ACH_ORIGINATION_REVIEWED - ACH_ORIGINATION_SETTLED - ACH_RECEIPT_PROCESSED - ACH_RECEIPT_RELEASED - ACH_RECEIPT_SETTLED - ACH_RETURN_INITIATED - ACH_RETURN_PROCESSED - ACH_RETURN_REJECTED - ACH_RETURN_SETTLED - AUTHORIZATION - AUTHORIZATION_ADVICE - AUTHORIZATION_EXPIRY - AUTHORIZATION_REVERSAL - BALANCE_INQUIRY - BILLING_ERROR - BILLING_ERROR_REVERSAL - CARD_TO_CARD - CASH_BACK - CASH_BACK_REVERSAL - CLEARING - COLLECTION - CORRECTION_CREDIT - CORRECTION_DEBIT - CREDIT_AUTHORIZATION - CREDIT_AUTHORIZATION_ADVICE - CURRENCY_CONVERSION - CURRENCY_CONVERSION_REVERSAL - DISPUTE_WON - EXTERNAL_ACH_CANCELED - EXTERNAL_ACH_INITIATED - EXTERNAL_ACH_RELEASED - EXTERNAL_ACH_REVERSED - EXTERNAL_ACH_SETTLED - EXTERNAL_CHECK_CANCELED - EXTERNAL_CHECK_INITIATED - EXTERNAL_CHECK_RELEASED - EXTERNAL_CHECK_REVERSED - EXTERNAL_CHECK_SETTLED - EXTERNAL_FEDNOW_CANCELED - EXTERNAL_FEDNOW_INITIATED - EXTERNAL_FEDNOW_RELEASED - EXTERNAL_FEDNOW_REVERSED - EXTERNAL_FEDNOW_SETTLED - EXTERNAL_RTP_CANCELED - EXTERNAL_RTP_INITIATED - EXTERNAL_RTP_RELEASED - EXTERNAL_RTP_REVERSED - EXTERNAL_RTP_SETTLED - EXTERNAL_TRANSFER_CANCELED - EXTERNAL_TRANSFER_INITIATED - EXTERNAL_TRANSFER_RELEASED - EXTERNAL_TRANSFER_REVERSED - EXTERNAL_TRANSFER_SETTLED - EXTERNAL_WIRE_CANCELED - EXTERNAL_WIRE_INITIATED - EXTERNAL_WIRE_RELEASED - EXTERNAL_WIRE_REVERSED - EXTERNAL_WIRE_SETTLED - FINANCIAL_AUTHORIZATION - FINANCIAL_CREDIT_AUTHORIZATION - INTEREST - INTEREST_REVERSAL - INTERNAL_ADJUSTMENT - LATE_PAYMENT - LATE_PAYMENT_REVERSAL - LOSS_WRITE_OFF - PROVISIONAL_CREDIT - PROVISIONAL_CREDIT_REVERSAL - SERVICE - RETURN - RETURN_REVERSAL - TRANSFER - TRANSFER_INSUFFICIENT_FUNDS - RETURNED_PAYMENT - RETURNED_PAYMENT_REVERSAL - LITHIC_NETWORK_PAYMENT - ANNUAL - ANNUAL_REVERSAL - QUARTERLY - QUARTERLY_REVERSAL - MONTHLY - MONTHLY_REVERSAL transaction_status: title: Transaction Status type: string enum: - PENDING - SETTLED - DECLINED - REVERSED - CANCELED - RETURNED financial_event: title: Financial Event description: Financial 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 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/financial_event_type' on_closed_account: title: On Closed Account description: What to do if the financial account is closed when posting an operation type: string enum: - FAIL - USE_SUSPENSE default: FAIL transaction_result: title: Transaction Result type: string enum: - APPROVED - DECLINED transaction_series: title: Transaction Series type: object properties: type: type: string example: FEE related_transaction_token: oneOf: - type: string format: uuid example: 123e4567-e89b-12d3-a456-426614174000 - type: 'null' related_transaction_event_token: oneOf: - type: string format: uuid example: 123e4567-e89b-12d3-a456-426614174000 - type: 'null' required: - type - related_transaction_token - related_transaction_event_token create_book_transfer_request: title: Create Book Transfer Request type: object properties: amount: description: Amount to be transferred in the currency's smallest unit (e.g., cents for USD). This should always be a positive value. type: integer minimum: 1 category: $ref: '#/components/schemas/book_transfer_category' from_financial_account_token: description: Globally unique identifier for the financial account or card that will send the funds. Accepted type dependent on the program's use case. format: uuid type: string memo: description: Optional descriptor for the transfer. type: string maxLength: 512 subtype: description: The program specific subtype code for the specified category/type. type: string to_financial_account_token: description: Globally unique identifier for the financial account or card that will receive the funds. Accepted type dependent on the program's use case. format: uuid type: string token: description: Customer-provided token that will serve as an idempotency token. This token will become the transaction token. format: uuid type: string type: $ref: '#/components/schemas/book_transfer_type' external_id: description: External ID defined by the customer type: string on_closed_account: $ref: '#/components/schemas/on_closed_account' hold_token: description: Token of an existing hold to settle when this transfer is initiated format: uuid type: string required: - amount - category - from_financial_account_token - subtype - to_financial_account_token - type error: type: object properties: debugging_request_id: type: string format: uuid description: Identifier to help debug an error. message: type: string description: Explanation of error response. required: - debugging_request_id - message book_transfer_event: title: Book Transfer Event description: Book transfer 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 type: $ref: '#/components/schemas/book_transfer_type' result: description: APPROVED financial events were successful while DECLINED financial events were declined by user, Lithic, or the network. type: string enum: - APPROVED - DECLINED created: description: Date and time when the financial event occurred. UTC time zone. type: string format: date-time token: description: Globally unique identifier. type: string format: uuid subtype: description: The program specific subtype code for the specified category/type. type: string memo: description: Memo for the transfer. type: string detailed_results: type: array items: $ref: '#/components/schemas/book_transfer_detailed_results' required: - amount - type - result - created - token - subtype - memo - detailed_results Transfer: properties: category: description: 'Status types: * `TRANSFER` - Internal transfer of funds between financial accounts in your program. ' enum: - TRANSFER type: string created: description: Date and time when the transfer occurred. UTC time zone. format: date-time type: string currency: description: 3-character alphabetic ISO 4217 code for the settling currency of the transaction. type: string descriptor: description: A string that provides a description of the transfer; may be useful to display to users. type: string events: description: A list of all financial events that have modified this trasnfer. items: $ref: '#/components/schemas/financial_event' type: array from_balance: description: The updated balance of the sending financial account. items: $ref: '#/components/schemas/balance' type: array pending_amount: 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. ' type: integer result: description: APPROVED transactions were successful while DECLINED transactions were declined by user, Lithic, or the network. enum: - APPROVED - DECLINED type: string settled_amount: description: Amount of the transaction that has been settled in the currency's smallest unit (e.g., cents). type: integer status: description: 'Status types: * `DECLINED` - The transfer was declined. * `EXPIRED` - The transfer was held in pending for too long and expired. * `PENDING` - The transfer is pending release from a hold. * `SETTLED` - The transfer is completed. * `VOIDED` - The transfer was reversed before it settled. ' enum: - DECLINED - EXPIRED - PENDING - SETTLED - VOIDED type: string to_balance: description: The updated balance of the receiving financial account. items: $ref: '#/components/schemas/balance' type: array token: description: Globally unique identifier for the transfer event. format: uuid type: string updated: description: Date and time when the financial transaction was last updated. UTC time zone. format: date-time type: string type: object balance: description: Balance properties: available_amount: description: Funds available for spend in the currency's smallest unit (e.g., cents for USD) type: integer created: description: Date and time for when the balance was first created. format: date-time type: string currency: description: 3-character alphabetic ISO 4217 code for the local currency of the balance. type: string financial_account_token: description: Globally unique identifier for the financial account that holds this balance. example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 format: uuid type: string financial_account_type: description: Type of financial account. enum: - ISSUING - OPERATING - RESERVE - SECURITY type: string last_transaction_event_token: description: Globally unique identifier for the last financial transaction event that impacted this balance. format: uuid type: string last_transaction_token: description: Globally unique identifier for the last financial transaction that impacted this balance. format: uuid type: string pending_amount: 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). type: integer total_amount: description: The sum of available and pending balance in the currency's smallest unit (e.g., cents for USD). type: integer updated: description: Date and time for when the balance was last updated. format: date-time type: string required: - available_amount - created - currency - financial_account_token - financial_account_type - last_transaction_event_token - last_transaction_token - pending_amount - total_amount - updated type: object book_transfer_detailed_results: title: Book Transfer Detailed Results type: string enum: - APPROVED - FUNDS_INSUFFICIENT book_transfer_category: title: Book Transfer Category type: string enum: - ADJUSTMENT - BALANCE_OR_FUNDING - DERECOGNITION - DISPUTE - FEE - INTERNAL - REWARD - PROGRAM_FUNDING - TRANSFER responses: BadRequest: content: application/json: schema: $ref: '#/components/schemas/error' description: A parameter in the query given in the request does not match the valid queries for the endpoint. NotFound: content: application/json: schema: $ref: '#/components/schemas/error' description: The specified resource was not found. Unauthorized: content: application/json: schema: $ref: '#/components/schemas/error' description: '| | | |---|---| | 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](https://lithic.com/contact) | | Insufficient privileges to create virtual cards. | Creating virtual cards requires an additional privilege | Reach out at [lithic.com/contact](https://lithic.com/contact) | ' TooManyRequests: content: application/json: schema: $ref: '#/components/schemas/error' description: '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 | ' parameters: startingAfter: description: A cursor representing an item's token after which a page of results should begin. Used to retrieve the next page of results after this item. in: query name: starting_after required: false schema: type: string endTime: description: Date string in RFC 3339 format. Only entries created before the specified time will be included. UTC time zone. in: query name: end schema: format: date-time type: string beginTime: description: Date string in RFC 3339 format. Only entries created after the specified time will be included. UTC time zone. in: query name: begin schema: format: date-time type: string endingBefore: description: A cursor representing an item's token before which a page of results should end. Used to retrieve the previous page of results before this item. in: query name: ending_before required: false schema: type: string pageSize: description: Page size (for pagination). in: query name: page_size schema: default: 50 maximum: 100 minimum: 1 type: integer securitySchemes: ApiKeyAuth: in: header name: Authorization type: apiKey