Validate

Request URL

POST /transfer-to/ach/validate

Description

This endpoint accepts the same parameters as the /transfer-to/ach/create endpoint and returns a similar response (including an example cFiTransactionId and mocked "Initiated" status), but instead of submitting the ACH transaction request for payment or recording the request details in the connectFi database, this endpoint will instead simply validate the request. If the response includes the "code": "0" parameter, the request details are valid. To submit a valid request for payment via ACH, a separate request should be made to the /transfer-to/ach/create endpoint.

Note: Since this endpoint does not submit the request for payment or record the request details in the connectFi database, request details validated using this endpoint will not be returned via a /transfer-to/ach/query or /transfer-to/ach/list request.

Schema

Property table for transfer-to/ach/validate

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": "UNIQUEREFERENCEID",
    "effectiveEntryDate": "2024-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": "UNIQUEREFERENCEID",
    "effectiveEntryDate": "2024-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/validate',
  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/validate" --data "{\"reference\":\"UNIQUEREFERENCEID\",   \"effectiveEntryDate\":\"2024-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 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": "UNIQUEREFERENCEID",
    "effectiveEntryDate": "2024-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"
}

RESPONSE BODY

{
    "code": "0",
    "data": {
        "cFiTransactionId": "CLIENTID_2WrLHSRsVCPZi5vqdMrDcM",
        "reference": "UNIQUEREFERENCEID",
        "cFiAggregatorId": "CLIENTID",
        "status": "Initiated",
        "effectiveEntryDate": "2024-11-13",
        "individualName": "John Smith",
        "routingNumber": "053207766",
        "amount": 10.53,
        "currency": "USD",
        "DFIAccountNumber": "123456789"
    },
    "requestId": "60ae7bb0a1cd11efadaf56da8a860aa8"
}