Wire Transfers

Overview

Wire transfers move funds between Highnote financial accounts and external bank accounts via the Fedwire Funds Service. Unlike ACH, wire transfers settle individually in real-time during Fedwire operating hours, making them suitable for high-value, time-sensitive payments.

Key characteristics:

• Speed: Same-day settlement (during Fedwire hours)
• Value: No transaction limit (program limits may apply)
• Finality: Irrevocable once completed
• Cost: Higher than ACH

Transfer directions

Direction	Description
Incoming	Funds received into a Highnote financial account from an external bank
Outgoing	Funds sent from a Highnote financial account to an external bank

Transfer statuses

Wire transfers progress through the following statuses:

Status	Description
PENDING	Transfer has been scheduled
PROCESSING	Transfer is being processed
COMPLETED	Funds have been deposited
FAILED	Transfer failed (see WireStatusReasonCode for details)

Initiate an incoming wire transfer

Use the following mutation to initiate a wire transfer into a Highnote financial account. This creates a review workflow event that must be approved before the transfer is processed.

InitiateAddWiredFundsToFinancialAccount

Query

mutation InitiateAddWiredFundsToFinancialAccount(
  $input: InitiateAddWiredFundsToFinancialAccountInput!
) {
  initiateAddWiredFundsToFinancialAccount(input: $input) {
    __typename
    ... on ReviewWorkflowEvent {
      id
      reviewState
      createdAt
      updatedAt
      transfer {
        __typename
        ... on WireTransfer {
          id
          type
        }
      }
      reviewItem {
        __typename
        ... on WireTransferReview {
          toFinancialAccount {
            __typename
            id
          }
          memo
          amount {
            ... on Amount {
              currencyCode
              value
            }
          }
          externalIdentifier
        }
      }
    }
    ... on UserError {
      errors {
        code
      }
    }
    ... on AccessDeniedError {
      message
    }
  }
}

Variables

{
  "input": {
    "toFinancialAccountId": "<FINANCIAL_ACCOUNT_ID>",
    "memo": "240926-HNS",
    "idempotencyKey": "00000000-0000-0000-0000-000000000000",
    "amount": {
      "value": 500000,
      "currencyCode": "USD"
    },
    "externalIdentifier": "an additional reference ID"
  }
}

⚠️ Please login to execute queries. Visit the dashboard to authenticate.

Result

{
  "data": {
    "initiateAddWiredFundsToFinancialAccount": {
      "__typename": "ReviewWorkflowEvent",
      "id": "<REVIEW_WORKFLOW_EVENT_ID>",
      "reviewState": "PENDING",
      "createdAt": "2025-01-23T21:13:41.685Z",
      "updatedAt": "2025-01-23T21:13:41.707Z",
      "transfer": null,
      "reviewItem": {
        "__typename": "WireTransferReview",
        "toFinancialAccount": {
          "__typename": "FinancialAccount",
          "id": "<FINANCIAL_ACCOUNT_ID>"
        },
        "memo": "Initiate workflow approval for wire transfer",
        "amount": {
          "currencyCode": "USD",
          "value": 999999
        },
        "externalIdentifier": "2b43fc97-2541-43fc-8dd6-6ab414ad0a48"
      }
    }
  }
}

The response returns a ReviewWorkflowEvent with reviewState: "PENDING". Once approved, the wire transfer will be processed.

Find wire transfers

After a wire transfer is initiated, use these queries to retrieve transfer details.

Find incoming wire transfer

Use the following query to get an incoming wire transfer by ID:

NodeWireTransfer (Incoming)

Query

query NodeWireTransfer($id: ID!) {
  node(id: $id) {
    __typename
    ... on WireTransfer {
      id
      amount {
        value
        currencyCode
      }
      createdAt
      updatedAt
      memo
      type
      status
      financialAccount {
        id
      }
    }
  }
}

Variables

{
  "id": "<WIRE_TRANSFER_ID>"
}

⚠️ Please login to execute queries. Visit the dashboard to authenticate.

Result

{
  "data": {
    "node": {
      "__typename": "WireTransfer",
      "id": "<WIRE_TRANSFER_ID>",
      "amount": {
        "value": 2000,
        "currencyCode": "USD"
      },
      "createdAt": "1970-01-01T00:01:00.000Z",
      "updatedAt": "1970-01-01T00:02:00.000Z",
      "memo": "This is an incoming wire transfer",
      "type": "INCOMING_WIRE_TRANSFER",
      "status": "COMPLETED",
      "financialAccount": {
        "id": "<FINANCIAL_ACCOUNT_ID>"
      }
    }
  }
}

Find outgoing wire transfer

Use the following query to get an outgoing wire transfer by ID:

NodeWireTransfer (Outgoing)

Query

query NodeWireTransfer($id: ID!) {
  node(id: $id) {
    __typename
    ... on WireTransfer {
      id
      amount {
        value
        currencyCode
      }
      createdAt
      updatedAt
      memo
      type
      status
      financialAccount {
        id
      }
    }
  }
}

Variables

{
  "id": "<WIRE_TRANSFER_ID>"
}

⚠️ Please login to execute queries. Visit the dashboard to authenticate.

Result

{
  "data": {
    "node": {
      "__typename": "WireTransfer",
      "id": "<WIRE_TRANSFER_ID>",
      "amount": {
        "value": 2000,
        "currencyCode": "USD"
      },
      "createdAt": "1970-01-01T00:01:00.000Z",
      "updatedAt": "1970-01-01T00:02:00.000Z",
      "memo": "This is an outgoing wire transfer",
      "type": "OUTGOING_WIRE_TRANSFER",
      "status": "COMPLETED",
      "financialAccount": {
        "id": "<FINANCIAL_ACCOUNT_ID>"
      }
    }
  }
}

Failure reasons

When a wire transfer fails, the WireStatusReasonCode provides details:

Reason Code	Description
ACCOUNT_CLOSED	Source or receiving account is closed
ACCOUNT_NOT_FOUND	Source or receiving account was not found
ACCOUNT_HOLDER_IS_NOT_AN_ORGANIZATION	Receiving account holder is not an organization
CURRENCY_MISMATCH	Source and receiving accounts have different currencies
INSUFFICIENT_FUNDS	Source account has insufficient funds

Simulate wire transfers

In the Test environment, you can simulate wire transfers to test your integration. See Simulate a Wire Transfer for details.