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
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:
For Payment speed = Express (Wires), if the payment is submitted/created today* before cut-off, it will be sent to beneficiary today itself.
For Payment speed = Instant (FedNow, RTP), if the payment is submitted/created today before, it will be sent to beneficiary today itself.
For Payment speed = Economy Plus, if the payment is submitted/created today before cut-off, it will be sent to beneficiary today itself.
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 in CRM (object) or Sender not in CRM (object)
Payment sender and account details from which the money will be deducted.
required
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
Payload
curl
JavaScript
Node.js
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": {
"accountUID": 64564
},
"receiver": {
"beneficiaryId": 209219
},
"fee": {
"feeName": "Custom",
"amount": 10.88
},
"recurrence": {
"frequency": "Daily",
"payUntil": "EndDate",
"endDate": "01-29-2023",
"numberOfPayments": 10
},
"additionalInfo": {
"channel": "API",
"costCenter": "12897",
"requestMethod": "WALK-IN",
"detailsOfCharges": "OUR",
"secCode": "CCD",
"transactionTypeCode": "ANN",
"receiverIdentificationNumber": "12334356",
"fxContractNumber": "111234",
"originatortoBeneficiary": "OBI Notes",
"senderToReceiverNotes": "Sender To Reciever Notes",