Initiate a Debit Payment (Collection)

Initiate a domestic or international debit payment [one time or recurring]

SecurityoAuth2
Request
Request Body schema: application/json
required

Debit Payment Request fields

externalReferenceId
required
string

Unique reference id set by the originator system. For the speed assocated 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

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

paymentDate
string <date>

This is an optional field. It signifies the payment date on which the Finzly system will pick up the payment to process. The payment date will be default to the current date if it is empty. The valid date format is in [MM-dd-yyyy]. User can set the payment date as current date or future date however, for the payment sets to the current date, the Finzly system may change the date based upon the bank/FI configuration for-instance, If the payment SPEED associated with the ACH [SAMEDAY/REGULAR], FEDWIRE and the last submission cutoff time is passed then the payment date will be set to the next business date, or the payment request will be rejected [as per the bank chosen behavior].

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

paymentNotes
string [ 1 .. 200 ] characters
Default: "Payment Notes"

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.

object (PaymentCreditor)

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

object (PaymentDebtor)

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

object (Fee)
object (PaymentRecurrence)

Set the payment recurrence based on the available options.

object (AdditionalInfoDebitPayment)
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

return payment response

post/v3/payments/debitrequest
Request samples
application/json
{
  • "externalReferenceId": "pymtref10012 or 123e4567-e89b-12d3-a456-426614174000 etc.",
  • "paymentAmount": 0,
  • "paymentCurrency": "USD or EUR etc.",
  • "paymentDate": "0014-03-15",
  • "speed": "Economy, Economy Plus, Express, Instant",
  • "paymentNotes": "Payment Notes",
  • "creditor": {
    },
  • "debtor": {
    },
  • "fee": {
    },
  • "recurrence": {
    },
  • "additionalInfo": {
    }
}
Response samples
application/json
{
  • "status": "Success or Failure",
  • "code": "PAYMENT001 etc.",
  • "message": "Failed to create a payment: <Reason>",
  • "data": {
    }
}