# Wire Processor

Understanding how the Twisp wire processor sends and receives Fedwire wires

The Twisp wire processor sends and receives Fedwire Funds Service wires in the ISO 20022 format. It builds and reads the Fedwire messages, holds and posts funds in your ledger, and matches every reply from the Fed to the wire it answers.

## How Wires Reach Twisp

Your sponsor bank connects to the Fed. Each Fedwire message travels as one ISO 20022 envelope in one file:

- **Inbound:** the sponsor bank drops each message it receives from the Fed, such as a wire to one of your customers or the Fed's status of a wire you sent, into its file store. You forward each file to Twisp with [`Mutation.wire.processFile()`](https://www.twisp.com/docs/reference/graphql/mutations.md#wire.process-file).
- **Outbound:** Twisp writes the messages you send, such as wires and the returns of wires you received, to one tar.gz archive per generation. Each message is its own file in the archive. You download the archive and forward each file to the sponsor bank.

Twisp never connects to the Fed or the sponsor bank itself.

## Why Wires Need a Processor

A wire looks like a single transfer, but processing one involves several messages and states:

**Message format:** Fedwire uses ISO 20022 XML wrapped in a Fed envelope. Beyond the ISO schemas, the Fed adds usage guidelines: fixed codes, required elements, the IMAD format of message ids and length limits. A message that breaks them is rejected.

**Settlement by reply:** A wire you send is not final when you send it. The Fed answers with a payment status (pacs.002): accepted, or rejected with a reason. Your customer's funds must stay held until that answer arrives.

**Correlation:** Replies, returns and reject notices arrive later, in separate files. Each must be matched to the wire it answers by its UETR or message id.

**Returns:** A wire you sent can come back as a pacs.004. A wire you received can be returned, which means sending a pacs.004 of your own.

## Processor Architecture

### Configuration

A [wire configuration](https://www.twisp.com/docs/reference/wire/configuration.md) connects:

- the settlement, suspense and exception accounts
- your routing number and the sponsor bank's Fedwire endpoint
- the range of IMAD sequence numbers Twisp may assign
- how inbound wires are decided: by webhook, as `PENDING`, or by account lookup

### Workflows

Two workflows hold each wire's state and post its transactions:

- [`WIRE_OUTBOUND`](https://www.twisp.com/docs/reference/wire/outbound.md) sends a wire: `CREATE` holds the funds, `SUBMIT` records the generated message, and the Fed's reply settles or rejects it.
- [`WIRE_INBOUND`](https://www.twisp.com/docs/reference/wire/inbound.md) receives a wire: the decision credits the account as `SETTLE` or `PENDING`, or returns the wire.

### File Operations

[File operations](https://www.twisp.com/docs/reference/wire/file-operations.md) move messages in and out:

- `processFile` records one inbound message and applies it.
- `generateFile` writes every queued outbound message to one tar.gz archive, each message as its own file.

## Lifecycle of an Outbound Wire

1. You execute `WIRE_OUTBOUND` `CREATE`. Twisp validates the wire by building its pacs.008, holds the amount in the customer's pending layer, and queues the wire.
2. You call `generateFile`. Twisp gives the wire an IMAD, writes its pacs.008 to the generation's archive, and moves the wire to `SUBMIT`. You download the archive and forward the wire's file to the sponsor bank.
3. The Fed answers with a pacs.002. You process the file:
   - `ACSC` (accepted): the wire moves to `SETTLE` and the hold becomes a settled debit.
   - `RJCT` (rejected): the wire moves to `REJECT` and the hold is released.
4. If the wire comes back later as a pacs.004, processing it moves the wire to `RETURN` and credits the customer.

## Lifecycle of an Inbound Wire

1. You process the file holding the pacs.008.
2. Twisp asks the configuration's decider which account to credit: your webhook, the pending account, or an account lookup.
3. The wire posts as `SETTLE` or `PENDING`. A wire you decide to return, or one that cannot post (for example because a velocity control refuses it), is credited to suspense and returned.
4. A returned wire's pacs.004 is written by the next `generateFile`.

## Further Reading

- [Wire Reference](https://www.twisp.com/docs/reference/wire.md)
- [Configuration](https://www.twisp.com/docs/reference/wire/configuration.md)
- [File Operations](https://www.twisp.com/docs/reference/wire/file-operations.md)
- [Outbound Wires](https://www.twisp.com/docs/reference/wire/outbound.md)
- [Inbound Wires](https://www.twisp.com/docs/reference/wire/inbound.md)