Initiate a Credit Payment

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

Unique reference id set by the originator system. For the Speed associated with the Fedwire payment this will be mapped to {3320} Tag. The {3320} tag limit is 16 characters

paymentAmount
required
number <double>

Payment amount. The payment amount are validated as per the limit set by the payment rails or by the bank for the customer. For the Fedwire payment this will be mapped to {2000} tag.The payment rail limit per transaction are RTP upto 1M$, FedNow upto $500K, Fedwire upto $9,999,999,999.99, Same Day ACH upto 1M$.

paymentCurrency
required
string = 3 characters

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

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.

The ACH, SWIFT, and Wire 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

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].

paymentNotes
string [ 1 .. 35 ] characters

Payment notes provided by the payment originator. These notes are passed to the payment network as per the specification such as for ACH upto 10 chars, Fedwire upto 35 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.

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

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

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

Payment receiver and account details to which the money will be deposited.

object (CreditPaymentInstruction_fee)

Fee to be charged for the payment transaction. Currency is fixed to USD. This is an optional field.

Recurring Until End Date (object) or Recurring for a Number of Payments (object) (CreditPaymentInstruction_recurrence)

Set the payment recurrence based on the available options.

object (CreditPaymentInstruction_additionalInfo)
Responses
200

search results matching criteria

400

bad input parameter environment

401

Unauthorized

403

Forbidden

404

Not Found

405

bad input parameter environment

500

Internal server error

503

Service unavailable

default

Payment response

post/v4/payments/credit
Request samples
application/json
{
  • "externalReferenceId": "pymtref10012 or 123e4567-e89b-12d3-a456-426614174000 etc.",
  • "paymentAmount": 175,
  • "paymentCurrency": "USD",
  • "paymentDate": "05-08-2024",
  • "speed": "Economy",
  • "paymentNotes": "Payment Notes",
  • "sender": {
    },
  • "receiver": {
    },
  • "fee": {
    },
  • "recurrence": {
    },
  • "additionalInfo": {
    }
}
Response samples
application/json
{
  • "data": {
    },
  • "errors": [
    ]
}