---
title: "Create payment"
method: POST
path: "/v1/payments"
tags: ["Payment"]
---

# Create payment

`POST /v1/payments`

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

## Request body

- CreatePaymentRequest
  - `amount` integer, required
  - `external_bank_account_token` string, uuid, required
  - `financial_account_token` string, uuid, required
  - `memo` string
  - `method` 'ACH_NEXT_DAY' | 'ACH_SAME_DAY', required
  - `method_attributes` PaymentMethodRequestAttributes, required
    - `sec_code` 'CCD' | 'PPD' | 'WEB', required
    - `ach_hold_period` integer — Number of days to hold the ACH payment
    - `addenda` string, nullable
    - `override_company_name` string, nullable — Value to override the configured company name with. Can only be used if allowed to override
  - `token` string, uuid — Customer-provided token that will serve as an idempotency token. This token will become the transaction token.
  - `type` 'COLLECTION' | 'PAYMENT', required
  - `user_defined_id` string
  - `hold` object — Optional hold to settle when this payment is initiated.
    - `token` string, uuid, required — Token of the hold to settle when this payment is initiated.

## Response `202`

Created

- PostPaymentResponse — Base class for all transaction types in the ledger service
  - `status` 'PENDING' | 'SETTLED' | 'DECLINED' | 'REVERSED' | 'CANCELED' | 'RETURNED', required
  - `token` string, uuid, required — Unique identifier for the transaction
  - `created` string, date-time, required — ISO 8601 timestamp of when the transaction was created
  - `updated` string, date-time, required — ISO 8601 timestamp of when the transaction was last updated
  - `family` 'PAYMENT', required — PAYMENT - Payment Transaction
  - `category` 'ACH' | 'WIRE' | 'STABLECOIN' | 'BALANCE_OR_FUNDING' | 'FEE' | 'REWARD' | 'ADJUSTMENT' | 'DERECOGNITION' | 'DISPUTE' | 'CARD' | 'EXTERNAL_ACH' | 'EXTERNAL_CHECK' | 'EXTERNAL_FEDNOW' | 'EXTERNAL_RTP' | 'EXTERNAL_TRANSFER' | 'EXTERNAL_WIRE' | 'MANAGEMENT_ADJUSTMENT' | 'MANAGEMENT_DISPUTE' | 'MANAGEMENT_FEE' | 'MANAGEMENT_REWARD' | 'MANAGEMENT_DISBURSEMENT' | 'HOLD' | 'PROGRAM_FUNDING' | 'PROGRAM_TRANSFER', required — Note: Inbound wire transfers are coming soon (availability varies by partner bank). The WIRE category is a preview. To learn more, contact your customer success manager.
  - `currency` string — Currency of the transaction in ISO 4217 format
  - `result` 'APPROVED' | 'DECLINED', required
  - `method_attributes` union, required — Method-specific attributes
    - AchMethodAttributes
      - `sec_code` 'CCD' | 'PPD' | 'WEB' | 'TEL' | 'CIE' | 'CTX', required — SEC code for ACH transaction
      - `return_reason_code` string, nullable — Return reason code if the transaction was returned
      - `ach_hold_period` integer, nullable — Number of days the ACH transaction is on hold
      - `retries` integer, nullable — Number of retries attempted
      - `company_id` string, nullable — Company ID for the ACH transaction
      - `receipt_routing_number` string, nullable — Receipt routing number
      - `recipient_name` string, nullable — Name of the recipient on ACH receipts. Reflects the originating bank's record
      - `trace_numbers` string[] — Trace numbers for the ACH transaction
      - `addenda` string, nullable — Addenda information
      - `override_company_name` string, nullable — Value to override the configured company name with. Can only be used if allowed to override
    - WireMethodAttributes
      - `wire_network` 'FEDWIRE' | 'SWIFT', required — Type of wire transfer
      - `wire_message_type` string, nullable, required — Type of wire message
      - `debtor` WirePartyDetails
        - `name` string, nullable — Name of the person or company
        - `account_number` string, nullable — Account number
        - `agent_name` string, nullable — Name of the financial institution
        - `agent_id` string, nullable — Routing number or BIC of the financial institution
      - `creditor` WirePartyDetails
        - `name` string, nullable — Name of the person or company
        - `account_number` string, nullable — Account number
        - `agent_name` string, nullable — Name of the financial institution
        - `agent_id` string, nullable — Routing number or BIC of the financial institution
      - `message_id` string, nullable — Point to point reference identifier, as assigned by the instructing party, used for tracking the message through the Fedwire system
      - `remittance_information` string, nullable — Payment details or invoice reference
    - StablecoinMethodAttributes
      - `chain` string, required — Blockchain the stablecoin transfer settled on
      - `transaction_hash` string, nullable — On-chain transaction hash of the transfer. Null until the transfer has settled on chain
  - `financial_account_token` string, uuid, required — Financial account token
  - `external_bank_account_token` string, uuid, nullable — External bank account token
  - `blockchain_recipient_token` string, uuid, nullable — Token of the blockchain recipient the payout is sent to
  - `direction` 'CREDIT' | 'DEBIT', required — Transfer direction
  - `source` 'LITHIC' | 'EXTERNAL' | 'CUSTOMER', required — Transaction source
  - `method` 'ACH_NEXT_DAY' | 'ACH_SAME_DAY' | 'WIRE' | 'STABLECOIN', required — Transfer method
  - `settled_amount` integer, required — Settled amount in cents
  - `pending_amount` integer, required — Pending amount in cents
  - `events` PaymentEvent[], required — List of transaction events
    - `amount` integer, required — Amount of the financial event that has been settled in the currency's smallest unit (e.g., cents).
    - `created` string, date-time, required — Date and time when the financial event occurred. UTC time zone.
    - `detailed_results` string[] — More detailed reasons for the event
    - `result` 'APPROVED' | 'DECLINED', required — APPROVED financial events were successful while DECLINED financial events were declined by user, Lithic, or the network.
    - `token` string, uuid, required — Globally unique identifier.
    - `type` 'ACH_ORIGINATION_CANCELLED' | 'ACH_ORIGINATION_INITIATED' | 'ACH_ORIGINATION_PROCESSED' | 'ACH_ORIGINATION_REJECTED' | 'ACH_ORIGINATION_RELEASED' | 'ACH_ORIGINATION_REVIEWED' | 'ACH_ORIGINATION_SETTLED' | 'ACH_RECEIPT_PROCESSED' | 'ACH_RECEIPT_RELEASED' | 'ACH_RECEIPT_RELEASED_EARLY' | 'ACH_RECEIPT_SETTLED' | 'ACH_RETURN_INITIATED' | 'ACH_RETURN_PROCESSED' | 'ACH_RETURN_REJECTED' | 'ACH_RETURN_SETTLED' | 'WIRE_TRANSFER_INBOUND_RECEIVED' | 'WIRE_TRANSFER_INBOUND_SETTLED' | 'WIRE_TRANSFER_INBOUND_BLOCKED' | 'WIRE_RETURN_OUTBOUND_INITIATED' | 'WIRE_RETURN_OUTBOUND_SENT' | 'WIRE_RETURN_OUTBOUND_SETTLED' | 'WIRE_RETURN_OUTBOUND_REJECTED' | 'STABLECOIN_RECEIVED' | 'STABLECOIN_INITIATED' | 'STABLECOIN_REVIEWED' | 'STABLECOIN_SENT' | 'STABLECOIN_SETTLED' | 'STABLECOIN_REJECTED', required — Note: Inbound wire transfers are coming soon (availability varies by partner bank). Wire-related event types below are a preview. To learn more, contact your customer success manager. Event types: ACH events: * `ACH_ORIGINATION_INITIATED` - ACH origination received and pending approval/release from an ACH hold. * `ACH_ORIGINATION_REVIEWED` - ACH origination has completed the review process. * `ACH_ORIGINATION_CANCELLED` - ACH origination has been cancelled. * `ACH_ORIGINATION_PROCESSED` - ACH origination has been processed and sent to the Federal Reserve. * `ACH_ORIGINATION_SETTLED` - ACH origination has settled. * `ACH_ORIGINATION_RELEASED` - ACH origination released from pending to available balance. * `ACH_ORIGINATION_REJECTED` - ACH origination was rejected and not sent to the Federal Reserve. * `ACH_RECEIPT_PROCESSED` - ACH receipt pending release from an ACH holder. * `ACH_RECEIPT_SETTLED` - ACH receipt funds have settled. * `ACH_RECEIPT_RELEASED` - ACH receipt released from pending to available balance. * `ACH_RECEIPT_RELEASED_EARLY` - ACH receipt released early from pending to available balance. * `ACH_RETURN_INITIATED` - ACH initiated return for an ACH receipt. * `ACH_RETURN_PROCESSED` - ACH receipt returned by the Receiving Depository Financial Institution. * `ACH_RETURN_SETTLED` - ACH return settled by the Receiving Depository Financial Institution. * `ACH_RETURN_REJECTED` - ACH return was rejected by the Receiving Depository Financial Institution. Wire transfer events: * `WIRE_TRANSFER_INBOUND_RECEIVED` - Inbound wire transfer received from the Federal Reserve and pending release to available balance. * `WIRE_TRANSFER_INBOUND_SETTLED` - Inbound wire transfer funds released from pending to available balance. * `WIRE_TRANSFER_INBOUND_BLOCKED` - Inbound wire transfer blocked and funds frozen for regulatory review. Wire return events: * `WIRE_RETURN_OUTBOUND_INITIATED` - Outbound wire return initiated to return funds from an inbound wire transfer. * `WIRE_RETURN_OUTBOUND_SENT` - Outbound wire return sent to the Federal Reserve and pending acceptance. * `WIRE_RETURN_OUTBOUND_SETTLED` - Outbound wire return accepted by the Federal Reserve and funds returned to sender. * `WIRE_RETURN_OUTBOUND_REJECTED` - Outbound wire return rejected by the Federal Reserve. Stablecoin events: * `STABLECOIN_RECEIVED` - Stablecoin pay-in received on-chain and pending release to available balance. * `STABLECOIN_INITIATED` - Stablecoin withdrawal initiated, with the funds placed on hold. * `STABLECOIN_REVIEWED` - Stablecoin pay-in or withdrawal has completed the review process. * `STABLECOIN_SENT` - Stablecoin withdrawal accepted for on-chain submission to the destination address, and pending confirmation. * `STABLECOIN_SETTLED` - Stablecoin pay-in funds released to available balance, or stablecoin withdrawal confirmed on-chain. * `STABLECOIN_REJECTED` - Stablecoin withdrawal failed and the hold placed at initiation has been reversed.
    - `external_id` string, nullable — Payment event external ID. For ACH transactions, this is the ACH trace number. For inbound wire transfers, this is the IMAD (Input Message Accountability Data). For stablecoin payments, this is the on-chain transaction hash of the transfer; it is present on events that reflect on-chain activity and null on internal lifecycle events.
  - `descriptor` string, required — Transaction descriptor
  - `user_defined_id` string, nullable — User-defined identifier
  - `expected_release_date` string, date, nullable — Expected release date for the transaction
  - `related_account_tokens` RelatedAccountTokens, required — Account tokens related to a payment transaction
    - `business_account_token` string, uuid, nullable, required — Globally unique identifier for the business account
    - `account_token` string, uuid, nullable, required — Globally unique identifier for the account
  - `type` 'ORIGINATION_CREDIT' | 'ORIGINATION_DEBIT' | 'RECEIPT_CREDIT' | 'RECEIPT_DEBIT' | 'WIRE_INBOUND_PAYMENT' | 'WIRE_INBOUND_ADMIN' | 'WIRE_OUTBOUND_PAYMENT' | 'WIRE_OUTBOUND_ADMIN' | 'WIRE_INBOUND_DRAWDOWN_REQUEST' | 'STABLECOIN_INBOUND' | 'STABLECOIN_OUTBOUND'
  - `tags` Tags — Key-value pairs for tagging resources. Tags allow you to associate arbitrary metadata with a resource for your own purposes.
  - `balance` Balance — Balance
    - `available_amount` integer, required — Funds available for spend in the currency's smallest unit (e.g., cents for USD)
    - `created` string, date-time, required — Date and time for when the balance was first created.
    - `currency` string, required — 3-character alphabetic ISO 4217 code for the local currency of the balance.
    - `financial_account_token` string, uuid, required — Globally unique identifier for the financial account that holds this balance.
    - `financial_account_type` 'CARD' | 'ISSUING' | 'OPERATING' | 'PROGRAM_RECEIVABLES' | 'RESERVE' | 'SECURITY', required — Type of financial account.
    - `last_transaction_event_token` string, uuid, nullable, required — Globally unique identifier for the last financial transaction event that impacted this balance.
    - `last_transaction_token` string, uuid, nullable, required — Globally unique identifier for the last financial transaction that impacted this balance.
    - `pending_amount` integer, required — 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).
    - `total_amount` integer, required — The sum of available and pending balance in the currency's smallest unit (e.g., cents for USD).
    - `updated` string, date-time, required — Date and time for when the balance was last updated.

## Other 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 | 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) |
- `404` — The specified resource was not found.
- `429` — 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 |

## Changes

- **2026-08-24** `697646814db7` — 1 info
  - removed the `STABLECOIN` enum value from the `allOf[subschema #1: Payment Transaction]/allOf[subschema #2]/type` response property for the response status `202`
- **2026-08-24** `3b9115e56436` — 2 warning
  - added the new `STABLECOIN_INBOUND` enum value to the `allOf[subschema #1: Payment Transaction]/allOf[subschema #2]/type` response property for the response status `202`
  - added the new `STABLECOIN_OUTBOUND` enum value to the `allOf[subschema #1: Payment Transaction]/allOf[subschema #2]/type` response property for the response status `202`
- **2026-08-13** `8fe10c2a978d` — 1 info
  - added the optional property `allOf[subschema #1: Payment Transaction]/allOf[subschema #2]/blockchain_recipient_token` to the response with the `202` status
- **2026-08-12** `d13224fa09ca` — 1 breaking, 1 warning
  - added `#/components/schemas/StablecoinMethodAttributes` to the `allOf[subschema #1: Payment Transaction]/allOf[subschema #2]/method_attributes` response property `oneOf` list for the response status `202`
  - added the new `STABLECOIN` enum value to the `allOf[subschema #1: Payment Transaction]/allOf[subschema #2]/method` response property for the response status `202`
- **2026-08-10** `5864e38724e6` — 1 warning
  - added the new `STABLECOIN` enum value to the `allOf[subschema #1: Payment Transaction]/allOf[subschema #2]/type` response property for the response status `202`

[Full history](https://skmtc.dev/lithic-com/apis/lithic-developer-api/changes/v1/payments/post.md)

---

[API](https://skmtc.dev/lithic-com/apis/lithic-developer-api.md) · [All operations](https://skmtc.dev/lithic-com/apis/lithic-developer-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/lithic-com/lithic-developer-api/revisions/76b96ae9a0b9/schema)