Initiate Debit payment - v1

Accepts the full ISO 20022 message as an XML string in the request body, rooted at the <Document> element. The Message-Type header specifies that the body contains a pain.013 document, so the correct XSD is applied for validation. On success the payment is processed through the existing debit payment validation and processing workflow.

Idempotency. The Idempotency-Key header is mandatory. Retrying the same request with the same key returns the original response without creating a duplicate payment; submitting the same key with a different request body returns 409 Conflict.

SecurityoAuth2
Request
header Parameters
Idempotency-Key
required
string [ 1 .. 128 ] characters

A client-generated unique key used to safely retry a request without creating duplicate payment initiations. Must be between 1 and 128 characters.

Message-Type
string
Default: pain.013

Specifies the ISO 20022 message type contained in the request body. In the XML request body, so the appropriate ISO 20022 XML Schema (XSD) is used for parsing and validation. The XML namespace and document structure must match the selected message type.

Value: "pain.013"
Speed
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
Request Body schema: application/xml
required

The full ISO 20022 message document as an XML string, rooted at the <Document> element with the namespace matching the message type declared in the Message-Type header:

  • pain.013 → urn:iso:std:iso:20022:tech:xsd:pain.013.001.07, containing <CdtrPmtActvtnReq>.

See the request body schema below for the full field-level structure of the message type.

required
object

Complete creditor payment activation request message.

Responses
201

Created (201). The payment request was accepted, validated against the applicable ISO 20022 XSD and business rules, and a payment resource was created.

400

Bad request (400). Malformed XML, an unsupported or missing required header, a Message-Type/XML namespace mismatch, or an XSD validation failure. No payment is created.

401

Unauthorized (401). The request does not contain a valid Bearer JWT access token. No response body is returned.

403

Forbidden (403). The authenticated caller does not have permission to initiate this payment.

409

Conflict (409). The same Idempotency-Key was previously processed with a different request body. No additional payment is created.

422

Unprocessable Entity (422). The XML is well-formed and XSD-compliant but fails an ISO 20022 business or semantic validation rule.

500

Internal Server Error (500). An unexpected error occurred while processing the request.

post/v1/iso20022/debit
Request samples
application/xml
<?xml version="1.0" encoding="UTF-8"?>
<Document xmlns="urn:iso:std:iso:20022:tech:xsd:pain.013.001.07">
    <CdtrPmtActvtnReq>
        <GrpHdr>
            <MsgId>20261012MMQFMC21000032</MsgId>
            <CreDtTm>2026-10-16T03:55:43-04:00</CreDtTm>
            <NbOfTxs>1</NbOfTxs>
            <InitgPty>
                <Nm>FIRST BANK</Nm>
                <PstlAdr>
                    <TwnNm>SAINT LOUIS</TwnNm>
                    <Ctry>US</Ctry>
                </PstlAdr>
                <Id>
                    <OrgId>
                        <Othr>
                            <Id>081009428</Id>
                        </Othr>
                    </OrgId>
                </Id>
            </InitgPty>
        </GrpHdr>
        <PmtInf>
            <PmtInfId>20261012MMQFMC21000032</PmtInfId>
            <PmtMtd>TRF</PmtMtd>
            <ReqdExctnDt>
                <Dt>2026-10-12</Dt>
            </ReqdExctnDt>
            <Dbtr>
                <Nm>A</Nm>
                <PstlAdr>
                    <TwnNm>a</TwnNm>
                    <Ctry>US</Ctry>
                </PstlAdr>
            </Dbtr>
            <DbtrAcct>
                <Id>
                    <Othr>
                        <Id>1122667</Id>
                    </Othr>
                </Id>
            </DbtrAcct>
            <DbtrAgt>
                <FinInstnId>
                    <ClrSysMmbId>
                        <ClrSysId>
                            <Cd>USABA</Cd>
                        </ClrSysId>
                        <MmbId>081009428</MmbId>
                    </ClrSysMmbId>
                </FinInstnId>
            </DbtrAgt>
            <CdtTrfTx>
                <PmtId>
                    <EndToEndId>NOTPROVIDED</EndToEndId>
                    <UETR>a5381764-07b3-4e27-9a99-05027740cfc0</UETR>
                </PmtId>
                <PmtTpInf>
                    <InstrPrty>NORM</InstrPrty>
                    <LclInstrm>
                        <Prtry>DRRB</Prtry>
                    </LclInstrm>
                </PmtTpInf>
                <Amt>
                    <InstdAmt Ccy="USD">5.00</InstdAmt>
                </Amt>
                <ChrgBr>SHAR</ChrgBr>
                <CdtrAgt>
                    <FinInstnId>
                        <ClrSysMmbId>
                            <ClrSysId>
                                <Cd>USABA</Cd>
                            </ClrSysId>
                            <MmbId>081009428</MmbId>
                        </ClrSysMmbId>
                    </FinInstnId>
                </CdtrAgt>
                <Cdtr>
                    <Nm>FIRST BANK</Nm>
                    <PstlAdr>
                        <TwnNm>SAINT LOUIS</TwnNm>
                        <Ctry>US</Ctry>
                    </PstlAdr>
                    <Id>
                        <OrgId>
                            <Othr>
                                <Id>081009428</Id>
                            </Othr>
                        </OrgId>
                    </Id>
                </Cdtr>
            </CdtTrfTx>
        </PmtInf>
    </CdtrPmtActvtnReq>
</Document>
Response samples
application/json
{
  • "paymentIds": [
    ]
}