externalReferenceId is a reference ID assigned by the originator system for tracking and reconciliation.

This value is not required to be unique and may be reused across multiple credit and debit payment requests. The API does not enforce uniqueness.

externalReferenceId does not provide idempotency. Clients must use the Idempotent-Key request header to prevent duplicate processing. For ACH check-serial SEC codes, this value additionally serves as the Check Serial Number, with a per-code maximum length: 9 for POP; 15 for ARC, BOC, RCK, ATX, TRC.

Payment amount. The payment amount is validated as per the limits set by the payment rails or by the bank for the customer. For the Fedwire payment, this will be mapped to the {2000} tag.

❗ Zero (0) is only allowed for ENR (Automated Enrollment Entry) payments and Prenote (Prenotification) transactions. For all other payment types, the amount must be greater than zero.

Payment rail limits per transaction:

• RTP: up to $1,000,000
• FedNow: up to $500,000
• Fedwire: up to $9,999,999,999.99
• Same Day ACH: up to $1,000,000

Receiver payment currency code. The valid country currency code should be per ISO 4217 standard.

Format: String with valid format as: MM-DD-YYYY

This is an optional field and signifies the date on which the Finzly system will settle the payment. If the paymentDate is not provided by the API user BankOS will derive it for the earliest available settlement date (not prior to the current business date), based on the configuration.

ACH Payments are typically settled two days after the current date.

Payment requests via API can be submitted using the following example guidelines:

Examples:

1. For Payment speed = Express (Wires), if the payment is submitted/created today* before cut-off, it will be sent to beneficiary today itself.
2. For Payment speed = Instant (FedNow, RTP), if the payment is submitted/created today before, it will be sent to beneficiary today itself.
3. For Payment speed = Economy Plus, if the payment is submitted/created today before cut-off, it will be sent to beneficiary today itself.
4. For Payment speed = Economy and if submitted/created for today before cut-off time, then the transaction shall have effective entry date of two days or one day after submission (T+2 or T+1) depending on your bank’s configuration. For Payment speed = Economy and if submitted on (12th Aug) for delivery date (on 16th Aug) before cut-off time, then the transaction shall be sent to beneficiary on 14th Aug assuming the configuration is two days prior to paymentDate.

• today being business day

Speed associated with the payment based on the delivery time and fee. The Speed names and associated payment rail can be configured or defined by the bank/financial institutions. The supported payment rails in FinzlyOS are ACH, Fedwire, SWIFT, RTP or FedNow. The following are the standard speed names and payment rails configured by default Economy - [ACH-REGULAR], Economy Plus [ACH-SAMEDAY], Express [FEDWIRE], Instant [FEDNOW or RTP], ON [SWIFT], TN [SWIFT], SPOT [SWIFT].

Payment notes provided by the payment originator. These notes will be truncated to the maximum allowed length. The notes are passed to the payment network as per the specification such as for ACH upto 10 chars, Fedwire upto 140 chars [Tag 6400 - Beneficiary information], SWIFT upto 140 chars [Tag 70], RTP/FedNow upto 140 chars [ISO 20022 - RmtInf Tag]. The value will be truncated if it exceeds the data length limit. paymentNotes is required for ACH and SWIFT payments.

Payment sender and account details from which the money will be deducted.

Optional. Party that ultimately originated the funds being moved, when different from sender. Used to convey an ultimate originator for third-party-originated payments (for example, a corporate sending on behalf of its end customer).

This object is entirely optional. When omitted, the server treats the payment as not having a distinct ultimate sender. When present, the following conditional rules apply:

• If name is provided, address.city and address.countryCode are required.
• If any address city or countryCode field is provided, name is required.

Contains the payment receiver’s personal and account details, where the funds will be deposited.

This field is required for all payment types except ENR (Automated Enrollment Entry).

Optional. Party that ultimately benefits from the payment, when different from receiver. Used to convey an ultimate beneficiary when the immediate beneficiary is an intermediary (for example, a payment processor receiving on behalf of a merchant).

This object is entirely optional. When omitted, the server treats the payment as not having a distinct ultimate receiver. When present, the following conditional rules apply:

• If name is provided, address.city and address.countryCode are required.
• If any address city or countryCode field is provided, name is required.

Set the payment recurrence based on the available options.