Lithic API Documentation | Payments

Payments

payments

Methods

List Payments -> CursorPage<

Payment

get/v1/payments

List all the payments for the provided search criteria.

Create Payment ->

Payment

post/v1/payments

Initiates a payment between a financial account and an external bank account.

Get Payment By Token ->

Payment

get/v1/payments/{payment_token}

Get the payment by token.

Simulate Release Payment -> { debugging_request_id, result, transaction_event_token }

post/v1/simulate/payments/release

Simulates a release of a Payment.

Simulate Return Payment -> { debugging_request_id, result, transaction_event_token }

post/v1/simulate/payments/return

Simulates a return of a Payment.

Retry Payment ->

Payment

post/v1/payments/{payment_token}/retry

Retry an origination which has been returned.

Return Payment ->

Payment

post/v1/payments/{payment_token}/return

Return an ACH payment with a specified return reason code. Returns must be initiated within the time window specified by NACHA rules for each return code (typically 2 banking days for most codes, 60 calendar days for unauthorized debits). For a complete list of return codes and their meanings, see the ACH Return Reasons documentation.

Note:

This endpoint does not modify the state of the financial account associated with the payment. If you would like to change the account state, use the Update financial account status endpoint.
By default this endpoint is not enabled for your account. Please contact your implementations manager to enable this feature.

path Parameters

payment_token: string

(format: uuid)

Response fields

Payment

Request example

curl https://api.lithic.com/v1/payments/$PAYMENT_TOKEN/return \
    -H 'Content-Type: application/json' \
    -H "Authorization: $LITHIC_API_KEY" \
    -d '{
          "financial_account_token": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
          "return_reason_code": "R01",
          "date_of_death": "2025-01-15"
        }'

200Example

{
  "token": "bd4efddb-771b-49e3-9af9-49b077ab5eb8",
  "category": "ACH",
  "created": "2025-10-27T20:12:22Z",
  "descriptor": "ach_origination_credit",
  "direction": "CREDIT",
  "events": [
    {
      "token": "327dccc3-fe42-54d2-962c-7f8135805464",
      "amount": -1588,
      "created": "2025-10-27T20:12:22Z",
      "result": "APPROVED",
      "type": "ACH_ORIGINATION_INITIATED",
      "detailed_results": [
        "APPROVED"
      ],
      "external_id": "external_id"
    },
    {
      "token": "f9165477-7cfc-53c6-98f1-84e9ec856a60",
      "amount": -1588,
      "created": "2025-10-27T20:12:25Z",
      "result": "APPROVED",
      "type": "ACH_ORIGINATION_REVIEWED",
      "detailed_results": [
        "APPROVED"
      ],
      "external_id": "external_id"
    }
  ],
  "family": "PAYMENT",
  "financial_account_token": "35b0c466-a3e3-519a-9549-ead6a6a2277d",
  "method": "ACH_NEXT_DAY",
  "method_attributes": {
    "sec_code": "CCD",
    "ach_hold_period": 1,
    "addenda": null,
    "company_id": "1111111111",
    "receipt_routing_number": null,
    "retries": 0,
    "return_reason_code": null,
    "trace_numbers": [
      "string"
    ]
  },
  "pending_amount": -1588,
  "related_account_tokens": {
    "account_token": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "business_account_token": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
  },
  "result": "APPROVED",
  "settled_amount": 0,
  "source": "LITHIC",
  "status": "PENDING",
  "updated": "2025-10-27T20:12:25Z",
  "currency": "USD",
  "expected_release_date": null,
  "external_bank_account_token": "feb4fee1-2414-4c38-a5f6-9deac293c8f4",
  "type": "ORIGINATION_CREDIT",
  "user_defined_id": null
}

Simulate Receipt -> { debugging_request_id, result, transaction_event_token }

post/v1/simulate/payments/receipt

Simulates a receipt of a Payment.

Simulate Payment Lifecycle Event -> { debugging_request_id, result, transaction_event_token }

post/v1/simulate/payments/{payment_token}/action

Simulate payment lifecycle event

Domain types

Payment = { token, category, created, 19 more... }

Payment transaction