This guide is intended for developers using the ACH Pro API

ODFI

An ODFI (originating depository financial institution) is a bank that sends an ACH file on behalf of its customer. ACH Pro requires a single ODFI in every ACH file.

Note that when creating an ACH file, you can either specify an existing ODFI using its odfiId or you can pass an ODFI from scratch. Passing from scratch allows you to use a one-off ODFI config without needing it to exist in ACH Pro.

Definition

Field	Type	Description
odfiId	string	(Generated) The UUID for this ODFI assigned by the API.
profileId	string	(Generated) The UUID for your profile.
name*	string	(Required) Name of financial institution.
routingNumber*	string	(Required) Nine digit routing number. This value must be unique among your other ODFIs.
fileLineEndings*	string	(Required) “UNIX” or “WINDOWS”. Specifies the line ending type for NACHA files created for this ODFI.
immediateOrigin	string	(Optional) Ten digit override for the Immediate Origin field in the NACHA file header. Only use this field if your bank has specific requirements.
immediateOriginName	string	(Optional) Overrides the Immediate Origin Name field in the NACHA file header. Only use this field if your bank has specific requirements.
immediateDestination	string	(Optional) Ten digit override for the Immediate Destination field in the NACHA file header. Only use this field if your bank has specific requirements.
immediateDestinationName	string	(Optional) Overrides the Immediate Destination Name field in the NACHA file header. Only use this field if your bank has specific requirements.

Examples

Creating an ODFI - Input (API Docs):

{ 
  "name": "Bank of America", 
  "routingNumber": "026009593", 
  "immediateDestination": null, 
  "immediateOrigin": null, 
  "immediateDestinationName": null, 
  "immediateOriginName": null, 
  "fileLineEndings": "UNIX" 
}

Updating an ODFI - Input (API Docs)

{ 
  "odfiId": "B3DD2388D8A54186B831681D80D8F95D", 
  "profileId": "A6868145A3714987852F601BE9E41E9C", 
  "name": "Bank of America", 
  "routingNumber": "026009593", 
  "immediateDestination": null, 
  "immediateOrigin": null, 
  "immediateDestinationName": null, 
  "immediateOriginName": null, 
  "fileLineEndings": "UNIX" 
}

Create ACH File using existing ODFI:

{ 
  "odfi": { 
    "odfiId": "B3DD2388D8A54186B831681D80D8F95D" 
  }, 
  ... 
}

Create ACH File using ODFI from scratch:

{ 
  "odfi": { 
    "name": "Bank of America", 
    "routingNumber": "026009593", 
    "immediateDestination": null, 
    "immediateOrigin": null, 
    "immediateDestinationName": null, 
    "immediateOriginName": null, 
    "fileLineEndings": "UNIX" 
  }, 
  ... 
}

Recipient

Recipients are payment destinations when there type is “CONSUMER”, “BUSINESS” or "COMPANY". Additionally, recipients of type “COMPANY” can be used as the originator in a NACHA file.

Note that when creating an ACH file, you can either specify an existing recipient using its recipientId or you can pass a recipient from scratch. Passing from scratch allows you to use a one-off recipient without needing it to exist in ACH Pro. You can mix and match existing and from scratch recipients within a file.

Definition

Field	Type	Description
recipientId	string	(Generated) The UUID for this recipient assigned by the API.
profileId	string	(Generated) The UUID for your profile.
recipientType*	string	(Required) “CONSUMER” or “BUSINESS” or “COMPANY”.
name*	string	(Required) The legal name of the recipient.
uniqueIdentifier	string	(Optional) A unique ID you can use to identify the recipient within a NACHA file.
accounts	[Account]	(Optional) A list of Accounts for this recipient.
notificationEmails	[ { email: string } ]	(Optional) A list of objects containing email addresses used to grant recipient users access to manage their ACH authorizations. This feature is only available in the Premium and Ultimate plans.
companyIdentification	string	(Required if type = “COMPANY”) Up to ten digit company identification used in NACHA batch header.
metadata	object	(Optional) Contains two optional fields. These fields are NOT encrypted so do not put sensitive data in them. externalId: Used to associate this recipient with an external system. If provided, must be unique among all recipients. externalGroup: Group identifier from an external system

Examples

Create CONSUMER/BUSINESS recipient - Input (API Docs):

{ 
  "recipientType": "BUSINESS", 
  "name": "ABC Company", 
  "uniqueIdentifier": "0001ABC", 
  "notificationEmails": [ 
    { 
      "email": "[email protected]" 
    } 
  ], 
  "accounts": [ 
    { 
      "accountNumber": "101010101", 
      "routingNumber": "026009593" 
    } 
  ], 
  "metadata": { 
    "externalId": "anIdFromSomewhere" 
  } 
}

Create COMPANY recipient - Input (API Docs):

{ 
  "recipientType": "COMPANY", 
  "name": "My Originating Company", 
  "companyIdentification": "810001234", 
  "accounts": [ 
    { 
      "accountNumber": "202020202", 
      "routingNumber": "026009593" 
    } 
  ], 
  "metadata": { 
    "externalId": "anIdFromSomewhere" 
  } 
}

Update recipient - Input (API Docs):

{ 
  "recipientId": "8126624016A544408EB74FFE81ADDB49", 
  "profileId": "59DE4FF642E543E0908AF7B18A78209E", 
  "recipientType": "BUSINESS", 
  "name": "ABC Company Inc", 
  "uniqueIdentifier": "0001ABC", 
  "notificationEmails": [ 
    { 
      "email": "[email protected]" 
    } 
  ], 
  "accounts": [ 
    { 
      "accountNumber": "102010201", 
      "routingNumber": "026009593" 
    } 
  ], 
  "metadata": { 
    "externalId": "anUpdatedIdFromSomewhere" 
  } 
}

Create ACH file using existing recipient:

{ 
  "batches": [ 
    { 
      "companyRecipient": { 
        "recipientId": "8126624016A544408EB74FFE81ADDB49" 
      }, 
      "entries": [ 
        { 
          "recipient": { 
            "recipientId": "8126624016A544408EB74FFE81ADDB49" 
          }, 
          ... 
        } 
      ], 
      ... 
    } 
  ], 
  ... 
}

Create ACH file using recipient from scratch:

{ 
  "batches": [ 
    { 
      "companyRecipient": { 
        "recipientType": "COMPANY", 
        "name": "My Originating Company", 
        "companyIdentification": "810001234" 
      }, 
      "entries": [ 
        { 
          "recipient": { 
            "recipientType": "BUSINESS", 
            "name": "ABC Company", 
            "uniqueIdentifier": "0001ABC" 
          }, 
          ... 
        } 
      ], 
      ... 
    } 
  ], 
  ... 
}

Account

Accounts are associated with Recipients and contain details of a bank account.

Note that when creating an ACH file, you can either specify an existing account using its accountId or you can pass an account from scratch. Passing from scratch allows you to use a one-off account without needing it to exist in ACH Pro. You can mix and match existing and from scratch accounts within a file.

Definition

Field	Type	Description
accountId	string	(Generated) The UUID for this account assigned by the API.
recipientId	string	(Generated) The UUID of this account’s associated recipient.
profileId	string	(Generated) The UUID for your profile.
accountNumber*	string	(Required) Up to 17 digit alphanumeric account number.
routingNumber*	string	(Required) 9 digit routing number of receiving bank.
accountType*	string	(Required) “CHECKING” or “SAVINGS” or “LOAN”
nickname	string	(Optional) Nickname for this account
metadata	object	(Optional) Contains two optional fields. These fields are NOT encrypted so do not put sensitive data in them. externalId: Used to associate this recipient with an external system. If provided, must be unique among all recipients. externalGroup: Group identifier from an external system

Examples

Create account - Input (API Docs):

{ 
  "accountNumber": "123456789", 
  "routingNumber": "125000024", 
  "accountType": "CHECKING", 
  "nickname": "Operating", 
  "metadata": { 
    "externalId": "anIdFromSomewhere" 
  } 
}

Update account - Input (API Docs):

{ 
  "accountId": "8126624016A544408EB74FFE81ADDB49", 
  "recipientId": "B3DD2388D8A54186B831681D80D8F95D", 
  "profileId": "59DE4FF642E543E0908AF7B18A78209E", 
  "accountNumber": "123456789", 
  "accountType": "CHECKING", 
  "routingNumber": "125000024", 
  "nickname": "Customer Account", 
  "metadata": { 
    "externalId": "anIdFromSomewhere" 
  } 
}

Create ACH file using existing account:

{ 
  "batches": [ 
    { 
      "entries": [ 
        { 
          "account": { 
            "accountId": "8126624016A544408EB74FFE81ADDB49" 
          }, 
          ... 
        } 
      ], 
      ... 
    } 
  ], 
  ... 
}

Create ACH file using account from scratch:

{ 
  "batches": [ 
    { 
      "entries": [ 
        { 
          "account": { 
            "accountNumber": "123456789", 
            "routingNumber": "125000024", 
            "accountType": "CHECKING" 
          }, 
          ... 
        } 
      ], 
      ... 
    } 
  ], 
  ... 
}

ACH File

An ACH file is a JSON representation of all the info needed to create a NACHA formatted file. ACH files are immutable, that is, they can’t be edited after creation.

Note that ACH files are composed an ODFI and numerous recipients and accounts. When using existing objects, you can reference them using their ID. Alternatively, you can create an ACH file by entering these objects from scratch.

Definition

Field	Type	Description
historicalFileId	string	(Generated) The UUID for this ACH file assigned by the API.
profileId	string	(Generated) The UUID for your profile.
name*	string	(Required) The name of this ACH file. Will be used in the file name of any generated NACHA files and reports.
odfiId*	ODFI	(Required) An existing or from scratch ODFI.
batches*	[ACHBatch]	(Required) A list containing at least one ACH Batch.
referenceCode	string	(Optional) Up to 8 digit reference code used in the NACHA file header.
immediateOrigin	string	(Optional) Ten digit override for the Immediate Origin field in the NACHA file header. Only use this field if your bank has specific requirements.
immediateOriginName	string	(Optional) Overrides the Immediate Origin Name field in the NACHA file header. Only use this field if your bank has specific requirements.
immediateDestination	string	(Optional) Ten digit override for the Immediate Destination field in the NACHA file header. Only use this field if your bank has specific requirements.
immediateDestinationName	string	(Optional) Overrides the Immediate Destination Name field in the NACHA file header. Only use this field if your bank has specific requirements.
totalCredits	number	(Generated) The sum of all credit entry amounts in the file.
totalCreditCount	number	(Generated) The count of all credit entries in the file.
totalDebits	number	(Generated) The sum of all debit entry amounts in the file.
totalDebitCount	number	(Generated) The count of all credit entries in the file.
totalEntries	number	(Generated) The count of all entries in the file.

Examples

Create ACH File - Input (API Docs):

{ 
  "name": "Payroll Oct 2023", 
  "odfi": { 
    "odfiId": "A6868145A3714987852F601BE9E41E9C" 
  }, 
  "batches": [ 
    { 
      "isBalanced": false, 
      "effectiveDate": "2022-10-14", 
      "secCode": "PPD", 
      "companyEntryDescription": "PAYROLL", 
      "companyDiscretionaryData": null, 
      "companyDescriptiveDate": null, 
      "companyRecipient": { 
        "recipientId": "8126624016A544408EB74FFE81ADDB49" 
      }, 
      "entries": [ 
        { 
          "amount": 1512.35, 
          "recipient": { 
            "recipientId": "8126624016A544408EB74FFE81ADDB49" 
          }, 
          "account": { 
            "accountId": "9651613016A544408EB74FAGBE658212" 
          }, 
          "entryType": "CREDIT", 
          "addendum": "Payroll Oct" 
        }, 
        { 
          "amount": 1512.35, 
          "recipient": { 
            "recipientId": "8126624016A544408EB74FFE81ADDB49", 
          }, 
          "account": { 
            "accountId": "9651613016A544408EB74FAGBE658212" 
          }, 
          "entryType": "CREDIT", 
          "addendum": "Payroll Oct" 
        } 
      ] 
    } 
  ] 
}

ACH Batch

An ACH batch is a group of related transactions within an ACH file.

Definition

Field	Type	Description
profileId	string	(Generated) The UUID for your profile.
effectiveDate*	string	(Required) Date the entries in this batch should be posted. Format: YYYY-MM-DD
secCode*	string	(Required) “PPD” or “CCD”.
companyEntryDescription*	string	(Required)
isBalanced	boolean	(Optional) Indicates if the credit and debit amounts should be equal. An error will be thrown if balanced: true and file is out of balance.
companyRecipient*	Recipient	(Required) “COMPANY” type recipient used as the originator of this batch. Can be existing or from scratch.
entries*	[ACHEntry]	(Required) List of at least one ACH entry.
companyDiscretionaryData	string	(Optional)
companyDescriptiveDate	string	(Optional)
totalCredits	number	(Generated) The sum of credit entry amounts in this batch.
totalCreditCount	number	(Generated) The count of credit entries in this batch.
totalDebits	number	(Generated) The sum of debit entry amounts in this batch.
totalDebitCount	number	(Generated) The count of debit entries in this batch.
totalEntries	number	(Generated) The count of all entries in this batch.

Examples

ACH batch within an ACH file:

{ 
  ..., 
  "batches": [ 
  { 
    "isBalanced": false, 
    "effectiveDate": "2022-10-14", 
    "secCode": "PPD", 
    "companyEntryDescription": "PAYROLL", 
    "companyDiscretionaryData": null, 
    "companyDescriptiveDate": null, 
    "companyRecipient": { 
      "recipientId": "8126624016A544408EB74FFE81ADDB49" 
    }, 
    "entries": [ 
      { 
        "amount": 1512.35, 
        "recipient": { 
          "recipientId": "8126624016A544408EB74FFE81ADDB49" 
        }, 
        "account": { 
          "accountId": "9651613016A544408EB74FAGBE658212" 
        }, 
        "entryType": "CREDIT", 
        "addendum": "Payroll Oct" 
      }, 
      { 
        "amount": 1512.35, 
        "recipient": { 
          "recipientId": "8126624016A544408EB74FFE81ADDB49", 
        }, 
        "account": { 
          "accountId": "9651613016A544408EB74FAGBE658212" 
        }, 
        "entryType": "CREDIT", 
        "addendum": "Payroll Oct" 
      } 
    ] 
  }] 
}

ACH Entry

An ACH entry describes a transaction in an ACH batch to a specific account and recipient within an ACH file.

Definition

Field	Type	Description
profileId	string	(Generated) The UUID for your profile.
amount*	number	(Required) The amount of the transaction. This value should always be positive, zero is allowed.
entryType*	string	(Required) “CREDIT” or “CREDIT_PRENOTE” or “DEBIT” or “DEBIT_PRENOTE”. Credits increase an account balance, debits decrease it. Prenote types should only be used when the amount is zero.
recipient*	Recipient	(Required) An existing or from scratch Recipient.
account*	Account	(Required) An existing or from scratch Account.
addendum	string	(Optional) Up to 80 characters of remittance information.

Examples

ACH Entry in an ACH file:

{ 
  ..., 
  "batches": [ 
    { 
      ..., 
      "entries": [ 
        { 
          "amount": 1512.35, 
          "recipient": { 
            "recipientId": "8126624016A544408EB74FFE81ADDB49" 
          }, 
          "account": { 
            "accountId": "9651613016A544408EB74FAGBE658212" 
          }, 
          "entryType": "CREDIT", 
          "addendum": "Payroll Oct" 
        } 
      ] 
    } 
  ] 
}

Create an ACH file using Excel

Create an ACH file using QuickBooks

Getting Started with the API

Create an ACH file using the API

Upload an ACH file using SFTP with the API