The External Payments API lets you record payment activity that happened outside of Lithic's own money-movement rails directly against a Financial Account. It acts as a ledger-recording mechanism: you tell Lithic that an amount moved in or out of a financial account through an external channel, and Lithic reflects that as a transaction with its own status, balance impact, and event history.

Use it to keep a financial account's balance in sync with money that moved on rails Lithic did not originate — for example a wire your bank processed directly, an ACH handled by another provider, or a paper check — and to backfill historical activity that is already resolved on the external side.

📘

External payments record money that moved elsewhere; they do not originate a payment. To move money on Lithic's rails, use Payments (ACH) or Book Transfers (internal).

Core concepts

Category

The category identifies the external rail the funds moved on:

Payment type

The payment_type sets the direction of funds relative to the financial account:

Status

An external payment carries a transaction status:

Events

Every state transition appends an event to the external payment's events array. Each event has its own type, result, amount, memo, and effective_date. Event types are named per category and per action, following the pattern {CATEGORY}_{ACTION}, where the action is one of INITIATED, SETTLED, RELEASED, CANCELED, or REVERSED — for example EXTERNAL_WIRE_INITIATED, EXTERNAL_ACH_SETTLED, or EXTERNAL_RTP_REVERSED.

📘

For a detailed walkthrough of the status lifecycle, including how each event affects pending and available balances, see ACH Payments Lifecycle.

Lifecycle

A newly created external payment records against the financial account and begins its lifecycle. From there you drive it toward a terminal state with the action endpoints:

• Settle confirms the external movement cleared on the bank's side and moves the payment to SETTLED.
• Release releases held funds so they become available balance — analogous to an ACH hold period ending and funds moving from pending to available.
• Cancel cancels a payment that has not settled yet — for example one booked in error, or where the external movement never actually happened — and moves it to CANCELED.
• Reverse unwinds a payment that had already settled — for example a wire that was recalled — and moves it to REVERSED.

For programs with a meaningful hold period, settle and release are distinct steps: settle confirms the movement cleared, and release governs pending-to-available balance timing. Programs without a hold period can collapse the two using progress_to (see below).

Advancing state

Normally an external payment moves through its lifecycle one step at a time: you create it, then call settle, then call release — each a separate API request. This mirrors how the money actually progresses on the external side.

Sometimes, though, you already know the payment is further along. When you record activity that has already cleared, or backfill historical payments that are fully resolved, replaying every intermediate step is unnecessary.

For those cases, the create and settle requests accept an optional progress_to parameter set to SETTLED or RELEASED. It tells Lithic to advance the payment straight to that state in a single call, generating the intermediate events along the way. For example, a create with progress_to: SETTLED books the payment and settles it at once, and a settle with progress_to: RELEASED settles and releases the funds together.

Endpoints

Create an external payment

POST https://api.lithic.com/v1/external_payments

Books a new external payment record against a financial account. See Create external payment for the full schema.

Get an external payment

GET https://api.lithic.com/v1/external_payments/{external_payment_token}

Fetch a single external payment by token, including its full events history. See Get external payment.

List external payments

GET https://api.lithic.com/v1/external_payments

List and filter external payments. See List external payments. Supported query parameters:

Settle, release, cancel, and reverse

Each action endpoint takes an effective_date (required) and an optional memo. The settle endpoint additionally accepts progress_to.

POST https://api.lithic.com/v1/external_payments/{external_payment_token}/settle

POST https://api.lithic.com/v1/external_payments/{external_payment_token}/release

POST https://api.lithic.com/v1/external_payments/{external_payment_token}/cancel

POST https://api.lithic.com/v1/external_payments/{external_payment_token}/reverse

📘

effective_date drives ledger and statement date logic, so it should reflect when the action is effective from an accounting standpoint — not necessarily today's date if you are backfilling historical records.

Response

An external payment response includes the transaction status, token, created, and updated timestamps, along with:

Idempotency

The optional token parameter on create lets you supply your own UUID, which becomes the transaction token. Passing the same token on a retried create call lets you safely retry without risking a duplicate booking.

Webhooks

Subscribe to these event types in the Events API to be notified of external payment activity:

• external_payment.created: an external payment was recorded
• external_payment.updated: an external payment was updated — for example settled, released, canceled, reversed, or returned