Skip to content

Send a Wire

Request URL

POST /transfer-to/wire

Description

This endpoint transfers funds from your bank (originator) to a specified account at another bank (beneficiary) within the U.S.

The /transfer-to/wire endpoint supports idempotency and will not accept requests with duplicate reference IDs. The external reference ID included in the request body is how connectFi controls for duplicate transactions. It is important to note that wire transactions submitted with unique reference IDs will not be considered duplicates, even if there are other properties with identical values. For example, the following wire transfers are not considered duplicates.

{
    "amount": 1.01,
    "currency": "USD",
    "endUserAccount": "12345678901234567",
    "reference": "EXT_REFERENCE_ID1", //Different reference IDS
    "originator": {
        "commonName": "John Doe",
        "legalName": "John Doe",
        "address": {
            "addressLine1": "999 Main Street",
            "addressLine2": "Ste. A",
            "city": "San Francisco",
            "state": "CA",
            "postalCode": "12345",
            "country": "US"
        }
    },
    "beneficiary": {
        "bankName": "Unicorn Bank",
        "bankABANumber": "123456789",
        "accountNumber": "12345678",
        "name": "John Smith",
        "address": {
            "addressLine1": "1346 Pleasant Ave",
            "addressLine2": "Apt A123",
            "city": "Salt Lake City",
            "state": "UT",
            "postalCode": "12345",
            "country": "US"
        }
    },
    "narrative": "Both of these wire transfers will post",
    "memos": [
        "Some message or note",
        "Another message or note"
    ],
    "webhookURL": "https://your_webhook_url/EXT_REFERENCE_ID1"
}
{
    "amount": 1.01,
    "currency": "USD",
    "endUserAccount": "12345678901234567",
    "reference": "EXT_REFERENCE_ID2", //Different reference IDS
    "originator": { //exact same originator details
    },
    "beneficiary": { //exact same beneficiary details
    },
    "narrative": "Both of these wire transfers will post",
    "memos": [
        "Some message or note",
        "Another message or note"
    ],
    "webhookURL": "https://your_webhook_url/EXT_REFERENCE_ID1"
}

If a wire will exceed the current available balance in the sending account, then the transaction will be saved as "Initiated", an alert will be sent to the configured alert email address to ensure that the correct balance is available, and the wire will be reattempted on a job schedule.

The alert sent will include the following.

    subject: "Wire Amount will exceed available balance",
    text: `Wire initialized, but not yet sent. Will retry sending wire. Please ensure correct balance is available.\r\n
    cFiAggregatorId: CLIENTID \r\n
    wireMerchantId: 1234567890 \r\n
    amount: $16.97 \r\n
    currency: USD \r\n`

If a wire is sent during nightly maintenance, the transaction is saved as "Initiated" and automatically retried when the back office has completed nightly maintenance. Typically nightly updates are done between approximately midnight and 4 am CST. Actual nightly update hours may vary.

Schema

Property table for transfer-to/wire

Property Description Required Schema
wireAccountToken The wireAccountToken that corresponds to the desired account from which to transfer funds. If not included, the default wireAccountToken configuration for this client will be used. Contact support to add or update wireAccountToken configurations. No {
  "type": "string",
  "pattern": "^((?![<>]).)*$",
  "minLength": 0,
  "maxLength": 100,
  "nullable": true,
  "description": "common-commonStr100"
}
amount amount Yes {
  "type": "number",
  "exclusiveMinimum": 0,
  "amountPrecision": 2,
  "description": "common-amount"
}
currency A three character ISO alphabetic code to identify the currency Yes {
  "type": "string",
  "maxLength": 3,
  "minLength": 3,
  "pattern": "^[A-Z]+$",
  "description": "common-currency"
}
endUserAccount The vAccount number that is used to fund the wire transfer Yes {
  "type": "string",
  "pattern": "^[0-9]+$",
  "minLength": 12,
  "maxLength": 16,
  "description": "transferTo-enduserAccount"
}
reference An external alphanumeric reference ID for the entity in your system Yes {
  "type": "string",
  "pattern": "^[0-9a-zA-Z]+$",
  "minLength": 1,
  "maxLength": 32,
  "description": "common-reference"
}
originator The details of the sender Yes transferTo originator object
beneficiary The details of the recipient Yes transferTo beneficiary object
narrative A brief description Yes {
  "type": "string",
  "pattern": "^((?![<>]).)*$",
  "minLength": 0,
  "maxLength": 500,
  "nullable": true,
  "description": "common-commonStr500"
}
memos An array containing memo notes Yes array of {
  "type": "string",
  "pattern": "^((?![<>]).)*$",
  "minLength": 0,
  "maxLength": 35,
  "nullable": true,
  "description": "common-commonStr35"
}
webhookURL If you specify a webhookURL in this request, the system will perform a callback to your webhookURL to notify you of specified asynchronous status changes. No {
  "type": "string",
  "pattern": "^((?![<>]).)*$",
  "minLength": 0,
  "maxLength": 500,
  "nullable": true,
  "description": "common-commonStr500"
}

Property table for transferTo address object

Property Description Required Schema
addressLine1 addressLine1 Yes {
  "type": "string",
  "pattern": "^((?![<>]).)*$",
  "minLength": 1,
  "maxLength": 35,
  "isNotOnlyWhitespace": true,
  "description": "common-commonStr35Req"
}
addressLine2 addressLine2 No {
  "type": "string",
  "pattern": "^((?![<>]).)*$",
  "minLength": 0,
  "maxLength": 35,
  "nullable": true,
  "description": "common-commonStr35"
}
city city Yes {
  "type": "string",
  "pattern": "^((?![<>]).)*$",
  "minLength": 1,
  "maxLength": 50,
  "isNotOnlyWhitespace": true,
  "description": "common-commonStr50Req"
}
state state Yes {
  "type": "string",
  "pattern": "^((?![<>]).)*$",
  "minLength": 1,
  "maxLength": 50,
  "isNotOnlyWhitespace": true,
  "description": "common-commonStr50Req"
}
postalCode postalCode Yes {
  "type": "string",
  "pattern": "^[0-9a-zA-Z-]+$",
  "minLength": 5,
  "maxLength": 10,
  "description": "customer-postalCode"
}
country country Yes {
  "type": "string",
  "pattern": "^((?![<>]).)*$",
  "minLength": 1,
  "maxLength": 50,
  "isNotOnlyWhitespace": true,
  "description": "common-commonStr50Req"
}

Property table for transferTo beneficiary object

Property Description Required Schema
bankName Bank name Yes {
  "type": "string",
  "pattern": "^((?![<>]).)*$",
  "minLength": 1,
  "maxLength": 35,
  "isNotOnlyWhitespace": true,
  "description": "common-commonStr35Req"
}
bankABANumber Bank ABA routing number Yes {
  "type": "string",
  "minLength": 9,
  "maxLength": 9,
  "description": "common-routingNumber"
}
accountNumber The account number Yes {
  "type": "string",
  "pattern": "^((?![<>]).)*$",
  "minLength": 1,
  "maxLength": 50,
  "isNotOnlyWhitespace": true,
  "description": "common-commonStr50Req"
}
name name Yes {
  "type": "string",
  "pattern": "^((?![<>]).)*$",
  "minLength": 1,
  "maxLength": 50,
  "isNotOnlyWhitespace": true,
  "description": "common-commonStr50Req"
}
address An object containing address details Yes transferTo address object

Property table for transferTo originator object

Property Description Required Schema
commonName commonName Yes {
  "type": "string",
  "pattern": "^((?![<>]).)*$",
  "minLength": 1,
  "maxLength": 50,
  "isNotOnlyWhitespace": true,
  "description": "common-commonStr50Req"
}
legalName The legal name of the payer. (Note: If the payer is a business, the "legalName" property is required instead of the "firstName" and "lastName" properties) Yes {
  "type": "string",
  "pattern": "^((?![<>]).)*$",
  "minLength": 1,
  "maxLength": 50,
  "isNotOnlyWhitespace": true,
  "description": "common-commonStr50Req"
}
address An object containing address details Yes transferTo address object

Request Body

{
    "amount": 16.53,
    "currency": "USD",
    "endUserAccount": "1234567890123456",
    "reference": "UNIQUE_REFERENCE_ID",
    "originator": {
        "commonName": "John Doe",
        "legalName": "John Doe",
        "address": {
            "addressLine1": "999 Main Street",
            "addressLine2": "Ste. A",
            "city": "San Francisco",
            "state": "CA",
            "postalCode": "12345",
            "country": "US"
        }
    },
    "beneficiary": {
        "bankName": "Unicorn Bank",
        "bankABANumber": "122244184",
        "accountNumber": "1234567890123456",
        "name": "John Smith",
        "address": {
            "addressLine1": "1346 Pleasant Ave",
            "addressLine2": "Apt A123",
            "city": "Salt Lake City",
            "state": "UT",
            "postalCode": "12345",
            "country": "US"
        }
    },
    "narrative": "Invoice #123 for May",
    "memos": [
        "For spare parts per contract #123",
        "Delivered Salt Lake City UT 12345"
    ],
    "webhookURL": "https://your_webhook_url/UNIQUE_REFERENCE_ID"
}

Snippet Examples

javascript

const axios = require('axios');
const data = {
    "amount": 16.53,
    "currency": "USD",
    "endUserAccount": "1234567890123456",
    "reference": "UNIQUE_REFERENCE_ID",
    "originator": {
        "commonName": "John Doe",
        "legalName": "John Doe",
        "address": {
            "addressLine1": "999 Main Street",
            "addressLine2": "Ste. A",
            "city": "San Francisco",
            "state": "CA",
            "postalCode": "12345",
            "country": "US"
        }
    },
    "beneficiary": {
        "bankName": "Unicorn Bank",
        "bankABANumber": "122244184",
        "accountNumber": "1234567890123456",
        "name": "John Smith",
        "address": {
            "addressLine1": "1346 Pleasant Ave",
            "addressLine2": "Apt A123",
            "city": "Salt Lake City",
            "state": "UT",
            "postalCode": "12345",
            "country": "US"
        }
    },
    "narrative": "Invoice #123 for May",
    "memos": [
        "For spare parts per contract #123",
        "Delivered Salt Lake City UT 12345"
    ],
    "webhookURL": "https://your_webhook_url/UNIQUE_REFERENCE_ID"
};
const config = {
  method: 'POST',
  url: '${CONNECTFI_BASE_URL}/transfer-to/wire',
  headers: {
    'Content-Type': "application/json",
    'x-connectfi-token': "A long random string token received from /auth/get-token request"
  },
  data
};

let result;
try {
  result = await axios.request(config);
  if (result.status === 200) {
    console.log(JSON.stringify(result.data));
  }
} catch (err) {
  console.log({
    errCode: err.code,
    responseStatus: err.response && err.response.status,
    data: err.response && JSON.stringify(err.response.data)
  });
}

cURL

curl --location "CONNECTFI_BASE_URL/transfer-to/wire" --data "{    \"amount\":16.53,   \"currency\":\"USD\",   \"endUserAccount\":\"1234567890123456\",   \"reference\":\"UNIQUE_REFERENCE_ID\",   \"originator\":{        \"commonName\":\"John Doe\",       \"legalName\":\"John Doe\",       \"address\":{            \"addressLine1\":\"999 Main Street\",           \"addressLine2\":\"Ste. A\",           \"city\":\"San Francisco\",           \"state\":\"CA\",           \"postalCode\":\"12345\",           \"country\":\"US\"        }    },   \"beneficiary\":{        \"bankName\":\"Unicorn Bank\",       \"bankABANumber\":\"122244184\",       \"accountNumber\":\"1234567890123456\",       \"name\":\"John Smith\",       \"address\":{            \"addressLine1\":\"1346 Pleasant Ave\",           \"addressLine2\":\"Apt A123\",           \"city\":\"Salt Lake City\",           \"state\":\"UT\",           \"postalCode\":\"12345\",           \"country\":\"US\"        }    },   \"narrative\":\"Invoice #123 for May\",   \"memos\":[        \"For spare parts per contract #123\",       \"Delivered Salt Lake City UT 12345\"    ],   \"webhookURL\":\"https://your_webhook_url/UNIQUE_REFERENCE_ID\"}" --header "Content-Type: application/json" --header "x-connectfi-token: A long random string token received from /auth/get-token request"

Successful Response Examples

200 TRANSFER-TO/WIRE SUCCESSFUL RESPONSE

HEADERS

Header Value
Content-Type application/json
x-connectfi-token A long random string token received from /auth/get-token request

REQUEST BODY

{
    "amount": 1.01,
    "currency": "USD",
    "endUserAccount": "1234567890123456",
    "reference": "externalTrnId1341",
    "originator": {
        "commonName": "John Doe",
        "legalName": "John Doe",
        "address": {
            "addressLine1": "999 Main Street",
            "addressLine2": "Ste. A",
            "city": "San Francisco",
            "state": "CA",
            "postalCode": "12345",
            "country": "US"
        }
    },
    "beneficiary": {
        "bankName": "Unicorn Bank",
        "bankABANumber": "122244184",
        "accountNumber": "1234567890123456",
        "name": "John Smith",
        "address": {
            "addressLine1": "1346 Pleasant Ave",
            "addressLine2": "Apt A123",
            "city": "Salt Lake City",
            "state": "UT",
            "postalCode": "12345",
            "country": "US"
        }
    },
    "narrative": "Invoice #123 for May",
    "memos": [
        "For spare parts per contract #123",
        "Delivered Salt Lake City UT 12345"
    ],
    "webhookURL": "https://your_webhook_url/externalTrnId1341"
}

RESPONSE BODY

{
    "code": "0",
    "data": {
        "reference": "externalTrnId1341",
        "cFiTransactionId": "CLIENTID_5r5ESJN8CEJZpFdfK2nqjE",
        "amount": 1.01,
        "currency": "USD",
        "transactionReceiptId": "JW2QGEHYI0",
        "status": "Sent",
        "dtsCreatedAt": "2023-10-24T12:34:38.938Z"
    },
    "requestId": "b2a2a480726911ee8ff83020a7305d12"
}

200 TRANSFER-TO/WIRE "NIGHTLY_UPDATES" TRIGGER AMOUNT USED 16.95

HEADERS

Header Value
Content-Type application/json
x-connectfi-token A long random string token received from /auth/get-token request

REQUEST BODY

{
    "amount": 16.95,
    "currency": "USD",
    "endUserAccount": "1234567890123456",
    "reference": "externalTrnId2170",
    "originator": {
        "commonName": "John Doe",
        "legalName": "John Doe",
        "address": {
            "addressLine1": "999 Main Street",
            "addressLine2": "Ste. A",
            "city": "San Francisco",
            "state": "CA",
            "postalCode": "12345",
            "country": "US"
        }
    },
    "beneficiary": {
        "bankName": "Unicorn Bank",
        "bankABANumber": "122244184",
        "accountNumber": "1234567890123456",
        "name": "John Smith",
        "address": {
            "addressLine1": "1346 Pleasant Ave",
            "addressLine2": "Apt A123",
            "city": "Salt Lake City",
            "state": "UT",
            "postalCode": "12345",
            "country": "US"
        }
    },
    "narrative": "Invoice #123 for May",
    "memos": [
        "For spare parts per contract #123",
        "Delivered Salt Lake City UT 12345"
    ],
    "webhookURL": "https://your_webhook_url/externalTrnId2170"
}

RESPONSE BODY

{
    "code": "0",
    "data": {
        "reference": "externalTrnId2170",
        "cFiTransactionId": "CLIENTID_6jxBgN2DJP9dJ2vRKxyuaJ",
        "amount": 16.95, //set sandbox value amount = 16.95 to test "Nightly_Updates" message. The transaction is saved as Initiated and retried
        "currency": "USD",
        "SC": 500, //back office status, will be saved in connectFi and retried automatically after nightly maintenance
        "transactionDelayedCode": "Nightly_Updates",
        "status": "Initiated",
        "dtsCreatedAt": "2024-02-16T18:47:18.522Z"
    },
    "requestId": "cf7dcd90ccfb11eebb061f991c0df212"
}

200 TRANSFER-TO/WIRE "AMOUNT EXCEEDS BALANCE" TRIGGER AMOUNT USED 16.97

HEADERS

Header Value
Content-Type application/json
x-connectfi-token A long random string token received from /auth/get-token request

REQUEST BODY

{
    "amount": 16.97,
    "currency": "USD",
    "endUserAccount": "1234567890123456",
    "reference": "externalTrnId1342",
    "originator": {
        "commonName": "John Doe",
        "legalName": "John Doe",
        "address": {
            "addressLine1": "999 Main Street",
            "addressLine2": "Ste. A",
            "city": "San Francisco",
            "state": "CA",
            "postalCode": "12345",
            "country": "US"
        }
    },
    "beneficiary": {
        "bankName": "Unicorn Bank",
        "bankABANumber": "122244184",
        "accountNumber": "1234567890123456",
        "name": "John Smith",
        "address": {
            "addressLine1": "1346 Pleasant Ave",
            "addressLine2": "Apt A123",
            "city": "Salt Lake City",
            "state": "UT",
            "postalCode": "12345",
            "country": "US"
        }
    },
    "narrative": "Invoice #123 for May",
    "memos": [
        "For spare parts per contract #123",
        "Delivered Salt Lake City UT 12345"
    ],
    "webhookURL": "https://your_webhook_url/externalTrnId1342"
}

RESPONSE BODY

{
    "code": "0",
    "data": {
        "reference": "externalTrnId1458",
        "cFiTransactionId": "CLIENTID_YEhoCaCSN6tNyRk6ETJjY",
        "amount": 16.97, //set sandbox value amount = 16.97 to test "Amount_Exceeds_Balance" insufficient funds alert message. The transaction is saved as Initiated and retried
        "currency": "USD",
        "SC": 409, //back office status, will be saved in connectFi and retried automatically
        "transactionDelayedCode": "Amount_Exceeds_Balance",
        "status": "Initiated",
        "dtsCreatedAt": "2023-11-09T14:27:35.087Z"
    },
    "requestId": "202254c07f0c11ee9e3bd5975edcd412"
}