Guides
StatusDashboard

Receiving Wires

Learn how to send wires to your Lithic financial account and how Lithic processes them.

📘

Wire transfers are currently in private beta. Contact your customer success manager to learn more about access. Your sponsor bank may apply additional screening, limits, or policies based on their risk management practices.

Wire transfers provide fast, final settlement for high-value payments. Unlike ACH payments that can take days to clear and may be reversed, wires settle within seconds and are irrevocable once completed. This makes them ideal for large customer deposits, account funding, and time-sensitive transactions.

Lithic supports domestic wire transfers only via the Fedwire network. The wire must originate from a US bank account. International wires (SWIFT) and wires forwarded by correspondent banks on behalf of foreign originators are not supported.

Wire transfers are only available with select sponsor banks. Contact your Lithic customer success manager to confirm whether your sponsor bank supports wire transfers.

How to Receive Wires

Wire transfers use terminology from the ISO 20022 standard:

  • Creditor - The party receiving the funds
  • Debtor - The party sending the funds

For incoming wires to your Lithic financial account, you are the creditor and the sender is the debtor.

To receive wires, your financial account must be routable (assigned a routing number and account number) and have status OPEN or PENDING. Use the Get financial account endpoint to retrieve your routing and account numbers.

Required Information

When sending a wire to your Lithic financial account, the sender (you or a third party) should provide:

  • Your sponsor bank name
  • Your sponsor bank routing number (9-digit RTN)
  • The account number for your Lithic financial account
  • Your account holder name on file with Lithic. When you send the wire, specify this name as the creditor or recipient. Use the Get account holder endpoint to retrieve this name, which is individual.first_name and individual.last_name for individual account holders or business_entity.legal_business_name for business account holders.
  • Wire amount in USD cents
  • Optional payment reference or memo

Returns

Lithic automatically returns wires that fail validation checks to the sender, typically within seconds to minutes of receipt.

Common Return Reasons

Creditor Name Mismatch

The most common cause of wire returns is when the creditor name on the wire doesn't match the account holder name associated with the financial account. Lithic looks up the financial account using the routing number and account number specified in the wire, then validates that the creditor name matches the account holder on file for that financial account. While Lithic uses smarter matching to accommodate minor variations like punctuation or abbreviations, significant differences will trigger a return. For example, a wire showing "Acme Corp" should still match an account holder named "Acme Corporation", but "John Smith" won't match "Jane Smith".

Account Not Found

Lithic returns the wire immediately if the account number doesn't match any account in Lithic's system. Double-check account numbers before initiating wires or sharing instructions with third parties.

Account Closed or Suspended

Lithic automatically returns wires sent to closed or suspended accounts. Only accounts with status OPEN or PENDING can receive wires. Check your account status using the Get financial account endpoint before initiating large transfers.

The Lifecycle of a Wire

When a wire arrives at your Lithic financial account, it progresses through a series of events from initial receipt to final settlement. The exact sequence depends on whether validation succeeds, fails, or requires manual review.

Successful Receipt

Lithic immediately settles wires that pass all validation checks to your account. Lithic receives and validates the wire, then credits your account with the funds. Funds typically become available within seconds.

Validation Failures

When a wire fails validation, Lithic automatically returns it to the sender. Lithic never credits any funds to your account. The entire process typically completes within the same banking day.

Validation failures occur when the creditor name doesn't match the account holder name for the specified financial account, the account number is incorrect, or the account is closed or suspended. If the wire sender provided incorrect information, they can retry after correcting the details.

Compliance Violations

Lithic may flag a wire for manual compliance review due to sanctions screening or other risk factors. This can happen when any named party appears on sanctions watchlists or when the wire originates from high-risk jurisdictions. Lithic holds the funds in suspense during the review period.

After the compliance team investigates, Lithic blocks the wire if a violation is confirmed and reports the transaction to the appropriate regulatory agencies. If the wire passes compliance review, Lithic credits your account with the funds.

The Wire Payment Object

The wire payment object in the Lithic API contains detailed information about the wire. This data is essential for visibility into funds flowing in and out of your account, reconciling against bank statements, and supporting compliance reporting.

You can track wires using these approaches:

All of these return the same payment object structure.

The top-level fields tell you about the payment state and amount:

  • family: Always "PAYMENT" for wire transfers
  • category: Always "WIRE" for wire transfers
  • method: Always "WIRE" for wire transfers
  • direction:
    • "CREDIT" for funds flowing into your Lithic financial account
    • "DEBIT" for funds flowing out of your Lithic financial account
  • type:
    • "WIRE_INBOUND_PAYMENT" for incoming wires
    • "WIRE_OUTBOUND_PAYMENT" for outgoing wires
  • status: Current payment state
    • "PENDING" - Wire has been received and is going through validation
    • "SETTLED" - Funds credited and available for use
    • "DECLINED" - Wire was blocked due to compliance violations
    • "RETURNED" - Wire was returned due to a validation failure
  • result: Final outcome
    • "APPROVED" - Wire was successful
    • "DECLINED" - Wire was rejected
  • settled_amount: Amount credited to your account in cents
  • pending_amount: Amount pending review in cents
  • financial_account_token: Lithic financial account receiving the wire (null if account not found)
  • external_bank_account_token: External bank account token when the sender's bank account is registered with Lithic; null when the sender's bank account isn't registered
  • descriptor: Description provided by the sender

The method_attributes object contains wire-specific details about both parties:

  • wire_network: Always "FEDWIRE" for domestic wires
  • message_id: IMAD (Input Message Accountability Data) - unique Federal Reserve tracking number
  • debtor: Information about the party sending the wire
    • name: Debtor name
    • account_number: Debtor account number
    • agent_name: Debtor's bank name
    • agent_id: Debtor's bank routing number
  • creditor: Information about the party receiving the wire
    • name: Name of the creditor, which is your account holder name
    • account_number: The account number assigned to your Lithic financial account
    • agent_name: Your sponsor bank name
    • agent_id: Your sponsor bank routing number

Each wire includes an events array showing its progression through the lifecycle. Each event contains:

  • type: Event type indicating the stage in the wire lifecycle
  • result: Event result (APPROVED or DECLINED)
  • detailed_results: Array of detailed outcome codes
  • amount: Wire amount in cents
  • created: Event timestamp
  • token: Unique event identifier

Event types for inbound wires:

  • WIRE_TRANSFER_INBOUND_RECEIVED - Wire received from the Federal Reserve; pending validation
  • WIRE_TRANSFER_INBOUND_SETTLED - Wire passed all validation checks and funds credited to your account
  • WIRE_TRANSFER_INBOUND_BLOCKED - Wire was determined to violate compliance rules and blocked; funds are frozen and relevant agencies such as OFAC will be notified
  • WIRE_RETURN_OUTBOUND_INITIATED - Return wire initiated; waiting to be sent back to the originator
  • WIRE_RETURN_OUTBOUND_SENT - Return wire sent to the Federal Reserve for delivery
  • WIRE_RETURN_OUTBOUND_SETTLED - Return wire delivered to the originator's bank

When reconciling incoming wire transfers against bank statements, consider referencing these fields:

  • method_attributes.message_id - The IMAD for matching with bank statements
  • method_attributes.debtor.name - Originator name for matching against expected senders
  • method_attributes.debtor.account_number - Originator account number
  • settled_amount - Final amount credited to your account in cents

Examples

The examples below show how each scenario with an incoming wire appears in the payment object.

Successful Wire Receipt

When a wire passes all validation checks, Lithic settles the wire and makes the funds available in your account.

{
  "family": "PAYMENT",
  "category": "WIRE",
  "status": "SETTLED",
  "result": "APPROVED",
  "token": "7b3f9e4d-8c2a-4f1b-9d3e-6a8c7b4f9e2d",
  "created": "2026-04-02T14:23:15Z",
  "updated": "2026-04-02T14:23:18Z",
  "financial_account_token": "9c4e8f2a-7d1b-4c3e-8f2a-9d7b4c3e8f2a",
  "external_bank_account_token": null,
  "direction": "CREDIT",
  "source": "EXTERNAL",
  "method": "WIRE",
  "type": "WIRE_INBOUND_PAYMENT",
  "settled_amount": 5000000,
  "pending_amount": 0,
  "currency": "USD",
  "descriptor": "Invoice 12345",
  "user_defined_id": null,
  "method_attributes": {
    "wire_network": "FEDWIRE",
    "wire_message_type": "CUSTOMER_CREDIT_TRANSFER",
    "message_id": "20260402WFBIUS33XXX1234567890",
    "debtor": {
      "name": "John Smith",
      "account_number": "9876543210",
      "agent_name": "Example Bank",
      "agent_id": "999888777"
    },
    "creditor": {
      "name": "Acme Corporation",
      "account_number": "[Your account number]",
      "agent_name": "[Sponsor Bank Name]",
      "agent_id": "[Sponsor Bank Routing Number]"
    }
  },
  "events": [
    {
      "token": "e1f9a4c7-3b2d-4e8f-9a4c-7b3d2e8f9a4c",
      "type": "WIRE_TRANSFER_INBOUND_RECEIVED",
      "amount": 5000000,
      "result": "APPROVED",
      "detailed_results": ["APPROVED"],
      "created": "2026-04-02T14:23:15Z"
    },
    {
      "token": "f2a8b5d3-4c9e-5f1a-8b5d-3c4e9f1a8b5d",
      "type": "WIRE_TRANSFER_INBOUND_SETTLED",
      "amount": 5000000,
      "result": "APPROVED",
      "detailed_results": ["APPROVED"],
      "created": "2026-04-02T14:23:18Z"
    }
  ]
}

Returned Wire

When a wire fails validation, it's automatically returned. The events array shows the complete return workflow.

{
  "family": "PAYMENT",
  "category": "WIRE",
  "status": "RETURNED",
  "result": "DECLINED",
  "token": "8d4a9f3e-7c2b-4e1f-8d3a-9f7c2e1f8d3a",
  "created": "2026-04-02T15:45:22Z",
  "updated": "2026-04-02T15:45:27Z",
  "financial_account_token": null,
  "external_bank_account_token": null,
  "direction": "CREDIT",
  "source": "EXTERNAL",
  "method": "WIRE",
  "type": "WIRE_INBOUND_PAYMENT",
  "settled_amount": 0,
  "pending_amount": 0,
  "currency": "USD",
  "descriptor": "Account funding",
  "user_defined_id": null,
  "method_attributes": {
    "wire_network": "FEDWIRE",
    "wire_message_type": "CUSTOMER_CREDIT_TRANSFER",
    "message_id": "20260402WFBIUS33XXX9876543210",
    "debtor": {
      "name": "Jane Doe",
      "account_number": "1234567890",
      "agent_name": "Example Bank",
      "agent_id": "888777666"
    },
    "creditor": {
      "name": "Acme Corp",
      "account_number": "[Your account number]",
      "agent_name": "[Sponsor Bank Name]",
      "agent_id": "[Sponsor Bank Routing Number]"
    }
  },
  "events": [
    {
      "token": "a3c8d2f9-5e4b-6a1c-8d2f-9e5b4a1c8d2f",
      "type": "WIRE_TRANSFER_INBOUND_RECEIVED",
      "amount": 2500000,
      "result": "DECLINED",
      "detailed_results": ["CREDITOR_MISMATCH"],
      "created": "2026-04-02T15:45:22Z"
    },
    {
      "token": "b4d9c3e8-6f2a-5d1b-9c3e-8f6a2d1b9c3e",
      "type": "WIRE_RETURN_OUTBOUND_INITIATED",
      "amount": 2500000,
      "result": "APPROVED",
      "detailed_results": ["APPROVED"],
      "created": "2026-04-02T15:45:23Z"
    },
    {
      "token": "c5e8d4f9-7a3b-6e2c-8d4f-9a7b3e2c8d4f",
      "type": "WIRE_RETURN_OUTBOUND_SENT",
      "amount": 2500000,
      "result": "APPROVED",
      "detailed_results": ["APPROVED"],
      "created": "2026-04-02T15:45:25Z"
    },
    {
      "token": "d6f9e5a8-8b4c-7f3d-9e5a-8b8c4f3d9e5a",
      "type": "WIRE_RETURN_OUTBOUND_SETTLED",
      "amount": 2500000,
      "result": "APPROVED",
      "detailed_results": ["APPROVED"],
      "created": "2026-04-02T15:45:27Z"
    }
  ]
}

The detailed_results field in the first event shows why the wire was declined:

  • CREDITOR_MISMATCH - Creditor name doesn't match the account holder name for the financial account
  • CREDITOR_NOT_FOUND - No Lithic financial account found for the routing and account number
  • CREDITOR_ACCOUNT_CLOSED - Lithic financial account is closed or suspended

Blocked Wire

When a wire is flagged for compliance review, Lithic holds the funds in suspense. If Lithic's compliance team determines the wire violates sanctions or other regulations, Lithic blocks the wire in accordance with AML/BSA policies and freezes the funds.

{
  "family": "PAYMENT",
  "category": "WIRE",
  "status": "DECLINED",
  "result": "DECLINED",
  "token": "6f8c2d4a-9e1b-5c3f-8d2a-4f9e1c3b8d2a",
  "created": "2026-04-02T16:12:08Z",
  "updated": "2026-04-02T16:12:10Z",
  "financial_account_token": "9c4e8f2a-7d1b-4c3e-8f2a-9d7b4c3e8f2a",
  "external_bank_account_token": null,
  "direction": "CREDIT",
  "source": "EXTERNAL",
  "method": "WIRE",
  "type": "WIRE_INBOUND_PAYMENT",
  "settled_amount": 0,
  "pending_amount": 10000000,
  "currency": "USD",
  "descriptor": "Payment for services",
  "user_defined_id": null,
  "method_attributes": {
    "wire_network": "FEDWIRE",
    "wire_message_type": "CUSTOMER_CREDIT_TRANSFER",
    "message_id": "20260402HSBC1234567890",
    "debtor": {
      "name": "Global Trading Co",
      "account_number": "5555666677",
      "agent_name": "Example Bank",
      "agent_id": "777666555"
    },
    "creditor": {
      "name": "Acme Corporation",
      "account_number": "[Your account number]",
      "agent_name": "[Sponsor Bank Name]",
      "agent_id": "[Sponsor Bank Routing Number]"
    }
  },
  "events": [
    {
      "token": "d4f9b2c8-7e5a-4d1f-9b2c-8e7a5d1f9b2c",
      "type": "WIRE_TRANSFER_INBOUND_RECEIVED",
      "amount": 10000000,
      "result": "APPROVED",
      "detailed_results": ["APPROVED"],
      "created": "2026-04-02T16:12:08Z"
    },
    {
      "token": "e5a8c3d9-6f2b-5e4a-8c3d-9f6b2e5a8c3d",
      "type": "WIRE_TRANSFER_INBOUND_BLOCKED",
      "amount": 10000000,
      "result": "DECLINED",
      "detailed_results": ["WATCHLIST_SCREENING_FAILED"],
      "created": "2026-04-02T16:12:10Z"
    }
  ]
}

FAQ

Can I return a wire I've already received?

If you receive a wire in error, contact Lithic support through your dashboard.

What if I don't recognize an incoming wire?

Check the originator information in the method_attributes.debtor object. If you cannot identify the sender, contact Lithic support through your dashboard to investigate.

How do I track wires in real-time?

Subscribe to webhooks for payment_transaction.created and payment_transaction.updated events. The webhook payload matches the Get payment response structure. You can also use the List payments endpoint to retrieve wire payment history.

Updated about 1 hour ago