Initiate a Credit Payment - v4

Initiate a domestic or international credit payment (on-time or recurring). The v4 version of this API includes enhanced error handling, returning all relevant error messages and error codes to provide clearer insights into any issues encountered during processing.

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 ^[\p{L}\p{N} ~!@#$%&(){}|^\[\]/_\-+=?\\;:"'<>...

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.

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. 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 ^[a-zA-Z]+$

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 <= 20 characters ^[a-zA-Z]+( [a-zA-Z]+)*$

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 [ 1 .. 215 ] characters

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

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 field is provided, name is required.
object

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 field is provided, name is required.
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/v4/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": {
    },
  • "ultimateSender": {
    },
  • "ultimateReceiver": {
    },
  • "fee": {
    },
  • "recurrence": {
    },
  • "additionalInfo": {
    }
}
Response samples
application/json
{
  • "data": {
    }
}