Creating Transactions

Submitting Single vs Multi Transactions

When submitting ACH transactions, there are important differences between single and bulk (multi) submission modes, as well as how item statuses are reported in responses.

Single Transaction Submission

If you submit a single transaction and the data is not formatted correctly, the API will return a 400 Bad Request error.
In some cases, even if the data is valid, the item may later be marked with ItemStatus='I' (Invalid) or ItemStatus='B' (Blocked) due to business processing rules. For example, this can happen if a state is restricted or an account number is blocked after initial validation.
If everything is successful, the response will include ItemStatus='W', which means all checks have passed and the item is waiting for further processing.

Bulk (Multi) Transaction Submission

When submitting multiple transactions in bulk, there is a flag that controls how the API handles validation for the entire set:

If the all-or-nothing flag is enabled (the whole set must be valid), and even a single item in the set is invalid (e.g., an account number contains an apostrophe), the entire set will be rejected and a 400 Bad Request will be returned.
If the flag is disabled (partial commit allowed), the API will process all valid items and return the invalid items with ItemStatus='I'.
If alwaysCommitValid == true, the API will process all valid items, and for invalid items, it will create entries and mark their ItemStatus as 'I'.

ItemStatus Codes

W: Waiting – All checks passed, item is ready for processing.
I: Invalid – The item failed validation or was later found to be invalid due to business rules.
B: Blocked – The item is blocked, possibly due to restrictions or account issues.

Tip: Even if data is initially valid, business rules may later change the status to I or B.

Submit a Debit

To add a single ACH transaction to the system, use the following endpoint:

POST /api/v3/AchTransactions/companycode/{companyCode}

Model Example:

{
  "firstSignerFirstName": "John",
  "firstSignerLastName": "Smith",
  "state": "MO",
  "zip": "63131",
  "yourReferenceNumber": "a15g488e11g1d11e",
  "bankRoutingNumber": "071921891",
  "bankAccountNumber": "9874654321",
  "amount": 10.51,
  "achAccountType": "Checking",
  "achTransactionType": "Debit",
  "achEntryClass": "PPD"
}

Submit a Credit

To add a single ACH transaction to the system, use the following endpoint:

POST /api/v3/AchTransactions/companycode/{companyCode}

Model Example:

{
  "firstSignerFirstName": "John",
  "firstSignerLastName": "Smith",
  "state": "MO",
  "zip": "63131",
  "yourReferenceNumber": "afe2233iyt5554",
  "bankRoutingNumber": "071921891",
  "bankAccountNumber": "9874654321",
  "amount": 10.51,
  "achAccountType": "Checking",
  "achTransactionType": "Credit",
  "achEntryClass": "PPD"
}

Submit a Debit Prenote

To add a single ACH transaction to the system, use the following endpoint:

POST /api/v3/AchTransactions/companycode/{companyCode}

Model Example:

{
  "firstSignerFirstName": "John",
  "firstSignerLastName": "Smith",
  "state": "MO",
  "zip": "63131",
  "yourReferenceNumber": "abc55445eee189",
  "bankRoutingNumber": "071921891",
  "bankAccountNumber": "9874654321",
  "amount": 0,
  "achAccountType": "Checking",
  "achTransactionType": "Debit",
  "achTransactionSubType": "Prenote",
  "achEntryClass": "PPD"
}

Bulk Submission

To add a single ACH transaction to the system, use the following endpoint:

POST /api/v3/AchTransactions/companycode/{companyCode}/many

Model Example:

{
  "alwaysCommitValid": true,
  "items": [
    {
      "firstSignerFirstName": "John",
      "firstSignerLastName": "Smith",
      "state": "MO",
      "zip": "63131",
      "yourReferenceNumber": "a15g488e11g1d11e",
      "bankRoutingNumber": "071921891",
      "bankAccountNumber": "9874654321",
      "amount": 10.51,
      "achAccountType": "Checking",
      "achTransactionType": "Debit",
      "achEntryClass": "PPD"
    },
    {
      "firstSignerFirstName": "John",
      "firstSignerLastName": "Smith",
      "state": "MO",
      "zip": "63131",
      "yourReferenceNumber": "afe2233iyt5554",
      "bankRoutingNumber": "071921891",
      "bankAccountNumber": "9874654321",
      "amount": 10.51,
      "achAccountType": "Checking",
      "achTransactionType": "Credit",
      "achEntryClass": "PPD"
    }
  ]
}

Submitting items that will automatically return (Dev Only)

To test return scenarios, Flex has created a mechanism that allows you to submit an account number that will automatically return an item. The pattern includes a variable for delaying the response as well as defining the particular reason code that will be returned.

Account Number Pattern: XXXXXXXXX99990001
XXXXXXXXX: Optional prefix of 9 digits
9999: Signals to Flex that this transaction should be responded to with a Return
00: How many days to wait until the Return response is triggered
01: Return code that should be triggered

Submitting items that automatically return a Notice of Change (Dev Only)

To test NOC (Notice of Change) scenarios, Flex has created a mechanism that allows you to submit an account number that will automatically generate a NOC. The pattern includes a variable for delaying the response as well as defining the particular reason code that will be generated.

Account Number Pattern: XXXXXXXXX88880001
XXXXXXXXX: Optional prefix of 9 digits
8888: Signals to Flex that this transaction should be responded to with an NOC
00: How many days to wait until the NOC response is triggered
01: NOC code that should be triggered