Skip to content

ACH Payments

The connectFi system supports both an ACH API Payments Solution format and an ACH SFTP Batch Payments Solution for processing payments through the Automated Clearing House network.

Section Description
What is ACH? Description of ACH payments and applicable terms
Processing Times Description of the currently supported processing times
Processing Schedule The schedule by which files are processed for the current year
Transfer Amount Limits Transaction amount limitations
ACH API Payments Solution ACH payments through API endpoint calls
ACH SFTP Batch Payments Solution ACH payments through SFTP file transfers

What is ACH?

An ACH (Automated Clearing House) payment is an electronic exchange of funds between accounts at different banks through the ACH network, where one bank originates the transfer (referred to as the Originating Depository Financial Institution, or ODFI) and the other bank receives the transfer (referred to as the Receiving Depository Financial Institution, or RDFI).

Electronic payments through the Automated Clearing House network are cost effective, while still providing the benefit of both security and efficiency. ACH funds transfers are a reliable and universally accepted payment solution that connectFi supports both through API endpoints and through SFTP file transfers to custom fit your business needs.

Customers can originate both debits and credits through the ACH network. An ACH debit is initiated (or originated) by the recipient, and "pulls" the money from the sending account. Examples of ACH debits are utility bill, credit card or loan payments. An ACH credit is initiated (or originated) by the sender, and "pushes" money into the receiving account. Examples of ACH credits are payroll payments, such as direct deposit paychecks and income tax refunds.

For the purpose of this documentation, the terms "payment", "transaction", and "funds transfer" are used interchangeably for both the ACH API Payments Solution and the ACH SFTP Batch Payments Solution. "File transfer" refers to the process by which a CSV file is delivered by you (the client) into a designated SFTP folder secured by an SSH-RSA key pair if you choose to utilize the ACH SFTP Batch Payments Solution.

Back to Top

Processing Times

Transactions can be scheduled Same Day (request must be received by 9:30 AM CST either by API or by file upload), Next Day (request must be received by 7:30 PM CST either by API or by file upload), or Future Dated (up to 10 business days in advance). Settlement typically takes place at the end of the effective date of the scheduled ACH transaction.

Same Day

Same Day ACH requests that are received prior to 9:30 AM CST (Monday-Friday) will be processed and made available that same day. The effective date should be listed as the current date (same day).

Next Day

The effective date of a Next Day ACH is the day after the request is received (either by API call or by SFTP file transfer), as long as the request is received prior to 7:30 pm CST, Monday-Friday. If the request is received after this cut-off time, then the effective date will be the following business day.

Future Dated

Future-dated requests received by 7:30pm CST, Monday-Friday will be processed and made available on the effective date listed in the ACH request. Transactions may be scheduled up to 10 days in advance.

Back to Top

Processing Schedule

Transactions can be processed on most federal holidays (special pricing may apply). Next-Day ACH requests received by the 7:30 pm CST cut off time will be forwarded to the next day to process (except for Saturdays and Christmas Day). ACH files are not processed on Saturdays nor on Christmas Day.

Back to Top

Transfer Amount Limits

The maximum amount sent per single ACH transaction must be less than or equal to the total available account balance. It is your (the client's) responsibility to ensure that the amount available in your settlement account is appropriate to fund your requested transactions. In addition, Same Day transfers are limited to an amount of $1,000,000 or less.

Back to Top

ACH API Payments Solution

The ACH API (Application Programming Interface) solution provides full featured, easy to integrate access to ACH payments through multiple endpoints. This solution is the best option if:

  • your system supports API endpoint calls,
  • you prefer the ability to receive immediate status updates through webhook calls,
  • you prefer on demand access to query or search ACH payments that you have initiated,
  • you prefer on demand access to your return rates data to insure that your ACH return rates remain in compliance with NACHA rules
Endpoint or Section Action
/transfer-to/ach/create Send an ACH funds payment
Standard Entry Class Codes SEC table containing descriptions of Standard Entry Class Codes and conditions for each
/transfer-to/ach/query Query details of one or more ACH payments
/transfer-to/ach/list List ACH payments by search criteria
/transfer-to/ach/return-rates Retrieve return rate data, including number of days out of compliance with NACHA thresholds for administrative return rates, unauthorized return rates, and overall return rates
Webhooks Information about optional webhookUrls
Possible Status Values List and descriptions of possible ACH payment status values

Send an ACH Payment

Request method and 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://webhook.site/53f3a57e-e8b7-4b1b-af99-fa340c2e2b94"
}

{
    "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://webhook.site/53f3a57e-e8b7-4b1b-af99-fa340c2e2b94"
}

The request body properties are described below:

Properties Description Schema Required? Example Values
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. string no "name1"
amount The requested ACH payment amount. If the amount is 0, then the preNote property must have a value of true. number >= 0, up to 2 decimal places yes 16.08
currency A three character ISO alphabetic code to identify the currency string, regex pattern: "^[A-Z]{3}$" yes "USD"
reference An external reference in your system (1-32 alphanumeric characters) string, regex pattern: "^[0-9a-zA-Z]+$", max 32 characters yes "externalTrnId331"
effectiveEntryDate The effective entry date in YYYY-MM-DD format string yes "2023-06-26"
standardEntryClassCode The Standard Entry Class (SEC) Code indicating the nature of the transaction and applicable conditions for each (see Standard Entry Class Codes below). string yes "ARC", "BOC", "CIE", "CCD", "CTX", "POP", "PPD", "RCK", "TEL", or "WEB"
companyEntryDescription A description of this payment, such as "PAYROLL", "PAYMENT", "REDEPCHECK" (necessary when standardEntryClassCode is "RCK"), or "AUTOENROLL", max length: 10 characters string Required for SEC types "ARC", "BOC", "CIE", "CCD", "CTX", "PPD", "RCK", "TEL", and "WEB" "PAYMENT"
companyDiscretionaryData Optional codes included by the ACH originating company, max length: 20 characters string no, can be empty "PayGears ACH"
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" string yes "John Smith"
routingNumber The routing number of the recipient, length: 9 numeric characters string yes "123456789"
DFIAccountNumber The alphanumeric account number of the recipient, max length: 17 characters string yes "1234567890abcdefg"
accountType The type of account for the recipient string yes "Checking" or "Savings"
transactionType The type of transaction string yes "Credit" or "Debit"
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" string Required for SEC types "ARC", "BOC", "POP", and "RCK" "123456789012345"
terminalCity First four characters of the terminal city, max length: 4 characters string Required for SEC type "POP" "Colu"
terminalState Two character state code string Required for SEC type "POP" "SC"
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" string Required for SEC type "CIE" "ACHTrans123"
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, nullable boolean no, can be empty true, false, or undefined
addenda05 An array of strings with payment related information, max items: 9999 array Not allowed for SEC types "ARC", "BOC", "CTX", "TEL", "RCK", and "POP". Optional for SEC types "CIE", "CCD", "PPD", and "WEB" ["Addenda"]
webhookUrl URL which will be called after the ACH payment request. If you specify a webhookUrl in the /transfer-to/ach/create request, the system will perform a callback to your webhookUrl every time the transaction status changes. Refer to Webhooks for the callback format. string, regex pattern: "^.{1,500}$" no "https://webhooktest.examplesite/9ec56257-5190-40a5-abc3-43f757b643abcc123"

Standard Entry Class Codes

SEC Code ACH Application Single/Recurring Debit/Credit Consumer/Corporate Additional Fields Required Fields Not Allowed
"ARC"* Accounts Receivable Entries Single Debit Consumer to Corporate companyEntryDescription, checkSerialNumber addenda05, terminalCity, terminalState, identificationNumber
"BOC"* Back Office Conversion Single Debit Consumer to Corporate companyEntryDescription, checkSerialNumber addenda05, terminalCity, terminalState, identificationNumber
"CIE" Customer Initiated Entries Single Credit Consumer to Corporate identificationNumber, companyEntryDescription terminalCity, terminalState, checkSerialNumber
"CCD" Corporate Credit or Debit Single or Recurring Credit or Debit Corporate to Corporate companyEntryDescription terminalCity, terminalState, checkSerialNumber
"CTX" Corporate Trade Exchange Single or Recurring Credit or Debit Corporate to Corporate companyEntryDescription addenda05, terminalCity, terminalState, checkSerialNumber
"POP" Point of Purchase Single Debit Corporate to Consumer/Corporate to Corporate checkSerialNumber, terminalCity, terminalState addenda05, identificationNumber
"PPD" Pre-arranged Payment or Deposit Single or Recurring Credit or Debit Corporate to Consumer companyEntryDescription terminalCity, terminalState, checkSerialNumber
"RCK" Re-presented Check Entries Single Debit Corporate to Consumer "companyEntryDescription": "REDEPCHECK", checkSerialNumber addenda05, terminalCity, terminalState, identificationNumber
"TEL" Telephone Initiated Entries Single or Recurring Debit Corporate to Consumer companyEntryDescription addenda05, terminalCity, terminalState, checkSerialNumber
"WEB" Internet-Initiated/Mobile Entries Single or Recurring Credit or Debit Corporate to Consumer companyEntryDescription terminalCity, terminalState, checkSerialNumber

*Origination of these SEC codes requires additional approval

Request headers:

{
    "Content-Type": "application/json",
    "x-connectfi-token": "a long random string" //Authorization token received from /auth/get-token request
}

Request body example:

{
    "reference": "extTrnAch126", //unique ID in the client system
    "effectiveEntryDate": "2023-06-28", //date for ACH payment to occur
    "standardEntryClassCode": "WEB", //see Standard Entry Class Codes above
    "individualName": "John Smith", //name of the ACH payment recipient
    "routingNumber": "123456789", //routing number of the recipient
    "DFIAccountNumber": "123456789", //alphanumeric account number of the recipient
    "accountType": "Checking", //type of account for the recipient
    "transactionType": "Credit", //or "Debit"
    "amount": 7.15, //transaction amount
    "currency": "USD", //currency code
    "companyEntryDescription": "PAYMENT", //description of this transaction
    "webhookUrl": "https://webhook.site/53f3a57e-e8b7-4b1b-af99-fa340c2e2b94" //optional webhookURL for callback
}

Possible responses:

200 (HTTP response status code) -- Request for ACH payment was accepted and will be processed. A connectFi ID is assigned to the transaction.

{
    "code": "0", //Success
    "data": {
        "cFiTransactionId": "amplifi_1vAJyVh5B98rtZ7kh2IFIQ", //transaction ID in connectFi
        "reference": "extTrnAch126", //reference from request
        "cFiAggregatorId": "amplifi",
        "effectiveEntryDate": "2023-06-28", //date for ACH payment to occur
        "individualName": "John Smith",
        "routingNumber": "123456789", //routing number of the recipient
        "DFIAccountNumber": "123456789", //alphanumeric account number of the recipient
        "amount": 7.15, //transaction amount
        "currency": "USD", //currency code
        "status": "Initiated", //current status of transaction
        "dtsCreatedAt": "2023-06-27T17:08:10.626Z",
    },
    "requestId": "31891690150d11eeaaa656da8a864a6c"
}

400 (HTTP response status code) -- Incorrect input data:

{
    "requestId": "7d3abc60151211eeaaa656da8a864a6c",
    "code": "requestValidateError",
    "context": [
        {
            "instancePath": "",
            "schemaPath": "#/required",
            "keyword": "required",
            "params": {
                "missingProperty": "effectiveEntryDate"
            },
            "message": "must have required property 'effectiveEntryDate'"
        }
    ]
}

400 (HTTP response status code) -- Reference is not unique:

In this example, the reference ID was already used on a previous transaction. Reference must be unique

{
    "requestId": "36aada40727911ee8ff83020a7305d12",
    "code": "referenceExists",
    "context": {
        "reference": "extTrnAch300",
        "entityId": "evolve_7tkfB02ZcJqwHDKiSQCGHM"
    },
    "message": "Reference already exists."
}

400 (HTTP response status code) -- Mandatory field for specified standardEntryClassCode

In this example, a mandatory field is missing for the specified SEC. See Standard Entry Class Codes to review additional required fields for each SEC.

{
    "requestId": "f9688cf0151111eeaaa656da8a864a6c",
    "code": "achValidate",
    "message": "batch #1 (BOC) Invalid Batch CompanyEntryDescription  is a mandatory field and has a default value, did you use the constructor?: "
}

400 (HTTP response status code) -- Field exceeds maxLength

{
    "requestId": "afea3320151211eeaaa656da8a864a6c",
    "code": "requestValidateError",
    "context": [
        {
            "instancePath": "/routingNumber",
            "schemaPath": "ach#/definitions/routingNumber/maxLength",
            "keyword": "maxLength",
            "params": {
                "limit": 9
            },
            "message": "must NOT have more than 9 characters"
        }
    ]
}

400 (HTTP response status code) -- Example of a field validation error in the back office

In this example, the given routing number did not pass validation in the back office.

{
    "requestId": "c045f970151211eeaaa656da8a864a6c",
    "code": "achValidate",
    "message": "batch #1 (BOC) FieldError RDFIIdentification 9 does not match calculated check digit 0"
}

400 (HTTP response status code) -- Cannot make a payment for less than $0

{
    "requestId": "1b630460151311eeaaa656da8a864a6c",
    "code": "requestValidateError",
    "context": [
        {
            "instancePath": "/amount",
            "schemaPath": "common#/definitions/amount/exclusiveMinimum",
            "keyword": "exclusiveMinimum",
            "params": {
                "comparison": ">=",
                "limit": 0
            },
            "message": "must be >= 0"
        }
    ]
}

400 (HTTP response status code) -- Amount must be 0 if and only if preNote is true

In this example, an amount of 0 was included in the request, but the property preNote: true was not included in the request. Amount must be 0 if and only if preNote is true.

{
    "requestId": "fcb08690728811ee8ff83020a7305d12",
    "code": "achValidate",
    "message": "Amount 0 this batch type requires that the amount is non-zero"
}

400 (HTTP response status code) -- Company Entry Description doesn't match SEC Code

In this example, the SEC code used was "RCK", which requires a companyEntryDescription of "REDEPCHECK". Instead, "PAYMENT" was entered for the companyEntryDescription, resulting in an error.

{
    "requestId": "0498267015b811eebc2556da8a8698d8",
    "code": "achValidate",
    "message": "batch #1 (RCK) CompanyEntryDescription this batch type requires that the Company Entry Description is REDEPCHECK: PAYMENT"
}

400 (HTTP response status code) -- Module ACH is disabled

This service has not been enabled for the client. Contact your PayGears Corporation representative to request ACH services.

{
    "requestId": "15e027707cc411eeb5658f28ab5fe311",
    "code": "moduleDisabled",
    "message": "Module ach is disabled"
}

400 (HTTP response status code) -- The clientCode specified in the request is not found

The clientCode property was included in the request body with a value that has not been configured. Contact PayGears support in order to add additional ACH configurations. If the clientCode property is not included in the request body, then the default ACH configuration will be used if one has been enabled.

{
    "requestId": "84814fe07cc611eeb5658f28ab5fe311",
    "code": "uniqueAttributeNotFound",
    "message": "Unique Attribute clientCode=________ not found for module ach"
}

Back to Top

Query ACH Payments

Request method and URL:

POST /transfer-to/ach/query

Description:

The status of up to 20 ACH payments may be requested at a time (either using the "references" array or the "cFiTransactionIds" array). The array that you include may not be an empty array.

The system will return only the ACH payments it could locate. Unknown IDs will be ignored and if no IDs are recognized, an empty array is returned with success code "0".

If the same ID is requested multiple times in the "сFiTransactionIds" or "references" array, the response will only return one object in the data array corresponding to that ID, regardless of how many times it was listed in the request array.

If more than 20 elements are listed in the request array (either "сFiTransactionIds" array or the "references" array), an error will be thrown even if the IDs are not unique. For example, if the cFiTransactionId "evolve_5dRyPYn4mlXUAOTfhObZlw" is listed 21 times in the request array, the request will fail even though technically only one unique ID was requested.

Either "cFiTransactionIds": [...] should be used or "references": [...], but not both. You cannot combine both types of IDs into a single request.

Required Properties Description Schema Example Values
cFiTransactionIds Array of transaction IDs from the connectFi system obtained when each transaction was initialized array ["evolve_13c261GGqsFL1yElgKBrnS", "evolve_64gfG7m5Vm199dKU2b9efG", ...]

OR

Required Properties Description Schema Example Values
references Array of external IDs from your system that you entered when initializing the ACH payments array ["extTrnACH218", "extTrnACH219", ...]

Request headers:

{
    "Content-Type": "application/json",
    "x-connectfi-token": "a long random string" //Authorization token received from /auth/get-token request
}

Request body examples:

Request body (using connectFi transaction IDs)

{
  "cFiTransactionIds": ["evolve_13c261GGqsFL1yElgKBrnS", "evolve_64gfG7m5Vm199dKU2b9efG"] //array of transaction IDs in connectFi
}

Request body (using external system references)

{
  "references": ["extTrnACH218", "extTrnACH219"] //array of external references from your system
}

Possible responses:

200 (HTTP response status code) -- Success, Transaction statuses are returned

Both request body examples above will return the same two ACH payments, although not necessarily in the same order. 

{
    "code": "0", //Success
    "data": [
        {
            "cFiTransactionId": "evolve_13c261GGqsFL1yElgKBrnS", //transaction ID in connectFi
            "reference": "extTrnACH218", //reference from request
            "cFiAggregatorId": "amplifi",
            "effectiveEntryDate": "2023-06-28", //date for ACH payment to occur
            "individualName": "John Smith",
            "routingNumber": "123456789", //routing number of the recipient
            "DFIAccountNumber": "123456789", //alphanumeric account number of the recipient
            "amount": 3.15, //transaction amount
            "currency": "USD", //currency code
            "status": "Initiated", //current status of transaction
            "dtsCreatedAt": "2023-06-27T17:57:58.246Z",
        },
        {
            "cFiTransactionId": "evolve_64gfG7m5Vm199dKU2b9efG", //transaction ID in connectFi
            "reference": "extTrnACH219", //reference from request
            "cFiAggregatorId": "amplifi",
            "effectiveEntryDate": "2023-06-28", //date for ACH payment to occur
            "individualName": "John Smith",
            "routingNumber": "123456789", //routing number of the recipient
            "DFIAccountNumber": "123456789", //alphanumeric account number of the recipient
            "amount": 3.15, //transaction amount
            "currency": "USD", //currency code
            "status": "Initiated", //current status of transaction
            "dtsCreatedAt": "2023-06-27T18:00:49.690Z",
        }
    ],
    "requestId": "a2358610151411eeaaa656da8a864a6c"
}

200 (HTTP response status code) -- Success, сFiTransactionIds/references requested do not exist

In this example, the request was successful but the requested transaction IDs do not exist in connectFi.

{
    "code": "0", //Success
    "data": [], //no matching transactions 
    "requestId": "7b57e240f0d911ed9bc156da8a861818"
}

400 (HTTP response status code) -- Array ("references" or "cFiTransactionIds") must NOT have fewer than 1 items

In this example, the references array property or the cFiTransactionIds array property did not contain at least 1 ID. This error will be thrown if the ID array used (either references or cFiTransactionIds) is empty. 

{
    "requestId": "87ac8130151511eeaaa656da8a864a6c",
    "code": "requestValidateError",
    "context": [
        {
            "instancePath": "",
            "schemaPath": "#/oneOf/0/required",
            "keyword": "required",
            "params": {
                "missingProperty": "cFiTransactionIds"
            },
            "message": "must have required property 'cFiTransactionIds'"
        },
        {
            "instancePath": "/references",
            "schemaPath": "#/oneOf/1/properties/references/minItems",
            "keyword": "minItems",
            "params": {
                "limit": 1
            },
            "message": "must NOT have fewer than 1 items"
        },
        {
            "instancePath": "",
            "schemaPath": "#/oneOf",
            "keyword": "oneOf",
            "params": {
                "passingSchemas": null
            },
            "message": "must match exactly one schema in oneOf"
        }
    ]
}

400 (HTTP response status code) -- Must not have fewer than 1 characters

In this example, the array included in the request body contained at least one empty string, "". Each cFiTransactionId must have between 1 and 32 characters. Each reference ID must have between 1 and 32 characters.

{
    "requestId": "969d1ec0151511eeaaa656da8a864a6c",
    "code": "requestValidateError",
    "context": [
        {
            "instancePath": "",
            "schemaPath": "#/oneOf/0/required",
            "keyword": "required",
            "params": {
                "missingProperty": "cFiTransactionIds"
            },
            "message": "must have required property 'cFiTransactionIds'"
        },
        {
            "instancePath": "/references/0",
            "schemaPath": "common#/definitions/reference/minLength",
            "keyword": "minLength",
            "params": {
                "limit": 1
            },
            "message": "must NOT have fewer than 1 characters"
        },
        {
            "instancePath": "",
            "schemaPath": "#/oneOf",
            "keyword": "oneOf",
            "params": {
                "passingSchemas": null
            },
            "message": "must match exactly one schema in oneOf"
        }
    ]
}

400 (HTTP response status code) -- Must not have more than 20 items

In this example, more than 20 reference IDs were included in the "references" array property in the request body. You may not include more than 20 reference IDs or cFiTransactionIds in a single request (even if they are not unique IDs). 

{
    "requestId": "addfb5c0151511eeaaa656da8a864a6c",
    "code": "requestValidateError",
    "context": [
        {
            "instancePath": "",
            "schemaPath": "#/oneOf/0/required",
            "keyword": "required",
            "params": {
                "missingProperty": "cFiTransactionIds"
            },
            "message": "must have required property 'cFiTransactionIds'"
        },
        {
            "instancePath": "/references",
            "schemaPath": "#/oneOf/1/properties/references/maxItems",
            "keyword": "maxItems",
            "params": {
                "limit": 20
            },
            "message": "must NOT have more than 20 items"
        },
        {
            "instancePath": "",
            "schemaPath": "#/oneOf",
            "keyword": "oneOf",
            "params": {
                "passingSchemas": null
            },
            "message": "must match exactly one schema in oneOf"
        }
    ]
}

Back to Top

List ACH Payments

Request method and URL:

POST /transfer-to/ach/list

Description:

This endpoint will list transactions that match the desired search criteria. Search criteria may be a specific cFiTransaction or reference ID, a date range, a status value, or a combination of criteria. You may also specify a maximum number of records to return using the numberOfRecords property (up to 1000) and you may specify a number of records to skip using the skipRecords property. Combine the numberOfRecords property with the skipRecords property to make displaying transaction lists in batches easy. For example, if you want to list transactions in batches of 150, you can set numberOfRecords to 150 and skipRecords to 0 in the first request. Then, increase skipRecords by 150 in each subsequent request to return the next batch and so on.

When making a request, if the number of transactions matching the criteria is greater than the numberOfRecords maximum requested, the response body will indicate that there are additional transactions ("more": true).

If no properties are included, an unfiltered transaction list will be returned (up to a maximum of 1000).

Optional Properties Description Schema Example Values
cFiTransactionId Transaction ID from the connectFi system obtained when the transaction was initialized, nullable string, regex pattern: "^[0-9a-zA-Z_]+$" "evolve_13c261GGqsFL1yElgKBrnS"
reference The external reference for the transaction in your system (1-32 alphanumeric characters), nullable string, regex pattern: "^[0-9a-zA-Z]+$" "externalTrnId2314"
dateCreateFrom A beginning date in ISO Date format, if using a date range to list transactions, nullable string "2023-05-10T12:46:31.578Z"
dateCreateTo An ending date in ISO Date format, if using a date range to list transactions, nullable string "2023-05-13T12:46:31.578Z"
status The desired status for which to search, nullable string "Initiated", "Sent", "Complete", "Returned", or "Declined"
numberOfRecords The maximum number of desired records to return, nullable integer <=1000 850
skipRecords The number of records to skip when returning results, nullable integer 25

Request headers:

{
    "Content-Type": "application/json",
    "x-connectfi-token": "a long random string" //Authorization token received from /auth/get-token request
}

Request body examples:

Request body (using connectFi transaction ID)

{
    "cFiTransactionId": "amplifi_4henAdnK6RrnXQ7y6KqU1O"
}

or

{
    "cFiTransactionIds": ["amplifi_4henAdnK6RrnXQ7y6KqU1O", ... ]
}

or 

{
    "cFiTransactionId": "amplifi_4henAdnK6RrL1yElgKBrnS",
  "cFiTransactionIds": ["amplifi_4henAdnK6Rrfdsadsafh12", ... ]
}

Request body (using external system references)

{
    "reference": "extTrnAch152"
}

Request body (using a date range)

{
    "dateCreateFrom": "2023-02-01T14:27:33.684Z",
  "dateCreateTo": "2023-06-28T18:27:33.684Z"
}

Request body (using a combination of desired search criteria)

{
    "dateCreateFrom": "2023-02-01T14:27:33.684Z", //beginning of requested date range
  "dateCreateTo": "2023-06-28T18:27:33.684Z", //end of requested date range
  "status": "Initiated", //will only return transactions with an "Initiated" status
  "numberOfRecords": 15, //will return up to a maximum of 15 records
  "skipRecords": 1 //will skip the first transaction found
}

Possible responses:

200 (HTTP response status code) -- Success, transactions that meet the search criteria will be returned.

{
    "code": "0", //Success
    "data": {
        "total": {
            "skipRecords": 0, //no records were skipped
            "numberOfRecords": 1, //number of records returned
            "more": false //there are no more records found that are not currently displayed
        },
        "items": [
            {
                "cFiTransactionId": "amplifi_4henAdnK6RrnXQ7y6KqU1O", //transaction ID in connectFi
                "reference": "extTrnAch152", //reference from request
                "cFiAggregatorId": "amplifi",
                "status": "Initiated", //current status of transaction
                "dtsCreatedAt": "2023-06-27T18:00:49.690Z",
                "effectiveEntryDate": "2023-06-28", //date for ACH payment to occur
                "individualName": "John Smith",
                "routingNumber": "123456789",
                "amount": 3.15,
                "currency": "USD",
                "DFIAccountNumber": "123456789"
            }
        ]
    },
    "requestId": "4935667015be11eebc2556da8a8698d8"
}

200 (HTTP response status code) -- Success, no transactions that meet the search criteria were found.

Note: If the dateCreateTo date is before the dateCreateFrom date, you will receive the same response. Check to make sure the date range is valid if no transactions meet your criteria when transactions are expected.

{
    "code": "0", //Success
    "data": {
        "total": {
            "skipRecords": 0,
            "numberOfRecords": 0,
            "more": false
        },
        "items": []
    },
    "requestId": "85f558b0f0e111ed9bc156da8a861818"
}

400 (HTTP response status code) -- Must be equal to one of the allowed values

In this example, an invalid status value was requested.

{
    "requestId": "e42ff8b015bf11eeb10356da8a868504",
    "code": "requestValidateError",
    "context": [
        {
            "instancePath": "/status",
            "schemaPath": "#/$merge/properties/status/enum",
            "keyword": "enum",
            "params": {
                "allowedValues": [
                    "Initiated",
                    "Sent",
                    "Complete",
                    "Returned",
                    "Declined"
                ]
            },
            "message": "must be equal to one of the allowed values"
        },
        {
            "instancePath": "",
            "schemaPath": "#/$merge/$merge",
            "keyword": "$merge",
            "params": {},
            "message": "must pass \"$merge\" keyword validation"
        },
        {
            "instancePath": "",
            "schemaPath": "#/$merge",
            "keyword": "$merge",
            "params": {},
            "message": "must pass \"$merge\" keyword validation"
        }
    ]
}

400 (HTTP response status code) -- Must match format

In this example, an invalid ISO date was entered.

{
    "requestId": "0a7f40c015c011eeb10356da8a868504",
    "code": "requestValidateError",
    "context": [
        {
            "instancePath": "/dateCreateTo",
            "schemaPath": "#/$merge/properties/dateCreateTo/format",
            "keyword": "format",
            "params": {
                "format": "dateISO"
            },
            "message": "must match format \"dateISO\""
        },
        {
            "instancePath": "",
            "schemaPath": "#/$merge/$merge",
            "keyword": "$merge",
            "params": {},
            "message": "must pass \"$merge\" keyword validation"
        },
        {
            "instancePath": "",
            "schemaPath": "#/$merge",
            "keyword": "$merge",
            "params": {},
            "message": "must pass \"$merge\" keyword validation"
        }
    ]
}

Back to Top

Return Rates

Request method and URL:

POST /transfer-to/ach/return-rates

Description:

This endpoint will retrieve the return rates data for the specified date (YYYY-MM-DD format). When originating ACH debits, customers are responsible for monitoring their compliance with NACHA's "ACH Network Risk and Enforcement Rule". This rule specifies that unauthorized return rates should remain below 0.5%, administrative return rates should remain below 3.0%, and the overall return rates should be below 15.0%. This response contains these return rates, as well as the number of days that any such rates have been out of compliance (if applicable). Return rates are calculated daily for a rolling 60-day period. This means that the data used to calculate the return rates for a specified reporting date would come from the 60 days prior to the requested date. If return rates exceed the allowed threshold, then a remediation plan may need to be provided, including updated processes/procedures and the timeline for when the return rates will be in good standing again.

  • Unauthorized Return Rate - the rate at which an Originator's or Third-Party Sender's debit entries are returned on the basis that they were unauthorized.
  • Administrative Return Rate - the rate at which an Originator’s or Third-Party Sender’s debit entries are returned for administrative reasons
  • Overall Return Rate - the rate at which an Originator’s or Third-Party Sender’s debit entries, excluding RCK Entries, are returned, regardless of reason, as calculated in accordance with Subsection 2.17.2.4(d) (ODFI Return Rate Reporting Regarding an Originator’s or Third-Party Sender’s Administrative Return Rate or Overall Return Rate) (NACHA Guidelines, Section 8.71 “Overall Return Rate”)
Optional Properties Description Schema Example Values
date Requested reporting date in YYYY-MM-DD format. If no date is included, up to a maximum of 1000 return rates records will be returned for the currently logged in client, sorted in decending order by maxDate. string "2023-06-25"

Request headers:

{
    "Content-Type": "application/json",
    "x-connectfi-token": "a long random string" //Authorization token received from /auth/get-token request
}

Request body examples:

{
    "date": "2023-03-13" //response will include return rates data for the specified date, if available
}

OR

{
    //if the optional date parameter is not included, up to a maximum of 1000 return rates records will be returned for the currently logged in client, sorted in decending order by maxDate
}

Possible responses:

200 (HTTP response status code) -- Success, return rates data is returned

{
    "code": "0", //Success
    "data": {
        "total": {
            "skipRecords": 0,
            "numberOfRecords": 1,
            "more": false
        },
        "items": [
            {
                "notes": [
                    "The administrative returns rate has been out of compliance for 14 days.  The adminRate = 42.86 and adminAmountRate = 43.58.",
                    "The total returns rate has been out of compliance for 39 days.  The totalRate = 92.86 and totalAmountRate = 94.38."
                ],
                "returnRates": {
                    "cFiAggregatorId": "evolve",
                    "maxDate": "2023-09-13", //requested reporting date
                    "adminAmountRate": 43.58, //administrative return rate based on $ amount
                    "adminDaysOver": 14, //number of days that the administrative return rate has been out of compliance
                    "adminRate": 42.86, //administrative return rate based on number of transactions
                    "adminReturns": 6, //number of transactions returned for administrative reasons
                    "adminReturnsAmount": 33548.36, //$ amount of returns for administrative reasons
                    "dtsCreatedAt": "2023-09-14T00:13:39.016Z",
                    "fedDR": 14, //number of fedDR transactions
                    "fedDRAmount": 76978.46, //$ amount of fedDR transactions
                    "fileName": "Return Rates PGACH 20230913094101.json",
                    "minDate": "2023-07-12", //beginning of 60 day rolling range the calculations for this report are based on
                    "nsfReturns": 7, //number of transactions returned for non-sufficient funds
                    "nsfReturnsAmount": 39103, //$ amount of transactions returned for non-sufficient funds
                    "totalAmountRate": 94.38, //overall return rate based on $ amount
                    "totalDaysOver": 39, //number of days that the overall return rate has been out of compliance
                    "totalRate": 92.86, //overall return rate based on number of transactions
                    "totalReturns": 13, //number of transactions returned overall
                    "totalReturnsAmount": 72651.36, //$ amount of transactions returned overall
                    "unAuthorizedAmountRate": 0, //unauthorized return rate based on $ amount
                    "unAuthorizedDaysOver": 0, //number of days that the unauthorized return rate has been out of compliance
                    "unAuthorizedRate": 0, //unauthorized return rate based on number of transactions
                    "unAuthorizedReturns": 0, //number of transactions returned on the basis that they were unauthorized
                    "unAuthorizedReturnsAmount": 0, //$ amount of transactions returned on the basis that they were unauthorized
                    "updatedAt": "2023-09-25T00:16:47.555Z"
                }
            }
        ]
    },
    "requestId": "6ad418a0151711eea42756da8a8627a0"
}

200 (HTTP response status code) -- Return rate data not found for requested date and cFiAggregatorId

{
    "code": "0",
    "data": {
        "total": {
            "skipRecords": 0,
            "numberOfRecords": 0,
            "more": false
        },
        "items": []
    },
    "requestId": "a30b2ab0728c11ee8ff83020a7305d12"
}

400 (HTTP response status code) -- Must match pattern

In this example, the requested date was not in YYYY-MM-DD format.

{
    "requestId": "e38ae380151911eea42756da8a8627a0",
    "code": "requestValidateError",
    "context": [
        {
            "instancePath": "/date",
            "schemaPath": "common#/definitions/dateOnly/pattern",
            "keyword": "pattern",
            "params": {
                "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
            },
            "message": "must match pattern \"^\\d{4}-\\d{2}-\\d{2}$\""
        }
    ]
}

Back to Top

Webhooks

Description:

If you specify a webhook URL in the /transfer-to/ach/create endpoint, every time a transaction status changes due to a response Paygears has received, the system will make a single POST call to the specified URL with the following body.

{
    "cFiTransactionId": "amplifi_3A5dSDcMFdlWK54dj1cacU",
    "reference": "extTrnAch153",
    "cFiAggregatorId": "amplifi",
    "status": "Initiated",
    "dtsCreatedAt": "2023-06-28T13:26:59.312Z",
    "effectiveEntryDate": "2023-06-28",
    "individualName": "John Smith",
    "routingNumber": "123456789", 
    "amount": 3.15,
    "currency": "USD",
    "DFIAccountNumber": "123456789"
}

Back to Top

Possible Status Values

Value of status property Description
Initiated A /transfer-to/ach/create request has successfully created the ACH transaction entity and returned the cFiTransactionId that was created.
Sent Multiple times a day, connectFi will send the NACHA formatted batch files containing all of the unsent ACH transactions that have been initiated and packed. An ACH transaction with a "Sent" status has successfully been sent for payment.
Complete A "Complete" status indicates that PayGears has received a response that the payment request was received successfully.
Returned A "Returned" status indicates that PayGears has received a response that the payment was returned
Declined A "Declined" status indicates that PayGears has received a response that the payment failed

Back to Top

ACH SFTP Batch Payments Solution

Alternatively, our ACH SFTP file transfer solution provides the ability to submit batch ACH payments through CSV files. This solution is the best option if:

  • your system does not support API endpoint calls,
  • you prefer the ability to submit ACH payments in batches

ACH payment requests received through SFTP file transfers are validated, formatted in accordance with NACHA guidelines, and 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.

Section Description
SFTP Integration Instructions on how to generate a USER SSH-RSA key pair and integrate with our SFTP file drop system
File Name Description of the file name format required for the CSV batch files
File Direction Direction in which the specified file will be transfered
File Format Description of the required file format and required/optional properties for each transaction
Example File An example of a valid ACH payments CSV file

SFTP Integration

Generating Public/Private USER SSH-RSA key-pairs

To integrate with our ACH batch payments solution using SFTP batch file transfers, you will need to generate a USER SSH-RSA key pair and provide us with the public key portion. We will use the public key to grant you access to your client folder on our SFTP server.

In order to generate the SSH-RSA key pair, you may use the CLI command ssh-keygen.

When you run ssh-keygen, you will be prompted to enter the file in which to save your public/private key pair. Enter the desired path and file name. Make sure that you choose a secure location to store your keys.

You will then be prompted (and then reprompted) for an optional passphrase. Press enter both times to leave empty or enter the same passphrase both times. Using a passphrase provides additional security for your private key once it is generated.

You will receive a confirmation that your identification (private key) has been saved in the file name that you specified. Make sure that your private key is not shared with anyone. The private key is what identifies you as the client and will allow you to access the SFTP folder to drop/pick up files. If your private key is ever compromised, notify us immediately so that we can temporarily shut down access to the SFTP server. You should then generate a new SSH-RSA key pair, provide us with the new public key, and use the new private key to re-establish your access to the SFTP server once we have updated the public key for your client folder.

A confirmation that your public key has been saved will also be provided. The public key is saved using the same file name but with a .pub file type. You will also be given a key fingerprint and randomart image.

c:\>ssh-keygen
Generating public/private rsa key pair.
Enter file in which to save the key(C:/.ssh/id_rsa): C:\The\path\for\secrets\fileName
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in C:\The\path\for\secrets\fileName
Your public key has been saved in C:\The\path\for\secrets\fileName.pub
The key fingerprint is: SHA256:123456789asdsdf/dfghjkzxcvbnqwe123456789/ab user@place
The key's randomart image is:
+---[RSA 3072]----+
|                 |
|                 |
|                 |
|                 |
|                 |
|                 |
|                 |
|                 |
|                 |
+----[SHA256]-----+

The public key is what you will need to share with PayGears, while the private key should be used to set up the SFTP server connection on your (the client's) end.

Connecting to the SFTP server

Once you have generated the SSH-RSA key pair and provided us with the public key, we will

  • create a folder specific to your (the client's) platform on our SFTP server,
  • create a user name associated with the public key that you provided in order to grant access to the newly created client folder, and
  • provide you with the host name and user name in order for you to set up a connection to your client folder on our SFTP server.

To test your ability to access your client folder on our SFTP server, an example using WinSCP is provided below.

  • In WinSCP, create a new login connection.
  • Choose "SFTP" as the "File protocol" and enter the "Host name" and the "User name" provided by PayGears.
  • Then choose "Advanced" options and navigate to the "Authentication" tab.
  • In the "Private key file" input field, choose the location of the private key that you generated. The default file type accepted is .ppk. If you have not already converted your private key to a .ppk file type, then choose "All Files" as the file type so that your private key file will be found.
  • Once you select and open the private key file, you will be prompted to convert the OpenSSH private key to PuTTY format (.ppk). Choose "OK".
  • Select "OK" again to confirm your advanced settings and then "Save" the login information that you entered.
  • Finally, attempt to log in using the connection.

If you are able to successfully create a connection session to the SFTP server and see the contents of your client folder (it may be empty at this point) then you have successfully established access.

Back to Top

File Name

The file name should be of the format "YYYY_MM_DD_#.csv", where "#" is an alphanumeric character (either a digit or a capital letter) that is unique for the specified file date. The file name should match the regex /^\d{4}_\d{2}_\d{2}_[0-9A-Z]{1}\.csv$/. If a file submission is rejected with defects, you may resubmit the file with the same file name after correcting the specified defects. The corrected file will overwrite the file with the same name containing defects. If a file with the same name as a previously accepted file is submitted to the SFTP drop folder, it will be rejected (it will not overwrite any file that has already successfully been processed).

Examples

2023_07_28_1.csv, 2023_07_28_2.csv, ..., 2023_07_28_A.csv

Back to Top

File Direction

This file is sent to PayGears from the client.

Back to Top

File Format

The file should be a comma delimited CSV file. There must be at least 16 fields present (fields 0-15 as designated in the table below). Even if optional fields are left blank, the comma delimiters must still be included. Any fields that exist beyond the first 16 (0-15) will be included as addenda. Do not include quotation marks for strings in the csv file and do not include delimiters (commas) as part of a field entry.

Properties CSV Column # Description Schema Required? Example Values
effectiveEntryDate 0 The effective entry date in YYMMDD format string yes 230626
companyName 1 The company name or client code as it appears in the client ACH attributes string yes ABCINC
standardEntryClassCode 2 The Standard Entry Class (SEC) Code indicating the nature of the transaction and applicable conditions for each (see Standard Entry Class Codes above). string yes ARC, BOC, CIE, CCD, CTX, POP, PPD, RCK, TEL, or WEB
companyEntryDescription 3 A description of this transaction, such as PAYROLL, PAYMENT, REDEPCHECK (necessary when standardEntryClassCode is RCK), or AUTOENROLL, max length: 10 characters string Required for SEC types ARC, BOC, CIE, CCD, CTX, PPD, RCK, TEL, and WEB PAYMENT
companyDiscretionaryData 4 Optional codes included by the ACH originating company, max length: 20 characters string no, can be empty PayGears ACH
individualName 5 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 string yes John Smith
routingNumber 6 The routing number of the recipient, length: 9 numeric characters string yes 123456789
DFIAccountNumber 7 The alphanumeric account number of the recipient, max length: 17 characters string yes 1234567890abcdefg
accountType 8 The type of account for the recipient string yes Checking or Savings
transactionType 9 The type of transaction string yes Credit or Debit
amount 10 The requested ACH payment amount. If the amount is 0, then the preNote property must have a value of true. number >= 0, must match regex /^\d+(?:.\d{0,2})?$/ yes 16.08
checkSerialNumber 11 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 string Required for SEC types ARC, BOC, POP, and RCK 123456789012345
terminalCity 12 First four characters of the terminal city, max length: 4 characters string Required for SEC type POP Colu
terminalState 13 Two character state code string Required for SEC type POP SC
identificationNumber 14 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 string Required for SEC type CIE ACHTrans123
preNote 15 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, nullable boolean no, can be empty true or leave empty
addenda05 16-10015 An array of strings with payment related information, max items: 9999 1-9999 string fields separated by commas Not allowed for SEC types "ARC", "BOC", "CTX", "TEL", "RCK", and "POP". Optional for SEC types "CIE", "CCD", "PPD", and "WEB" UAT penny test

Back to Top

Example File

File Name: 2023_07_31_1.csv

230731,CSVTEST,PPD,PENNY TEST,PayGears ACH,John Doe,031101279,123456789012,Checking,Credit,1.07,,,,,,UAT penny test1
230731,CSVTEST,PPD,PENNYTEST2,PayGears ACH,Susan Doe,031101279,123456789012,Checking,Debit,1.07,,,,,,UAT penny test2
230731,CSVTEST,PPD,PENNYTEST3,PayGears ACH,Jake Doe,031101279,123456789012,Savings,Credit,1.07,,,,,,An,addenda05,with,multiple,items,should,appear,as,multiple fields, separated, by commas, after the first 16, fields
230731,CSVTEST,BOC,PAYMENT,,John Doe,031101279,123456789012,Savings,Debit,1.07,000007,,,,,
230731,CSVTEST,CIE,PAYMENT,Trading,John Doe,031101279,123456789012,Checking,Credit,1.07,,,,1,,UAT test
230731,CSVTEST,CCD,PAYMENT,,John Doe,031101279,123456789012,Savings,Debit,1.07,,,,,,UAT test
230731,CSVTEST,CTX,PAYMENT,Trading,John Doe,031101279,123456789012,Checking,Credit,1.07,,,,1,,
230731,CSVTEST,POP,PAYMENT,,John Doe,031101279,123456789012,Checking,Debit,1.07,000010,term,SC,,,

Back to Top