This page documents the possible lifecycle permutations of an External Payment that you can expect to see, with code examples. External Payments represent money movement between a Lithic financial account and an account held outside of Lithic, across a range of payment rails.

Compared to ACH payments, External Payment lifecycles are far less varied: every payment moves through the same small set of states regardless of the rail used. The two parameters that determine which lifecycle a payment follows are:

category — the payment rail (EXTERNAL_ACH, EXTERNAL_WIRE, EXTERNAL_CHECK, EXTERNAL_FEDNOW, EXTERNAL_RTP, EXTERNAL_TRANSFER)
payment_type — the direction of the money movement (DEPOSIT or WITHDRAWAL)

Typically, the type and result parameters within the event object are most important in understanding what has occurred to a given External Payment.

Possible enum values for category:

EXTERNAL_ACH: The payment is being made over the ACH network
EXTERNAL_WIRE: The payment is being made over a wire network
EXTERNAL_CHECK: The payment is being made by check
EXTERNAL_FEDNOW: The payment is being made over FedNow
EXTERNAL_RTP: The payment is being made over the RTP network
EXTERNAL_TRANSFER: The payment is being made as a generic external transfer

Possible enum values for payment_type:

DEPOSIT: Funds are moving into the Lithic financial account from an external account
WITHDRAWAL: Funds are moving out of the Lithic financial account to an external account

Possible enum values for event.type:

Every event type follows the pattern EXTERNAL_{RAIL}_{STATE}, where {RAIL} is one of ACH, WIRE, CHECK, FEDNOW, RTP, or TRANSFER, and {STATE} is one of the five lifecycle states below. The examples on this page use EXTERNAL_ACH_*, but the same states apply to every rail.

EXTERNAL_{RAIL}_INITIATED: Event indicates that the external payment was initiated via the API; for a withdrawal, funds are held (moved from available to pending) at this point, and for a deposit, funds are recorded as pending against internal accounts but not yet applied to the financial account
EXTERNAL_{RAIL}_SETTLED: Event indicates that the payment has settled on the underlying rail; for a withdrawal, the held funds leave the financial account, and for a deposit, funds are applied to the financial account in a pending state
EXTERNAL_{RAIL}_RELEASED: Event indicates that a deposit's pending funds have been released and are now available for use (applies to deposits only)
EXTERNAL_{RAIL}_CANCELED: Event indicates that the payment was canceled before it settled; only possible while the payment is in an initiated state
EXTERNAL_{RAIL}_REVERSED: Event indicates that a payment was reversed after it had settled (or, for deposits, released); all prior postings are rolled back

Possible enum values for result:

APPROVED: The event occurred with a successful outcome

External payment events always resolve to APPROVED. The result parameter shares an enum with other transaction types that also includes DECLINED, but that value does not surface for external payments.

Possible enum values for detailed_results:

APPROVED: No exceptional condition applies to the event

As with result, external payment events always return APPROVED here. The shared enum also includes INSUFFICIENT_FUNDS, but that value does not surface for external payments.

Withdrawals

A withdrawal moves funds out of a Lithic financial account to an external destination. When a withdrawal is initiated, Lithic places a hold on the funds by moving them from the available balance into the pending balance, preventing them from being spent elsewhere. Once the payment settles, the held funds leave the account. Unlike deposits, withdrawals do not have a released state — the happy path ends at the settled event.

Possible event.type sequences:

Sequence 1: Successful payment ("Happy Path")

A successful withdrawal contains two events at the end of its lifecycle: initiated and settled. At initiation the funds are held (moved from available to pending); at settlement the held funds leave the financial account.

{
  "family": "EXTERNAL_PAYMENT",
  "token": "6d5a2718-9b79-4473-aa1e-6bbf7433ea6f",
  "status": "SETTLED",
  "result": "APPROVED",
  "category": "EXTERNAL_ACH",
  "payment_type": "WITHDRAWAL",
  "financial_account_token": "6127238d-cb85-50bc-86aa-264654a11be9",
  "settled_amount": 10000,
  "pending_amount": 0,
  "currency": "USD",
  "user_defined_id": "1234",
  "events": [
    {
      "amount": 10000,
      "type": "EXTERNAL_ACH_INITIATED",
      "result": "APPROVED",
      "detailed_results": ["APPROVED"],
      "created": "2024-04-18T18:16:09Z",
      "token": "34c5b9d2-2d6a-540b-90fe-fa202b418242",
      "memo": "Vendor payment",
      "effective_date": "2024-04-18"
    },
    {
      "amount": 10000,
      "type": "EXTERNAL_ACH_SETTLED",
      "result": "APPROVED",
      "detailed_results": ["APPROVED"],
      "created": "2024-04-19T08:30:40Z",
      "token": "5f6255f8-4016-5e66-aedf-2e3c76027e04",
      "memo": "Vendor payment",
      "effective_date": "2024-04-19"
    }
  ],
  "created": "2024-04-18T18:16:09Z",
  "updated": "2024-04-19T16:38:22Z"
}

Sequence 2: Payment canceled before settlement

A withdrawal that is canceled while it is still in the initiated state contains two events: initiated and canceled. The canceled event rolls back the hold placed at initiation, restoring the financial account to its pre-payment state. A payment can only be canceled before it has settled.

{
  "family": "EXTERNAL_PAYMENT",
  "token": "6d5a2718-9b79-4473-aa1e-6bbf7433ea6f",
  "status": "CANCELED",
  "result": "APPROVED",
  "category": "EXTERNAL_ACH",
  "payment_type": "WITHDRAWAL",
  "financial_account_token": "6127238d-cb85-50bc-86aa-264654a11be9",
  "settled_amount": 0,
  "pending_amount": 0,
  "currency": "USD",
  "user_defined_id": "1234",
  "events": [
    {
      "amount": 10000,
      "type": "EXTERNAL_ACH_INITIATED",
      "result": "APPROVED",
      "detailed_results": ["APPROVED"],
      "created": "2024-04-18T18:16:09Z",
      "token": "34c5b9d2-2d6a-540b-90fe-fa202b418242",
      "memo": "Vendor payment",
      "effective_date": "2024-04-18"
    },
    {
      "amount": 0,
      "type": "EXTERNAL_ACH_CANCELED",
      "result": "APPROVED",
      "detailed_results": ["APPROVED"],
      "created": "2024-04-18T18:20:11Z",
      "token": "5f6255f8-4016-5e66-aedf-2e3c76027e04",
      "memo": "Vendor payment",
      "effective_date": "2024-04-18"
    }
  ],
  "created": "2024-04-18T18:16:09Z",
  "updated": "2024-04-18T18:20:11Z"
}

Sequence 3: Payment reversed after settlement

A withdrawal that is reversed after it has settled contains three events: initiated, settled, and reversed. The reversed event rolls back all prior postings, returning the funds to the financial account. A payment can only be reversed once it has settled.

{
  "family": "EXTERNAL_PAYMENT",
  "token": "6d5a2718-9b79-4473-aa1e-6bbf7433ea6f",
  "status": "REVERSED",
  "result": "APPROVED",
  "category": "EXTERNAL_ACH",
  "payment_type": "WITHDRAWAL",
  "financial_account_token": "6127238d-cb85-50bc-86aa-264654a11be9",
  "settled_amount": 0,
  "pending_amount": 0,
  "currency": "USD",
  "user_defined_id": "1234",
  "events": [
    {
      "amount": 10000,
      "type": "EXTERNAL_ACH_INITIATED",
      "result": "APPROVED",
      "detailed_results": ["APPROVED"],
      "created": "2024-04-18T18:16:09Z",
      "token": "34c5b9d2-2d6a-540b-90fe-fa202b418242",
      "memo": "Vendor payment",
      "effective_date": "2024-04-18"
    },
    {
      "amount": 10000,
      "type": "EXTERNAL_ACH_SETTLED",
      "result": "APPROVED",
      "detailed_results": ["APPROVED"],
      "created": "2024-04-19T08:30:40Z",
      "token": "5f6255f8-4016-5e66-aedf-2e3c76027e04",
      "memo": "Vendor payment",
      "effective_date": "2024-04-19"
    },
    {
      "amount": 0,
      "type": "EXTERNAL_ACH_REVERSED",
      "result": "APPROVED",
      "detailed_results": ["APPROVED"],
      "created": "2024-04-22T10:02:05Z",
      "token": "6fd208bc-1227-445d-a7c5-03e7e9cc15f9",
      "memo": "Vendor payment",
      "effective_date": "2024-04-22"
    }
  ],
  "created": "2024-04-18T18:16:09Z",
  "updated": "2024-04-22T10:02:05Z"
}

Withdrawal Balance Impacts

The below table shows if/how balances are impacted per transaction event for withdrawals from debit and prepaid accounts. The impacts are reversed for credit accounts.

`event.type`	Pending Balance	Available Balance
`EXTERNAL_*_INITIATED`	Increased	Decreased
`EXTERNAL_*_SETTLED`	Decreased	None
`EXTERNAL_*_CANCELED`	All postings rolled back	All postings rolled back
`EXTERNAL_*_REVERSED`	All postings rolled back	All postings rolled back

Deposits

A deposit moves funds into a Lithic financial account from an external account. When a deposit is initiated, the funds are recorded as pending against internal accounts but are not yet applied to the financial account. Once the payment settles, the funds are applied to the financial account in a pending state; once released, they become available for use.

Possible event.type sequences:

Sequence 1: Successful payment ("Happy Path")

A successful deposit contains three events at the end of its lifecycle: initiated, settled, and released. After the settled event the funds appear in the associated financial account with a pending status; after the released event they are made available for use.

{
  "family": "EXTERNAL_PAYMENT",
  "token": "6d5a2718-9b79-4473-aa1e-6bbf7433ea6f",
  "status": "SETTLED",
  "result": "APPROVED",
  "category": "EXTERNAL_ACH",
  "payment_type": "DEPOSIT",
  "financial_account_token": "6127238d-cb85-50bc-86aa-264654a11be9",
  "settled_amount": 10000,
  "pending_amount": 0,
  "currency": "USD",
  "user_defined_id": "1234",
  "events": [
    {
      "amount": 10000,
      "type": "EXTERNAL_ACH_INITIATED",
      "result": "APPROVED",
      "detailed_results": ["APPROVED"],
      "created": "2024-04-18T18:16:09Z",
      "token": "34c5b9d2-2d6a-540b-90fe-fa202b418242",
      "memo": "Customer deposit",
      "effective_date": "2024-04-18"
    },
    {
      "amount": 10000,
      "type": "EXTERNAL_ACH_SETTLED",
      "result": "APPROVED",
      "detailed_results": ["APPROVED"],
      "created": "2024-04-19T08:30:40Z",
      "token": "5f6255f8-4016-5e66-aedf-2e3c76027e04",
      "memo": "Customer deposit",
      "effective_date": "2024-04-19"
    },
    {
      "amount": 10000,
      "type": "EXTERNAL_ACH_RELEASED",
      "result": "APPROVED",
      "detailed_results": ["APPROVED"],
      "created": "2024-04-21T08:30:40Z",
      "token": "7eec03f2-2fac-4485-bc4b-0526d8bff3ba",
      "memo": "Customer deposit",
      "effective_date": "2024-04-21"
    }
  ],
  "created": "2024-04-18T18:16:09Z",
  "updated": "2024-04-21T08:30:40Z"
}

Depending on how the payment is progressed, a deposit may stop at the settled event, leaving the funds in a pending state (status: PENDING) until a subsequent released event makes them available.

Sequence 2: Payment canceled before settlement

A deposit that is canceled while it is still in the initiated state contains two events: initiated and canceled. The canceled event rolls back the postings made at initiation. A payment can only be canceled before it has settled.

{
  "family": "EXTERNAL_PAYMENT",
  "token": "6d5a2718-9b79-4473-aa1e-6bbf7433ea6f",
  "status": "CANCELED",
  "result": "APPROVED",
  "category": "EXTERNAL_ACH",
  "payment_type": "DEPOSIT",
  "financial_account_token": "6127238d-cb85-50bc-86aa-264654a11be9",
  "settled_amount": 0,
  "pending_amount": 0,
  "currency": "USD",
  "user_defined_id": "1234",
  "events": [
    {
      "amount": 10000,
      "type": "EXTERNAL_ACH_INITIATED",
      "result": "APPROVED",
      "detailed_results": ["APPROVED"],
      "created": "2024-04-18T18:16:09Z",
      "token": "34c5b9d2-2d6a-540b-90fe-fa202b418242",
      "memo": "Customer deposit",
      "effective_date": "2024-04-18"
    },
    {
      "amount": 0,
      "type": "EXTERNAL_ACH_CANCELED",
      "result": "APPROVED",
      "detailed_results": ["APPROVED"],
      "created": "2024-04-18T18:20:11Z",
      "token": "5f6255f8-4016-5e66-aedf-2e3c76027e04",
      "memo": "Customer deposit",
      "effective_date": "2024-04-18"
    }
  ],
  "created": "2024-04-18T18:16:09Z",
  "updated": "2024-04-18T18:20:11Z"
}

Sequence 3: Payment reversed after release

A deposit that is reversed after it has settled and released contains four events: initiated, settled, released, and reversed. The reversed event rolls back all prior postings, removing the funds from the financial account. A payment can only be reversed once it has settled.

{
  "family": "EXTERNAL_PAYMENT",
  "token": "6d5a2718-9b79-4473-aa1e-6bbf7433ea6f",
  "status": "REVERSED",
  "result": "APPROVED",
  "category": "EXTERNAL_ACH",
  "payment_type": "DEPOSIT",
  "financial_account_token": "6127238d-cb85-50bc-86aa-264654a11be9",
  "settled_amount": 0,
  "pending_amount": 0,
  "currency": "USD",
  "user_defined_id": "1234",
  "events": [
    {
      "amount": 10000,
      "type": "EXTERNAL_ACH_INITIATED",
      "result": "APPROVED",
      "detailed_results": ["APPROVED"],
      "created": "2024-04-18T18:16:09Z",
      "token": "34c5b9d2-2d6a-540b-90fe-fa202b418242",
      "memo": "Customer deposit",
      "effective_date": "2024-04-18"
    },
    {
      "amount": 10000,
      "type": "EXTERNAL_ACH_SETTLED",
      "result": "APPROVED",
      "detailed_results": ["APPROVED"],
      "created": "2024-04-19T08:30:40Z",
      "token": "5f6255f8-4016-5e66-aedf-2e3c76027e04",
      "memo": "Customer deposit",
      "effective_date": "2024-04-19"
    },
    {
      "amount": 10000,
      "type": "EXTERNAL_ACH_RELEASED",
      "result": "APPROVED",
      "detailed_results": ["APPROVED"],
      "created": "2024-04-21T08:30:40Z",
      "token": "7eec03f2-2fac-4485-bc4b-0526d8bff3ba",
      "memo": "Customer deposit",
      "effective_date": "2024-04-21"
    },
    {
      "amount": 0,
      "type": "EXTERNAL_ACH_REVERSED",
      "result": "APPROVED",
      "detailed_results": ["APPROVED"],
      "created": "2024-04-22T10:02:05Z",
      "token": "f7d208bc-1227-445d-a7c5-03e7e9cc15f9",
      "memo": "Customer deposit",
      "effective_date": "2024-04-22"
    }
  ],
  "created": "2024-04-18T18:16:09Z",
  "updated": "2024-04-22T10:02:05Z"
}

Sequence 4: Payment reversed before release

A deposit can also be reversed after it has settled but before its funds have been released. This sequence contains three events: initiated, settled, and reversed. As with any reversal, the reversed event rolls back all prior postings.

{
  "family": "EXTERNAL_PAYMENT",
  "token": "6d5a2718-9b79-4473-aa1e-6bbf7433ea6f",
  "status": "REVERSED",
  "result": "APPROVED",
  "category": "EXTERNAL_ACH",
  "payment_type": "DEPOSIT",
  "financial_account_token": "6127238d-cb85-50bc-86aa-264654a11be9",
  "settled_amount": 0,
  "pending_amount": 0,
  "currency": "USD",
  "user_defined_id": "1234",
  "events": [
    {
      "amount": 10000,
      "type": "EXTERNAL_ACH_INITIATED",
      "result": "APPROVED",
      "detailed_results": ["APPROVED"],
      "created": "2024-04-18T18:16:09Z",
      "token": "34c5b9d2-2d6a-540b-90fe-fa202b418242",
      "memo": "Customer deposit",
      "effective_date": "2024-04-18"
    },
    {
      "amount": 10000,
      "type": "EXTERNAL_ACH_SETTLED",
      "result": "APPROVED",
      "detailed_results": ["APPROVED"],
      "created": "2024-04-19T08:30:40Z",
      "token": "5f6255f8-4016-5e66-aedf-2e3c76027e04",
      "memo": "Customer deposit",
      "effective_date": "2024-04-19"
    },
    {
      "amount": 0,
      "type": "EXTERNAL_ACH_REVERSED",
      "result": "APPROVED",
      "detailed_results": ["APPROVED"],
      "created": "2024-04-20T10:02:05Z",
      "token": "f7d208bc-1227-445d-a7c5-03e7e9cc15f9",
      "memo": "Customer deposit",
      "effective_date": "2024-04-20"
    }
  ],
  "created": "2024-04-18T18:16:09Z",
  "updated": "2024-04-20T10:02:05Z"
}

Deposit Balance Impacts

The below table shows if/how balances are impacted per transaction event for deposits into debit and prepaid accounts. The impacts are reversed for credit accounts.

`event.type`	Pending Balance	Available Balance
`EXTERNAL_*_INITIATED`	None	None
`EXTERNAL_*_SETTLED`	Increased	None
`EXTERNAL_*_RELEASED`	Decreased	Increased
`EXTERNAL_*_CANCELED`	All postings rolled back	All postings rolled back
`EXTERNAL_*_REVERSED`	All postings rolled back	All postings rolled back