Bulk File Webhook

Please note:

  • For NACHA files, the transactions section will be empty. Example: "transactions": []
  • For non-NACHA files, the achBatches section will be empty. Example: "achBatches": []
  • In the example payload, both sections are shown as non-empty for descriptive purposes only. In production, exactly one of the two sections will be populated based on fileType.
Request
Request Body schema: application/json
required
fileNumber
required
integer <int64>

Unique File reference.

fileName
required
string <= 255 characters

File name provided by the originating systems/source.

fileType
required
string <= 30 characters

File type - NACHA, FINZLY-CSV, FEDWIRE, ISO 20022-RTP, ISO 20022-FEDNOW - for the bulk file.

fileStatus
required
string <= 30 characters

Bulk File status such as PROCESSED, APPROVED, STAGED, AUTHORIZED, SYSTEM_REJECTED, CANCELLED, PENDING_AUTH, PROCESSED_WITH_ERROR, FAILED, REJECTED, EXPIRED_AUTH.

channel
required
string <= 20 characters

FTP — Channel via which the bulk file was received.

ftpUser
required
string <= 50 characters

FTP account user name used to upload the bulk file.

ftpOriginationSource
required
string <= 50 characters

FTP Origination value from FTP User Account.

accountType
required
string <= 20 characters

FTP account type — CUSTOMER or CHANNEL.

accountName
string <= 15 characters

FTP account name used to upload the bulk file. (Optional)

counterParty
required
string or null <= 50 characters

Legal entity (Counterparty) shortname associated with the payment.

counterPartyId
integer or null <int64>

CRM legal entity id for the bulk file. (Conditional)

offsetType
required
string <= 20 characters

Offset type — FILE_LEVEL or BATCH_LEVEL — for settlement for the bulk file.

fileCreationDate
required
string <date>

ACH file creation date in YYYY-MM-DD format derived from ACH file header record for the bulk file.

fileCreationTime
string <= 4 characters

ACH file creation time from file header record for the bulk file. (Optional)

fileIdModifier
string = 1 characters

ACH file id modifier from file header record for the bulk file. (Optional)

immediateOrigin
string

Immediate origin (NACHA file header).

immediateDestination
string

Immediate destination (NACHA file header).

transactionType
string <= 20 characters

Transaction type — Credit, Debit, Mixed, FedWire, FedNow, RTP — for the bulk file. (Conditional)

validPayments
integer <int32>

Number of valid payments — payments that passed all validations — for the bulk file. (Optional)

errorPayments
integer <int32>

Number of payments in error — payments that failed one or more validations — for the bulk file with File status 'PROCESSED_WITH_ERROR' or 'SYSTEM_REJECTED'. (Conditional)

totalDebits
required
number <decimal>

Total debit amount for the bulk file (decimal, up to 8 fractional digits).

totalCredits
required
number <decimal>

Total credit amount for the bulk file (decimal, up to 8 fractional digits).

totalDebitsCount
integer <int32>

Total number of debit transactions in the file.

totalCreditsCount
integer <int32>

Total number of credit transactions in the file.

rejectReason
string <= 2000 characters

One or more reasons the bulk file was rejected. (Conditional)

errors
Array of strings

Array of file-level error messages.

warnings
Array of strings

Array of file-level warning messages.

createdBy
string <= 50 characters

User — Bank admin, SYSTEM, or API etc. — who created/uploaded the bulk file.

creationDateTime
string <date-time>

Date and Time in YYYY-MM-DD HH:MM:SS format when the bulk file was created.

approvedBy
string <= 50 characters

User — Bank admin, bank user etc. — who approved the bulk file.

approvedDateTime
string <date-time>

Date and Time in YYYY-MM-DD HH:MM:SS format when the bulk file was approved.

lastUpdatedBy
string <= 50 characters

User who last updated the bulk file record.

lastUpdatedTime
string <date-time>

Date and Time in YYYY-MM-DD HH:MM:SS format of the last update to the bulk file record.

Array of objects or null

Transaction details — populated only when the file is other than NACHA; otherwise null/empty.

Array of objects or null

ACH batch details — populated only when the file is NACHA; otherwise null/empty.

Responses
200

Notification accepted by the consumer.

400

Malformed payload.

401

Unauthorized.

500

Consumer-side error while processing the notification.

post/webhooks/bulk-files
Request samples
application/json
{
  • "fileNumber": 9267,
  • "fileName": "demobankACHonWebACH20260303T1434.txt",
  • "fileType": "NACHA",
  • "fileStatus": "PROCESSED_WITH_ERROR",
  • "channel": "FTP",
  • "ftpUser": "banka-ftpuser",
  • "ftpOriginationSource": "ACHONWEB",
  • "accountType": "CHANNEL",
  • "accountName": "testAccountName",
  • "counterParty": "string",
  • "counterPartyId": 0,
  • "offsetType": "BATCH_LEVEL",
  • "fileCreationDate": "2026-03-03",
  • "fileCreationTime": "0122",
  • "fileIdModifier": "Y",
  • "immediateOrigin": "123456789",
  • "immediateDestination": "987654321",
  • "transactionType": "Mixed",
  • "validPayments": 7,
  • "errorPayments": 1,
  • "totalDebits": 100,
  • "totalCredits": 100,
  • "totalDebitsCount": 4,
  • "totalCreditsCount": 4,
  • "rejectReason": "N/A",
  • "errors": [
    ],
  • "warnings": [
    ],
  • "createdBy": "System",
  • "creationDateTime": "2019-08-24T14:15:22Z",
  • "approvedBy": "testapprover",
  • "approvedDateTime": "2019-08-24T14:15:22Z",
  • "lastUpdatedBy": "testuser",
  • "lastUpdatedTime": "2019-08-24T14:15:22Z",
  • "transactions": [
    ],
  • "achBatches": [
    ]
}