Initiate a Credit Payment - v5

Initiate a domestic or international credit payment (one-time or recurring).

v5 is a full superset of v4. It clones every field and behavior of POST /v4/payments/credit and layers the following new ISO 20022 (Fedwire pacs.008) fields on top:

  • sender.bankAgent (new in v5) — the account held at the debtor agent, completing the DbtrAgt agent/account pair. Maps to ISO 20022 DbtrAgtAcct. It now carries a full CashAccount field set — iban/id identification (mutually exclusive), schemeName, issuer, type, name, proxyType/proxyId, and currency — with per-field code-vs-proprietary toggles (schemeNameProprietary, accountTypeProprietary, proxyTypeProprietary).

  • receiver.intermediaryBanks (new in v5) — a list of up to two intermediary banks, mapped to ISO 20022 IntrmyAgt1 / IntrmyAgt2 (with their IntrmyAgt1Acct / IntrmyAgt2Acct account sub-objects). Each account sub-object carries the same full CashAccount field set as sender.bankAgent, including the schemeNameProprietary/ accountTypeProprietary/proxyTypeProprietary toggles.

Breaking change (v5 only): the v4 single receiver.intermediaryBank object is replaced by the receiver.intermediaryBanks list. Sending the legacy intermediaryBank object to v5 is rejected. Each list entry supports bankIdType of SWIFT or NID and an optional account sub-object.

  • sender.instructingAgents (new in v5) — a list of up to three previous instructing agents in the payment chain, mapped to ISO 20022 PrvsInstgAgt1/PrvsInstgAgt2/PrvsInstgAgt3 (with their PrvsInstgAgt1Acct/PrvsInstgAgt2Acct/PrvsInstgAgt3Acct account sub-objects). Each entry requires bankIdType (SWIFT or NID, same pattern as intermediaryBanks) and carries the same full CashAccount field set as sender.bankAgent. Postal address for each agent is derived server-side from a bank lookup — it is not a request field.

All other fields (payment, sender, receiver, receiver bank, additionalInfo, fee, recurrence, etc.) behave exactly as in v4. The v4 endpoint is unchanged.

SecurityoAuth2
Request
header Parameters
Idempotent-Key
string <uuid>

Optional idempotency key to ensure the payment is processed only once.

Example: 123e4567-e89b-12d3-a456-426614174000
Request Body schema: application/json
required

Credit Payment Request fields

externalReferenceId
required
string <= 50 characters

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.

paymentAmount
required
number <double>

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.

  • The drawdown feature is currently not supported via OpenAPI. Therefore, when using FX Trade-based payments, the paymentAmount must exactly match the FX Trade amount.

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
paymentCurrency
required
string = 3 characters

Payment currency code as per ISO 4217 (e.g., USD, EUR). The currency must exist in the system.

  • For international payments, non-USD payment currency must match the receiver currency.
  • Payment currency must match either sender or receiver currency.
  • For FX trades, payment currency must match the trade currency.
paymentDate
string

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.

SWIFT systems do not allow users to initiate payments on holidays or weekends.

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
required
string

Specifies the delivery speed of the payment, which determines how quickly the funds will be delivered and the associated fee. Valid values are predefined and mapped to specific payment rails, as configured by the bank or financial institution.

Supported Speed Names and Rails (default configuration in FinzlyOS):

  • Economy: ACH (Regular)
  • Economy Plus: ACH (Same Day)
  • Express: Fedwire
  • Instant: FedNow or RTP
  • ON, TN, SPOT: SWIFT

Validation Rules:

  • If the provided speed value is not recognized or not configured for the given currency/payment type, the payment cannot proceed.
  • If the speed value is missing, invalid, or not supported for the contact or currency pair, payment initiation will fail.
paymentNotes
string

Notes added by the payment originator. These notes will be truncated to the maximum allowed length and passed to the payment network according to rail-specific limits :

  • ACH: up to 10 characters
  • Fedwire: up to 140 characters (Tag 6400 - Beneficiary Info)
  • SWIFT: up to 140 characters (Tag 70)
  • RTP/FedNow: up to 140 characters (ISO 20022 - RmtInf tag)

paymentNotes is required for ACH and SWIFT payments.

required
Sender not in CRM (object) or Sender in CRM (object)

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

Beneficiary not in CRM (object) or Beneficiary in CRM (object)

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 payment (Automated Enrollment Entry).

object

Fee details to be charged for the payment transaction.

  • This field is optional.
  • Fee currency is fixed to USD.
Recurring Until End Date (object) or Recurring for a Number of Payments (object)

Defines the recurrence pattern for the payment. Use this object to configure how frequently the payment should repeat and when it should stop.

Fields such as endDate or numberOfPayments are conditionally required depending on the payUntil value.

ACH-specific (object) or Instant-specific (object) or FEDWIRE-specific (object) or SWIFT-specific (object)
Responses
201

The payment has been created successfully

400

Bad request

401

Unauthorized

403

Forbidden

404

Not Found

405

bad input parameter environment

500

Internal server error

503

Service unavailable

post/v5/payments/credit
Request samples
application/json
{
  • "externalReferenceId": "123e4567-e89b-12d3-a456-4266141740",
  • "paymentAmount": 175,
  • "paymentCurrency": "USD",
  • "paymentDate": "05-08-2024",
  • "speed": "Economy",
  • "paymentNotes": "Notes",
  • "sender": {
    },
  • "receiver": {
    },
  • "fee": {
    },
  • "recurrence": {
    },
  • "additionalInfo": {
    }
}
Response samples
application/json
{
  • "data": {
    }
}