# Wire Transfers
> Wire transfers move funds between your Increase account and any other account accessible by Fedwire.

[Events](https://increase.com/documentation/events.md) will be generated for this resource. The possible event categories are: `wire_transfer.created` and `wire_transfer.updated`.

## The Wire Transfer object
### Example
```json
{
  "account_id": "account_in71c4amph0vgo2qllky",
  "account_number": "987654321",
  "amount": 100,
  "approval": {
    "approved_at": "2020-01-31T23:59:59Z",
    "approved_by": null
  },
  "cancellation": null,
  "created_at": "2020-01-31T23:59:59Z",
  "created_by": {
    "category": "user",
    "user": {
      "email": "user@example.com"
    }
  },
  "creditor": {
    "address": {
      "unstructured": {
        "line1": "33 Liberty Street",
        "line2": null,
        "line3": null
      }
    },
    "name": "National Phonograph Company"
  },
  "currency": "USD",
  "debtor": null,
  "external_account_id": "external_account_ukk55lr923a3ac0pp7iv",
  "id": "wire_transfer_5akynk7dqsq25qwk9q2u",
  "idempotency_key": null,
  "inbound_wire_drawdown_request_id": null,
  "network": "wire",
  "pending_transaction_id": null,
  "remittance": {
    "category": "unstructured",
    "unstructured": {
      "message": "Invoice 29582"
    }
  },
  "reversal": null,
  "routing_number": "101050001",
  "source_account_number_id": null,
  "status": "complete",
  "submission": null,
  "transaction_id": "transaction_uyrp7fld2ium70oa7oi",
  "type": "wire_transfer",
  "unique_end_to_end_transaction_reference": null
}
```
### Attributes
- `account_id` (string)
  The Account to which the transfer belongs.

- `account_number` (string)
  The destination account number.

- `amount` (integer)
  The transfer amount in USD cents.

- `approval` (dictionary, nullable)
  If your account requires approvals for transfers and the transfer was approved, this will contain details of the approval.

  - `approval.approved_at` (string)
    The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time at which the transfer was approved.

  - `approval.approved_by` (string, nullable)
    If the Transfer was approved by a user in the dashboard, the email address of that user.

- `cancellation` (dictionary, nullable)
  If your account requires approvals for transfers and the transfer was not approved, this will contain details of the cancellation.

  - `cancellation.canceled_at` (string)
    The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time at which the Transfer was canceled.

  - `cancellation.canceled_by` (string, nullable)
    If the Transfer was canceled by a user in the dashboard, the email address of that user.

- `created_at` (string)
  The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time at which the transfer was created.

- `created_by` (dictionary, nullable)
  What object created the transfer, either via the API or the dashboard.

  - `created_by.api_key` (dictionary, nullable)
    If present, details about the API key that created the transfer.

      - `created_by.api_key.description` (string, nullable)
        The description set for the API key when it was created.

  - `created_by.category` (enum)
    The type of object that created this transfer.
    Cases:
    * `api_key` (An API key. Details will be under the `api_key` object.)
    * `oauth_application` (An OAuth application you connected to Increase. Details will be under the `oauth_application` object.)
    * `user` (A User in the Increase dashboard. Details will be under the `user` object.)

  - `created_by.oauth_application` (dictionary, nullable)
    If present, details about the OAuth Application that created the transfer.

      - `created_by.oauth_application.name` (string)
        The name of the OAuth Application.

  - `created_by.user` (dictionary, nullable)
    If present, details about the User that created the transfer.

      - `created_by.user.email` (string)
        The email address of the User.

- `creditor` (dictionary, nullable)
  The person or business that is receiving the funds from the transfer.

  - `creditor.address` (dictionary, nullable)
    The person or business's address.

      - `creditor.address.unstructured` (dictionary, nullable)
        Unstructured address lines.

            - `creditor.address.unstructured.line1` (string, nullable)
              The first line.

            - `creditor.address.unstructured.line2` (string, nullable)
              The second line.

            - `creditor.address.unstructured.line3` (string, nullable)
              The third line.

  - `creditor.name` (string, nullable)
    The person or business's name.

- `currency` (enum)
  The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) code for the transfer's currency. For wire transfers this is always equal to `usd`.
  Cases:
  * `USD` (US Dollar (USD))

- `debtor` (dictionary, nullable)
  The person or business whose funds are being transferred.

  - `debtor.address` (dictionary, nullable)
    The person or business's address.

      - `debtor.address.unstructured` (dictionary, nullable)
        Unstructured address lines.

            - `debtor.address.unstructured.line1` (string, nullable)
              The first line.

            - `debtor.address.unstructured.line2` (string, nullable)
              The second line.

            - `debtor.address.unstructured.line3` (string, nullable)
              The third line.

  - `debtor.name` (string, nullable)
    The person or business's name.

- `external_account_id` (string, nullable)
  The identifier of the External Account the transfer was made to, if any.

- `id` (string)
  The wire transfer's identifier.

- `idempotency_key` (string, nullable)
  The idempotency key you chose for this object. This value is unique across Increase and is used to ensure that a request is only processed once. Learn more about [idempotency](https://increase.com/documentation/idempotency-keys).

- `inbound_wire_drawdown_request_id` (string, nullable)
  The ID of an Inbound Wire Drawdown Request in response to which this transfer was sent.

- `network` (string)
  The transfer's network.

- `pending_transaction_id` (string, nullable)
  The ID for the pending transaction representing the transfer. A pending transaction is created when the transfer [requires approval](https://increase.com/documentation/transfer-approvals#transfer-approvals) by someone else in your organization.

- `remittance` (dictionary, nullable)
  Remittance information sent with the wire transfer.

  - `remittance.category` (enum)
    The type of remittance information being passed.
    Cases:
    * `unstructured` (The wire transfer contains unstructured remittance information.)
    * `tax` (The wire transfer is for tax payment purposes to the Internal Revenue Service (IRS).)

  - `remittance.tax` (dictionary, nullable)
    Internal Revenue Service (IRS) tax repayment information. Required if `category` is equal to `tax`.

      - `remittance.tax.date` (string)
        The month and year the tax payment is for, in YYYY-MM-DD format. The day is ignored.

      - `remittance.tax.identification_number` (string)
        The 9-digit Tax Identification Number (TIN) or Employer Identification Number (EIN).

      - `remittance.tax.type_code` (string)
        The 5-character tax type code.

  - `remittance.unstructured` (dictionary, nullable)
    Unstructured remittance information. Required if `category` is equal to `unstructured`.

      - `remittance.unstructured.message` (string)
        The message to the beneficiary.

- `reversal` (dictionary, nullable)
  If your transfer is reversed, this will contain details of the reversal.

  - `reversal.amount` (integer)
    The amount that was reversed in USD cents.

  - `reversal.created_at` (string)
    The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time at which the reversal was created.

  - `reversal.debtor_routing_number` (string, nullable)
    The debtor's routing number.

  - `reversal.description` (string)
    The description on the reversal message from Fedwire, set by the reversing bank.

  - `reversal.input_cycle_date` (string)
    The Fedwire cycle date for the wire reversal. The "Fedwire day" begins at 9:00 PM Eastern Time on the evening before the `cycle date`.

  - `reversal.input_message_accountability_data` (string)
    The Fedwire transaction identifier.

  - `reversal.input_sequence_number` (string)
    The Fedwire sequence number.

  - `reversal.input_source` (string)
    The Fedwire input source identifier.

  - `reversal.instruction_identification` (string, nullable)
    The sending bank's identifier for the reversal.

  - `reversal.return_reason_additional_information` (string, nullable)
    Additional information about the reason for the reversal.

  - `reversal.return_reason_code` (string, nullable)
    A code provided by the sending bank giving a reason for the reversal. The common return reason codes are [documented here](/documentation/wire-reversals#reversal-reason-codes).

  - `reversal.return_reason_code_description` (string, nullable)
    An Increase-generated description of the `return_reason_code`.

  - `reversal.transaction_id` (string)
    The ID for the Transaction associated with the transfer reversal.

  - `reversal.wire_transfer_id` (string)
    The ID for the Wire Transfer that is being reversed.

- `routing_number` (string)
  The American Bankers' Association (ABA) Routing Transit Number (RTN).

- `source_account_number_id` (string, nullable)
  The Account Number that was passed to the wire's recipient.

- `status` (enum)
  The lifecycle status of the transfer.
  Cases:
  * `pending_approval` (The transfer is pending approval.)
  * `canceled` (The transfer has been canceled.)
  * `pending_reviewing` (The transfer is pending review by Increase.)
  * `rejected` (The transfer has been rejected by Increase.)
  * `requires_attention` (The transfer requires attention from an Increase operator.)
  * `pending_creating` (The transfer is pending creation.)
  * `reversed` (The transfer has been reversed.)
  * `submitted` (The transfer has been submitted to Fedwire.)
  * `complete` (The transfer has been acknowledged by Fedwire and can be considered complete.)

- `submission` (dictionary, nullable)
  After the transfer is submitted to Fedwire, this will contain supplemental details.

  - `submission.input_message_accountability_data` (string)
    The accountability data for the submission.

  - `submission.submitted_at` (string)
    When this wire transfer was submitted to Fedwire.

- `transaction_id` (string, nullable)
  The ID for the transaction funding the transfer.

- `type` (string)
  A constant representing the object's type. For this resource it will always be `wire_transfer`.

- `unique_end_to_end_transaction_reference` (string, nullable)
  The unique end-to-end transaction reference ([UETR](https://www.swift.com/payments/what-unique-end-end-transaction-reference-uetr)) of the transfer.

## Sandbox: Reverse a Wire Transfer
POST /simulations/wire_transfers/{wire_transfer_id}/reverse
> Simulates the reversal of a [Wire Transfer](#wire-transfers) by the Federal Reserve due to error conditions. This will also create a [Transaction](#transaction) to account for the returned funds. This Wire Transfer must first have a `status` of `complete`.
### Example
```curl
curl -X "POST" \
  --url "${INCREASE_URL}/simulations/wire_transfers/wire_transfer_5akynk7dqsq25qwk9q2u/reverse" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}"
```
### Path Parameters
- `wire_transfer_id` (string, required)
  The identifier of the Wire Transfer you wish to reverse.

## Sandbox: Submit a Wire Transfer
POST /simulations/wire_transfers/{wire_transfer_id}/submit
> Simulates the submission of a [Wire Transfer](#wire-transfers) to the Federal Reserve. This transfer must first have a `status` of `pending_approval` or `pending_creating`.
### Example
```curl
curl -X "POST" \
  --url "${INCREASE_URL}/simulations/wire_transfers/wire_transfer_5akynk7dqsq25qwk9q2u/submit" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}"
```
### Path Parameters
- `wire_transfer_id` (string, required)
  The identifier of the Wire Transfer you wish to submit.

## List Wire Transfers
GET /wire_transfers

### Example
```curl
curl \
  --url "${INCREASE_URL}/wire_transfers?account_id=account_in71c4amph0vgo2qllky" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}"
```

### Query Parameters
- `cursor` (string, optional)
  Return the page of entries after this one.

- `limit` (integer, optional)
  Limit the size of the list that is returned. The default (and maximum) is 100 objects.

- `account_id` (string, optional)
  Filter Wire Transfers to those belonging to the specified Account.

- `external_account_id` (string, optional)
  Filter Wire Transfers to those made to the specified External Account.

- `idempotency_key` (string, optional)
  Filter records to the one with the specified `idempotency_key` you chose for that object. This value is unique across Increase and is used to ensure that a request is only processed once. Learn more about [idempotency](https://increase.com/documentation/idempotency-keys).

- `status.in` (array of enums, optional)
  Return results whose value is in the provided list. For GET requests, this should be encoded as a comma-delimited string, such as `?in=one,two,three`.
  Cases:
  * `pending_approval` (The transfer is pending approval.)
  * `canceled` (The transfer has been canceled.)
  * `pending_reviewing` (The transfer is pending review by Increase.)
  * `rejected` (The transfer has been rejected by Increase.)
  * `requires_attention` (The transfer requires attention from an Increase operator.)
  * `pending_creating` (The transfer is pending creation.)
  * `reversed` (The transfer has been reversed.)
  * `submitted` (The transfer has been submitted to Fedwire.)
  * `complete` (The transfer has been acknowledged by Fedwire and can be considered complete.)

- `created_at.after` (string, optional)
  Return results after this [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp.

- `created_at.before` (string, optional)
  Return results before this [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp.

- `created_at.on_or_after` (string, optional)
  Return results on or after this [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp.

- `created_at.on_or_before` (string, optional)
  Return results on or before this [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp.

### Returns a Wire Transfer List object:
```json
{
  "data": [
    {
      "account_id": "account_in71c4amph0vgo2qllky",
      "account_number": "987654321",
      "amount": 100,
      "approval": {
        "approved_at": "2020-01-31T23:59:59Z",
        "approved_by": null
      },
      "cancellation": null,
      "created_at": "2020-01-31T23:59:59Z",
      "created_by": {
        "category": "user",
        "user": {
          "email": "user@example.com"
        }
      },
      "creditor": {
        "address": {
          "unstructured": {
            "line1": "33 Liberty Street",
            "line2": null,
            "line3": null
          }
        },
        "name": "National Phonograph Company"
      },
      "currency": "USD",
      "debtor": null,
      "external_account_id": "external_account_ukk55lr923a3ac0pp7iv",
      "id": "wire_transfer_5akynk7dqsq25qwk9q2u",
      "idempotency_key": null,
      "inbound_wire_drawdown_request_id": null,
      "network": "wire",
      "pending_transaction_id": null,
      "remittance": {
        "category": "unstructured",
        "unstructured": {
          "message": "Invoice 29582"
        }
      },
      "reversal": null,
      "routing_number": "101050001",
      "source_account_number_id": null,
      "status": "complete",
      "submission": null,
      "transaction_id": "transaction_uyrp7fld2ium70oa7oi",
      "type": "wire_transfer",
      "unique_end_to_end_transaction_reference": null
    }
  ],
  "next_cursor": "v57w5d"
}
```

## Create a Wire Transfer
POST /wire_transfers

### Example
```curl
curl -X "POST" \
  --url "${INCREASE_URL}/wire_transfers" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d $'{
    "account_id": "account_in71c4amph0vgo2qllky",
    "account_number": "987654321",
    "amount": 100,
    "creditor": {
      "address": {
        "unstructured": {
          "line1": "33 Liberty Street",
          "line2": "New York",
          "line3": "NY 10045"
        }
      },
      "name": "Ian Crease"
    },
    "remittance": {
      "category": "unstructured",
      "unstructured": {
        "message": "New account transfer"
      }
    },
    "routing_number": "101050001"
  }'
```

### Body Parameters
- `account_id` (string, required)
  The identifier for the account that will send the transfer.

- `account_number` (string, optional)
  The account number for the destination account.

- `amount` (integer, required)
  The transfer amount in USD cents.

- `creditor` (dictionary, required)
  The person or business that is receiving the funds from the transfer.

  - `creditor.address` (dictionary, optional)
    The person or business's address.

      - `creditor.address.unstructured` (dictionary, required)
        Unstructured address lines.

            - `creditor.address.unstructured.line1` (string, required)
              The address line 1.

            - `creditor.address.unstructured.line2` (string, optional)
              The address line 2.

            - `creditor.address.unstructured.line3` (string, optional)
              The address line 3.

  - `creditor.name` (string, required)
    The person or business's name.

- `debtor` (dictionary, optional)
  The person or business whose funds are being transferred. This is only necessary if you're transferring from a commingled account. Otherwise, we'll use the associated entity's details.

  - `debtor.address` (dictionary, optional)
    The person or business's address.

      - `debtor.address.unstructured` (dictionary, required)
        Unstructured address lines.

            - `debtor.address.unstructured.line1` (string, required)
              The address line 1.

            - `debtor.address.unstructured.line2` (string, optional)
              The address line 2.

            - `debtor.address.unstructured.line3` (string, optional)
              The address line 3.

  - `debtor.name` (string, required)
    The person or business's name.

- `external_account_id` (string, optional)
  The ID of an External Account to initiate a transfer to. If this parameter is provided, `account_number` and `routing_number` must be absent.

- `inbound_wire_drawdown_request_id` (string, optional)
  The ID of an Inbound Wire Drawdown Request in response to which this transfer is being sent.

- `remittance` (dictionary, required)
  Additional remittance information related to the wire transfer.

  - `remittance.category` (enum, required)
    The type of remittance information being passed.
    Cases:
    * `unstructured` (The wire transfer contains unstructured remittance information.)
    * `tax` (The wire transfer is for tax payment purposes to the Internal Revenue Service (IRS).)

  - `remittance.tax` (dictionary, optional)
    Internal Revenue Service (IRS) tax repayment information. Required if `category` is equal to `tax`.

      - `remittance.tax.date` (string, required)
        The month and year the tax payment is for, in YYYY-MM-DD format. The day is ignored.

      - `remittance.tax.identification_number` (string, required)
        The 9-digit Tax Identification Number (TIN) or Employer Identification Number (EIN).

      - `remittance.tax.type_code` (string, required)
        The 5-character tax type code.

  - `remittance.unstructured` (dictionary, optional)
    Unstructured remittance information. Required if `category` is equal to `unstructured`.

      - `remittance.unstructured.message` (string, required)
        The information.

- `require_approval` (boolean, optional)
  Whether the transfer requires explicit approval via the dashboard or API.

- `routing_number` (string, optional)
  The American Bankers' Association (ABA) Routing Transit Number (RTN) for the destination account.

- `source_account_number_id` (string, optional)
  The ID of an Account Number that will be passed to the wire's recipient

## Retrieve a Wire Transfer
GET /wire_transfers/{wire_transfer_id}

### Example
```curl
curl \
  --url "${INCREASE_URL}/wire_transfers/wire_transfer_5akynk7dqsq25qwk9q2u" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}"
```
### Path Parameters
- `wire_transfer_id` (string, required)
  The identifier of the Wire Transfer.

## Approve a Wire Transfer
POST /wire_transfers/{wire_transfer_id}/approve

### Example
```curl
curl -X "POST" \
  --url "${INCREASE_URL}/wire_transfers/wire_transfer_5akynk7dqsq25qwk9q2u/approve" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}"
```
### Path Parameters
- `wire_transfer_id` (string, required)
  The identifier of the Wire Transfer to approve.

## Cancel a pending Wire Transfer
POST /wire_transfers/{wire_transfer_id}/cancel

### Example
```curl
curl -X "POST" \
  --url "${INCREASE_URL}/wire_transfers/wire_transfer_5akynk7dqsq25qwk9q2u/cancel" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}"
```
### Path Parameters
- `wire_transfer_id` (string, required)
  The identifier of the pending Wire Transfer to cancel.