Skip to content

Create Payment

Request URL

POST /transfer-to/ach/create

Description

This endpoint requests a funds transfer from your (originator) account at our banking partner (ODFI) to a specified account at the recipient's bank (RDFI) through the Automated Clearing House network. ACH payment requests received through API endpoint calls are delivered electronically in NACHA formatted batch files to the ODFI (Originating Depository Financial Institution) via SFTP. The files are then sent electronically to the RDFI (Receiving Depository Financial Institution), where the debits and credits are applied to the recipient's account.

The /transfer-to/ach/create 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 ACH transactions submitted with unique reference IDs will not be considered duplicates, even if there are other properties with identical values. For example, the following ACH payments are not considered duplicates.

{
    "reference": "extTrnAch125",  //Different reference IDS, both transactions will post
    "effectiveEntryDate": "2023-06-28",
    "standardEntryClassCode": "WEB",
    "individualName": "John Smith",
    "routingNumber": "123456789",
    "DFIAccountNumber": "123456789",
    "accountType": "Checking",
    "transactionType": "Credit",
    "amount": 7.15,
    "currency": "USD",
    "companyEntryDescription": "PAYMENT",
    "webhookUrl": "https://your_webhook_url/extTrnAch125"
}
{
    "reference": "extTrnAch126",  //Different reference IDS, both transactions will post
    "effectiveEntryDate": "2023-06-28",
    "standardEntryClassCode": "WEB",
    "individualName": "John Smith",
    "routingNumber": "123456789",
    "DFIAccountNumber": "123456789",
    "accountType": "Checking",
    "transactionType": "Credit",
    "amount": 7.15,
    "currency": "USD",
    "companyEntryDescription": "PAYMENT",
    "webhookUrl": "https://your_webhook_url/extTrnAch125"
}

Schema

Property table for transfer-to/ach/create

Property Description Required Schema
reference An external alphanumeric reference ID for the entity in your system Yes {
  "type": "string",
  "pattern": "^[0-9a-zA-Z]+$",
  "minLength": 1,
  "maxLength": 32,
  "$id": "common-reference"
}
clientCode The clientCode in connectFi that corresponds to the desired ACH configurations for companyName and companyId. If not included, the default ACH solution configuration for this client will be used. Contact support to update ACH configurations. Example - If clientCode: "name1" is configured to use ACH { companyName: "COABC", companyId: "123abc456def789" } and clientCode: "name2" is configured to use ACH { companyName: "COABD", companyId: "123abc456def780" }, then including the clientCode parameter will specify which configuration to use. If not included, the default "name1" configuration would be used in this example. No {
  "type": "string",
  "pattern": "^((?![<>]).)*$",
  "minLength": 0,
  "maxLength": 50,
  "nullable": true,
  "$id": "common-commonStr50"
}
effectiveEntryDate The effective entry date in YYYY-MM-DD format Yes {
  "type": "string",
  "format": "dateISO",
  "pattern": "^\d{4}-\d{2}-\d{2}$",
  "$id": "common-dateOnly"
}
standardEntryClassCode The Standard Entry Class (SEC) Code indicating the nature of the transaction and applicable conditions for each Yes {
  "type": "string",
  "enum": [ "ARC", "BOC", "CIE", "CCD", "CTX", "POP",
"PPD", "RCK", "TEL", "WEB" ],
  "maxLength": 3,
  "$id": "ach-standardEntryClassCode"
}
companyEntryDescription A description of this payment, such as "PAYROLL", "PAYMENT", "REDEPCHECK" (necessary when standardEntryClassCode is "RCK"), or "AUTOENROLL", max length: 10 characters No {
  "type": "string",
  "maxLength": 10,
  "nullable": true,
  "isNotOnlyWhitespace": true,
  "$id": "ach-companyEntryDescription"
}
companyDiscretionaryData Optional codes included by the ACH originating company, max length: 20 characters No {
  "type": "string",
  "maxLength": 20,
  "nullable": true,
  "isNotOnlyWhitespace": true,
  "$id": "ach-companyDiscretionaryData"
}
individualName The name of the ACH payment recipient, max length: 22 characters when SEC is "PPD", "TEL", "WEB", "PPD", "RCK", "ARC", "BOC", or "POP" (and for returns), max length: 16 characters when SEC is "CTX", max length: 15 characters when SEC is "CIE" Yes {
  "type": "string",
  "minLength": 1,
  "maxLength": 22,
  "isNotOnlyWhitespace": true,
  "$id": "ach-individualName"
}
routingNumber routingNumber Yes {
  "type": "string",
  "pattern": "^[0-9a-zA-Z]+$",
  "minLength": 9,
  "maxLength": 9,
  "$id": "ach-routingNumber"
}
DFIAccountNumber The alphanumeric account number of the recipient Yes {
  "type": "string",
  "pattern": "^[0-9a-zA-Z]+$",
  "minLength": 1,
  "maxLength": 17,
  "$id": "ach-DFIAccountNumber"
}
accountType accountType Yes {
  "type": "string",
  "enum": [ "Checking", "Savings" ],
  "$id": "ach-accountType"
}
transactionType The type of transaction Yes {
  "type": "string",
  "enum": [ "Credit", "Debit" ],
  "$id": "ach-transactionType"
}
amount Amount Yes {
  "type": "number",
  "minimum": 0,
  "amountPrecision": 2,
  "$id": "common-amountWithZero"
}
currency A three character ISO alphabetic code to identify the currency Yes {
  "type": "string",
  "maxLength": 3,
  "minLength": 3,
  "pattern": "^[A-Z]+$",
  "$id": "common-currency"
}
checkSerialNumber Serial number of the digital check (checkSerialNumber is only allowed/required for "ARC", "BOC", "RCK", and "POP" Standard Entry Class types), max length: 15 characters when SEC is "ARC", "BOC", or "RCK", max length: 9 characters when SEC is "POP" No {
  "type": "string",
  "minLength": 1,
  "maxLength": 15,
  "isNotOnlyWhitespace": true,
  "$id": "ach-checkSerialNumber"
}
terminalCity First four characters of the terminal city No {
  "type": "string",
  "maxLength": 4,
  "isNotOnlyWhitespace": true,
  "$id": "ach-terminalCity"
}
terminalState Two character state code No {
  "type": "string",
  "maxLength": 2,
  "isNotOnlyWhitespace": true,
  "$id": "ach-terminalState"
}
identificationNumber Optional additional identifier (identificationNumber is only allowed for "CTX", "CCD", "PPD", "TEL", "WEB", and "CIE" Standard Entry Class types), max length: 22 characters when SEC is "CIE", max length: 15 characters when SEC is "CTX", "CCD", "PPD", "TEL", or "WEB" No {
  "type": "string",
  "minLength": 1,
  "maxLength": 22,
  "isNotOnlyWhitespace": true,
  "$id": "ach-identificationNumber"
}
preNote True if prenotification should be utilized to verify account details before debiting/crediting the recipient's account, amount must be 0.00 if preNote is true No {
  "type": "boolean",
  "nullable": true,
  "$id": "ach-preNote"
}
addenda05 An array of strings with payment related information No array of {
  "type": "string",
  "minLength": 1,
  "maxLength": 80
}
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,
  "$id": "common-commonStr500"
}

Request Body

{
    "reference": "UNIQUE_REFERENCE_ID",
    "effectiveEntryDate": "2023-11-13",
    "standardEntryClassCode": "CCD",
    "individualName": "John Smith",
    "routingNumber": "053207766",
    "DFIAccountNumber": "123456789",
    "accountType": "Checking",
    "transactionType": "Debit",
    "amount": 10.53,
    "currency": "USD",
    "companyEntryDescription": "PAYMENT",
    "webhookUrl": "https://your_webhook_url/UNIQUE_REFERENCE_ID"
}

Snippet Examples

javascript

const axios = require('axios');
const data = {
    "reference": "UNIQUE_REFERENCE_ID",
    "effectiveEntryDate": "2023-11-13",
    "standardEntryClassCode": "CCD",
    "individualName": "John Smith",
    "routingNumber": "053207766",
    "DFIAccountNumber": "123456789",
    "accountType": "Checking",
    "transactionType": "Debit",
    "amount": 10.53,
    "currency": "USD",
    "companyEntryDescription": "PAYMENT",
    "webhookUrl": "https://your_webhook_url/UNIQUE_REFERENCE_ID"
};
const config = {
  method: 'POST',
  url: '${CONNECTFI_BASE_URL}/transfer-to/ach/create',
  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/ach/create" --data "{\"reference\":\"UNIQUE_REFERENCE_ID\",   \"effectiveEntryDate\":\"2023-11-13\",   \"standardEntryClassCode\":\"CCD\",   \"individualName\":\"John Smith\",   \"routingNumber\":\"053207766\",   \"DFIAccountNumber\":\"123456789\",   \"accountType\":\"Checking\",   \"transactionType\":\"Debit\",   \"amount\":10.53,\"currency\":\"USD\",   \"companyEntryDescription\":\"PAYMENT\",   \"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/ACH/CREATE 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

{
    "reference": "extTrnAch450",
    "effectiveEntryDate": "2023-11-03",
    "standardEntryClassCode": "WEB",
    "individualName": "John Smith",
    "routingNumber": "053207766",
    "DFIAccountNumber": "123456789",
    "accountType": "Checking",
    "transactionType": "Credit",
    "amount": 3.15,
    "currency": "USD",
    "companyEntryDescription": "PAYMENT",
    "webhookUrl": "https://your_webhook_url/extTrnAch450"
}

RESPONSE BODY

{
    "code": "0",
    "data": {
        "cFiTransactionId": "CLIENTID_6CX4ofCQ1FuyXL72EFMjfk",
        "reference": "extTrnAch450",
        "cFiAggregatorId": "CLIENTID",
        "status": "Initiated",
        "dtsCreatedAt": "2023-11-02T17:32:52.563Z",
        "effectiveEntryDate": "2023-11-03",
        "individualName": "John Smith",
        "routingNumber": "053207766",
        "amount": 3.15,
        "currency": "USD",
        "DFIAccountNumber": "123456789"
    },
    "requestId": "d9c7356079a511eeb5658f28ab5fe311"
}

200 TRANSFER-TO/ACH/CREATE SUCCESSFUL RESPONSE WITH CLIENTCODE

HEADERS

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

REQUEST BODY

{
    "reference": "extTrnAch456",
    "clientCode": "CLIENTID",
    "effectiveEntryDate": "2023-11-03",
    "standardEntryClassCode": "WEB",
    "individualName": "John Smith",
    "routingNumber": "053207766",
    "DFIAccountNumber": "123456789",
    "accountType": "Checking",
    "transactionType": "Credit",
    "amount": 3.15,
    "currency": "USD",
    "companyEntryDescription": "PAYMENT",
    "webhookUrl": "https://your_webhook_url/extTrnAch456"
}

RESPONSE BODY

{
    "code": "0",
    "data": {
        "cFiTransactionId": "CLIENTID_idcYdatqbKngpf4wVOdma",
        "reference": "extTrnAch456",
        "cFiAggregatorId": "CLIENTID",
        "status": "Initiated",
        "dtsCreatedAt": "2023-11-03T13:51:07.324Z",
        "effectiveEntryDate": "2023-11-03",
        "individualName": "John Smith",
        "routingNumber": "053207766",
        "amount": 3.15,
        "currency": "USD",
        "DFIAccountNumber": "123456789"
    },
    "requestId": "09a562707a5011eeb5658f28ab5fe311"
}