Payment details

Webhook API allows Finzly customers to get real-time notifications on the payment data that belongs to them based on the configured payment events such as payment is Processed, Cancelled, HOLD, etc...

Request
Request Body schema: application/json
required
paymentId
integer <= 11 characters

Unique Payment Identifier

externalReferenceId
string <= 255 characters

External reference id set by the originator system

sourceReferenceId
string <= 35 characters

The bulk file id set by the system when the payment is originated via bulk file upload

bulkFileName
string <= 100 characters

Bulk file name if the payment is originated from the FTP channel

bulkFileNumber
integer <= 12 characters

Bulk File Unique Identifier if the payment is originated from the FTP channel

counterParty
string <= 255 characters

Legal entity (Counterparty) shortname associated with the payment

channel
string

Payment origination channel such as API, FTP, ONLINE

paymentStatus
string <= 35 characters

Payment Status such as VALIDATED, VALIDATION_FAILURE, AUTHORIZED, MEMO_POSTED, READY_TO_TRANSMIT, TRANSMITTED,PROCESSED, CANCELLED

Array of objects (ValidationFailureMessages)
deliveryDate
string <date>

Payment delivery or effective entry date in yyyy-mm-dd format

deliveryMethod
string <= 20 characters

Delivery method associated with the payment such as ACH, FEDWIRE, RTP, FEDNOW, SWIFT

feeAmount
number <decimal> [ 0 .. 10000000000000000 ]

Fee amount in USD

paymentDate
string <date>

Payment date in yyyy-mm-dd format

paymentIOType
string <= 3 characters

Inbound or Outbound Payment Indicator.

paymentNote1
string <= 35 characters

Payment Notes

paymentNote2
string <= 35 characters

Additional Payment Notes

paymentRemittanceInfo
string <= 35 characters

Payment Remittance Information from NACHA addenda record

paymentType
string <= 35 characters

Type of Payment - Same Day or Regular ACH. Possible values are REGULAR_ACH, SAME_DAY_ACH, WIRE, BOOK_TRANSFER, REALTIME_RTP, REALTIME_FEDNOW, SPOT_SWIFT, SAME_DAY_SWIFT, NEXT_DAY_SWIFT

senderBankCountry
string

Sender bank country.

feeName
string

Fee name.

memoPostDate
string

Date when the memo posted.

memoPostStatus
string

Memo post status

Enum: "POSTED" "NOT_POSTED" "SUCCESS" "PARTIAL_SUCCESS" "FAILURE" "NOT_APPLICABLE" "NA_RETURN_INITIATED" "NA_RECEIVED_REVERSAL"
memoPostFailureReason
string

Memo post failure reason.

memoPostReferenceId
string

Memo post referenceId. It is an unique Id.

costCenter
string <= 25 characters

Cost center is a function within an organization that does not directly add to profit but still costs money to operate, such as the accounting, HR, or IT departments

checkSerialNumber
string

Check serial number.

receiverAccountNumber
string <= 35 characters

Account number of the receiver

receiverAccountType
string <= 35 characters

Receiver Account Type

receiverAddress1
string <= 35 characters

Receiver Address 1

receiverAddress2
string <= 35 characters

Receiver Address 2

receiverCity
string <= 35 characters

Receiver City

receiverAmount
number <decimal> [ 0 .. 10000000000000000 ]

Amount received by recipient

receiverBankName
string <= 255 characters

Receiver Bank Name

receiverBankState
string <= 35 characters

Receiver Bank State

receiverDiscretionaryData
string <= 35 characters

Receiver discretionary data

receiverTemplateName
string <= 35 characters

Receiver Template Name

receiverName
string <= 255 characters

Receiver name associated with the payment.

originalReceiverName
string <= 255 characters

The original receiver name recieved from the payment network for the inbound payment request.

receiverRoutingNumber
string <= 35 characters

Receiver Routing Number

receiverType
string <= 35 characters

Receiver Type

receiverState
string <= 35 characters

Receiver State

receiverZip
string <= 10 characters

Receiver zipcode

receiverCountry
string <= 35 characters

Receiver country

receiverEmail
string <email> <= 50 characters

Receiver Email

receiverPhoneNumber
string <= 35 characters

Receiver Phone Number

receiverId
string <= 35 characters

Receiver Identifier (1)

receiverIdType
string <= 35 characters

Receiver Identifier Type (1)

receiverBankIdType
string <= 35 characters

Receiver Bank Id Type

receiverBankId
string <= 35 characters

Receiver Bank Id Value

receiverBankAddress1
string <= 35 characters

Receiver Bank Address 1

receiverBankAddress2
string <= 35 characters

Receiver Bank Address 2

receiverBankCity
string <= 35 characters

Receiver Bank City

receiverBankZip
string <= 35 characters

Receiver Bank Zip

receiverBankCountry
string <= 35 characters

Receiver Bank Country

intermediaryReceiverBankIdType
string <= 35 characters

Intermediary Receiver Bank ID Type

intermediaryReceiverBankId
string <= 35 characters

Intermediary Receiver Bank ID value

intermediaryReceiverBankName
string <= 255 characters

Intermediary Receiver Bank Name

intermediaryReceiverBankAddress1
string <= 35 characters

Intermediary Receiver Bank Address 1

intermediaryReceiverBankAddress2
string <= 35 characters

Intermediary Receiver Bank Address 2

intermediaryReceiverBankCity
string <= 35 characters

Intermediary Receiver Bank City

intermediaryReceiverBankState
string <= 35 characters

Intermediary Receiver Bank State

intermediaryReceiverBankZip
string <= 35 characters

Intermediary Receiver Bank Zip/Postal Code

intermediaryReceiverBankCountry
string <= 35 characters

Intermediary Receiver Bank Country Name

ultimateReceiverName
string <= 255 characters

Ultimate receiver name. This will be used for the fintech scenario when the virtual account range is used to process a payment.

ultimateReceiverAccountNumber
string <= 35 characters

Ultimate receiver account number. This will be used for the fintech scenario when the virtual account range is used to process a payment.

ultimateReceiverTaxId
string <= 35 characters

Ultimate receiver company id. This will be used for the fintech scenario when the virtual account range is used to process a payment.

ultimateReceiverAddress1
string <= 35 characters

Ultimate receiver address 1. This will be used for the fintech scenario when the virtual account range is used to process a payment.

ultimateReceiverAddress2
string <= 35 characters

Ultimate receiver address 2. This will be used for the fintech scenario when the virtual account range is used to process a payment.

ultimateReceiverCity
string <= 35 characters

Ultimate receiver city. This will be used for the fintech scenario when the virtual account range is used to process a payment.

ultimateReceiverState
string <= 35 characters

Ultimate receiver state. This will be used for the fintech scenario when the virtual account range is used to process a payment.

ultimateReceiverZip
string <= 35 characters

Ultimate receiver zip or postal code. This will be used for the fintech scenario when the virtual account range is used to process a payment.

ultimateReceiverCountry
string <= 35 characters

Ultimate receiver country. This will be used for the fintech scenario when the virtual account range is used to process a payment.

networkRefId
string <= 35 characters

The reference ID recieved from the payment network.

otherBankRefId
string <= 35 characters

The is applicable for the mainly SWIFT payment where addtional reference ID is used.

forexContract
string <= 35 characters

FX contract number associated with the SWIFT/International payment

entryType
string <= 10 characters

Payment entry type such as CREDIT or DEBIT

senderName
string <= 255 characters

Sender Name

senderAmount
number <decimal> [ 0 .. 10000000000000000 ]

Sender Amount

senderAccountNumber
string <= 20 characters

Sender Bank Account Number

senderRoutingNumber
string <= 35 characters

Sender's Routing Number

senderAccountType
string <= 35 characters

Sender Account Type such as Deposit or GL or Loan

senderType
string <= 35 characters

Sender Type - Corporate, Consumer, Downstream Partner

senderAddress1
string <= 35 characters

Sender Address1

senderAddress2
string <= 35 characters

Sender Address2

senderCity
string <= 35 characters

Sender City

senderState
string <= 35 characters

Sender State

senderZip
string <= 10 characters

Sender zipcode

senderCountry
string <= 35 characters

Sender country

senderIdType
string <= 35 characters

Sender Identifier type the possible values are Driving License,Passport, Tax ID

senderId
string <= 35 characters

Sender Identifier Value

senderIdType2
string <= 35 characters

Sender Identifier type (2) the possible values are Driving License, Passport, Tax ID

senderId2
string <= 35 characters

Sender Identifier Value (2)

senderEmail
string <email> <= 50 characters

Sender Email

senderBankIdType
string <= 35 characters

Sender Bank Id Type

senderBankId
string <= 35 characters

Sender Bank Id Value

senderBankName
string <= 255 characters

Sender Bank name

senderBankAddress1
string <= 35 characters

Sender Bank Address 1

senderBankAddress2
string <= 35 characters

Sender Bank Address 2

senderBankCity
string <= 35 characters

Sender Bank City

senderBankState
string <= 35 characters

Sender Bank State

senderBankZip
string <= 35 characters

Sender Bank Zip or Postal code

senderDiscretionaryData
string <= 35 characters

Sender's Discretionary Data

intermediarySenderBankIdType
string <= 35 characters

Intermediary Sender Bank ID Type

intermediarySenderBankId
string <= 35 characters

Intermediary Sender Bank ID value

intermediarySenderBankName
string <= 255 characters

Intermediary Sender Bank Name

intermediarySenderBankAddress1
string <= 35 characters

Intermediary Sender Bank Address 1

intermediarySenderBankAddress2
string <= 35 characters

Intermediary Sender Bank Address 2

intermediarySenderBankCity
string <= 35 characters

Intermediary Sender Bank City

intermediarySenderBankState
string <= 35 characters

Intermediary Sender Bank State

intermediarySenderBankZip
string <= 35 characters

Intermediary Sender Bank Zip/Postal Code

intermediarySenderBankCountry
string <= 35 characters

Intermediary Sender Bank Country Name

ultimateSenderName
string <= 255 characters

Ultimate sender name. This will be used for the fintech scenario when the virtual account range is used to process a payment.

ultimateSenderAccountNumber
string <= 35 characters

Ultimate sender account number. This will be used for the fintech scenario when the virtual account range is used to process a payment.

ultimateSenderAddress1
string <= 35 characters

Ultimate sender address 1. This will be used for the fintech scenario when the virtual account range is used to process a payment.

ultimateSenderAddress2
string <= 35 characters

Ultimate sender address 2. This will be used for the fintech scenario when the virtual account range is used to process a payment.

ultimateSenderTaxId
string <= 35 characters

Ultimate sender company id. This will be used for the fintech scenario when the virtual account range is used to process a payment.

ultimateSenderCity
string <= 35 characters

Ultimate sender city. This will be used for the fintech scenario when the virtual account range is used to process a payment.

ultimateSenderState
string <= 35 characters

Ultimate sender state. This will be used for the fintech scenario when the virtual account range is used to process a payment.

ultimateSenderZip
string <= 35 characters

Ultimate sender zip or postal code. This will be used for the fintech scenario when the virtual account range is used to process a payment.

ultimateSenderCountry
string <= 35 characters

Ultimate sender country. This will be used for the fintech scenario when the virtual account range is used to process a payment.

object (PaymentNocDetails)
iMad
string

It is a unique number given to each FedWire payment when using the Federal Reserve Bank Service and can be used to investigate and track wire transfers

oMad
string

The OMAD indicates a unique number assigned to each transfer providing delivery-related information

originatorToBeneficiaryInformation
string <= 140 characters

The OBI details

senderToReceiverInfo
string <= 210 characters

Sender to Receiver details. This field replaces senderToRecieverInfo due to a previous typo.

referenceForBeneficiary
string <= 16 characters

This is applicable for the fedwire payment where the local instrument set to COVS. This specifies the reference details for the beneficiary.

requestMethod
string <= 140 characters

Request Method associated with the payment origination

achOriginationId
string

ACH orgination id.

achSecCode
string <= 3 characters

ACH SEC Code. Applicable for the ACH payment rail.

achTransactionCode
string <= 10 characters

ACH transaction code.

achTraceId
string <= 25 characters

ACH Trace Id associated with the payment record

achBatchId
string <= 11 characters

ACH Batch Id associated with the payment record

fedwireBusinessFunctionCode
string <= 3 characters

Fedwire busines function code

fedwireDetailsOfCharge
string <= 3 characters

Fedwire details of charge

fedwireComments
string <= 255 characters

Fedwire comments

fiToFiInformation
string <= 255 characters

FI to FI Details

beneficiaryFIAdviceCode
string <= 3 characters

Beneficiary FI Advice Code

object (BeneficiaryFIAdviceInformation)
beneficiaryAdviceCode
string <= 3 characters

Beneficiary Advice Code

object (BeneficiaryFIAdviceInformation)
beneficiaryFIInformation
string <= 255 characters

Beneficiary FI Information

object (RtpFedNowDetails)
object (RtpFedNowDetails)
Array of objects (PaymentReturnDetails)
creationDateTime
string <date-time>

Payment creation date and time are recorded in UTC.

lastUpdatedTime
string <date-time>

Payment last updated date and time are recorded in UTC.

object (RecurrenceDetails)
object (PositivePayDecisionDetails)
Responses
200

Successfully posted payment status

400

Bad request

401

Unauthorized

402

Request Failed

403

Forbidden

404

Not Found

409

The request conflict with other requests

429

Too many requests

500

Server Errored out.

502

Server Errored out

503

Server Errored out

504

Server Errored out

post/payments
Request samples
application/json
{
  • "paymentId": 8982,
  • "externalReferenceId": "197297287383",
  • "sourceReferenceId": "123",
  • "bulkFileName": "achfile198191.ach",
  • "bulkFileNumber": 1231,
  • "counterParty": "LESHORTNAME",
  • "channel": "API",
  • "paymentStatus": "VALIDATION_FAILURE",
  • "validationFailureMessages": [
    ],
  • "deliveryDate": "2023-03-11",
  • "deliveryMethod": "ACH",
  • "feeAmount": 2,
  • "paymentDate": "2023-03-10",
  • "paymentIOType": "IN",
  • "paymentNote1": "payment notes",
  • "paymentNote2": "payment notes2",
  • "paymentRemittanceInfo": "invoice #1233",
  • "paymentType": "SAME_DAY_ACH",
  • "senderBankCountry": "US",
  • "feeName": "Custom",
  • "memoPostDate": "11-31-2025",
  • "memoPostStatus": "POSTED",
  • "memoPostFailureReason": "reason",
  • "memoPostReferenceId": "88787878",
  • "costCenter": "12897",
  • "checkSerialNumber": "989978785454",
  • "receiverAccountNumber": "27898978798",
  • "receiverAccountType": "Deposit or GL",
  • "receiverAddress1": "9090 Adam street",
  • "receiverAddress2": "Collelium drive",
  • "receiverCity": "Charlotte",
  • "receiverAmount": 95,
  • "receiverBankName": "XXY Bank",
  • "receiverBankState": "NC",
  • "receiverDiscretionaryData": "string",
  • "receiverTemplateName": "ABCTemplate",
  • "receiverName": "XYZ Name",
  • "originalReceiverName": "XYZ Name",
  • "receiverRoutingNumber": "044000037",
  • "receiverType": "Consumer",
  • "receiverState": "North Carolina ",
  • "receiverZip": "28269 ",
  • "receiverCountry": "United States of America ",
  • "receiverEmail": "abc@gmail.com",
  • "receiverPhoneNumber": "12897789128",
  • "receiverId": "string",
  • "receiverIdType": "string",
  • "receiverBankIdType": "NID",
  • "receiverBankId": "103000648",
  • "receiverBankAddress1": "1211 Adam street",
  • "receiverBankAddress2": "Adam street",
  • "receiverBankCity": "Charlotte",
  • "receiverBankZip": "28269 ",
  • "receiverBankCountry": "United States of America ",
  • "intermediaryReceiverBankIdType": "NID",
  • "intermediaryReceiverBankId": "044000037",
  • "intermediaryReceiverBankName": "ABC Bank",
  • "intermediaryReceiverBankAddress1": "9090 Adam street",
  • "intermediaryReceiverBankAddress2": "Adam lane 1200",
  • "intermediaryReceiverBankCity": "Charlotte",
  • "intermediaryReceiverBankState": "North Carolina ",
  • "intermediaryReceiverBankZip": "28269 ",
  • "intermediaryReceiverBankCountry": "United States of America ",
  • "ultimateReceiverName": "Rec Name",
  • "ultimateReceiverAccountNumber": "679567838",
  • "ultimateReceiverTaxId": "4987289187",
  • "ultimateReceiverAddress1": "1211 Adam street",
  • "ultimateReceiverAddress2": "Collelium drive",
  • "ultimateReceiverCity": "Charlotte",
  • "ultimateReceiverState": "North Carolina",
  • "ultimateReceiverZip": "28269 ",
  • "ultimateReceiverCountry": "United States of America ",
  • "networkRefId": "134222",
  • "otherBankRefId": "098989",
  • "forexContract": "12398",
  • "entryType": "CREDIT",
  • "senderName": "XYZ Name",
  • "senderAmount": 95,
  • "senderAccountNumber": "90819918",
  • "senderRoutingNumber": "072000326",
  • "senderAccountType": "DepositL",
  • "senderType": "Corporate",
  • "senderAddress1": "1123 ABC St.",
  • "senderAddress2": "Unit 200",
  • "senderCity": "Charlotte",
  • "senderState": "string",
  • "senderZip": "28267",
  • "senderCountry": "United States Of America",
  • "senderIdType": "Driving License",
  • "senderId": "C8798779",
  • "senderIdType2": "Driving License",
  • "senderId2": "5678943",
  • "senderEmail": "xyz@gmail.com",
  • "senderBankIdType": "NID",
  • "senderBankId": "103000648",
  • "senderBankName": "ABC Bank",
  • "senderBankAddress1": "89798 street",
  • "senderBankAddress2": "Lane 200 ",
  • "senderBankCity": "BankCity",
  • "senderBankState": "BankState",
  • "senderBankZip": "28289",
  • "senderDiscretionaryData": "string",
  • "intermediarySenderBankIdType": "NID or SWIFT",
  • "intermediarySenderBankId": "044000037",
  • "intermediarySenderBankName": "IntermediaryBankName",
  • "intermediarySenderBankAddress1": "9090 Adam street",
  • "intermediarySenderBankAddress2": "Collelium drive",
  • "intermediarySenderBankCity": "Charlotte",
  • "intermediarySenderBankState": "North Carolina ",
  • "intermediarySenderBankZip": "28269 ",
  • "intermediarySenderBankCountry": "United States of America ",
  • "ultimateSenderName": "Name",
  • "ultimateSenderAccountNumber": "987656789",
  • "ultimateSenderAddress1": "Address1",
  • "ultimateSenderAddress2": "Address2",
  • "ultimateSenderTaxId": "7876789287",
  • "ultimateSenderCity": "Charlotte",
  • "ultimateSenderState": "NC",
  • "ultimateSenderZip": "23434",
  • "ultimateSenderCountry": "United States of America",
  • "paymentNocDetails": {
    },
  • "iMad": "20220627MMQCTR7B000012",
  • "oMad": "0328QMGFNP6400002503281343FT0120232023",
  • "originatorToBeneficiaryInformation": "OBI Notes",
  • "senderToReceiverInfo": "Notes",
  • "referenceForBeneficiary": "RefForBeneficiary Details",
  • "requestMethod": "WALK-IN",
  • "achOriginationId": "ABC1234",
  • "achSecCode": "PPD",
  • "achTransactionCode": "21",
  • "achTraceId": "202110182222664",
  • "achBatchId": "12341",
  • "fedwireBusinessFunctionCode": "CTR",
  • "fedwireDetailsOfCharge": "SHA",
  • "fedwireComments": "comments notes",
  • "fiToFiInformation": "notes",
  • "beneficiaryFIAdviceCode": "LTR",
  • "beneficiaryFIAdviceInformation": {
    },
  • "beneficiaryAdviceCode": "LTR",
  • "beneficiaryAdviceInformation": {
    },
  • "beneficiaryFIInformation": "notes",
  • "rtpDetails": {
    },
  • "fedNowDetails": {
    },
  • "paymentReturnDetails": [
    ],
  • "creationDateTime": "2022-06-30T01:30:48.342Z",
  • "lastUpdatedTime": "2022-06-30T01:30:48.342Z",
  • "recurrence": {
    },
  • "positivePayDecision": {
    }
}