Initiate Credit payment

Accepts the full ISO 20022 message as an XML string in the request body, rooted at the <Document> element. The Message-Type header specifies whether the body contains a pain.001 or pacs.008 document, so the correct XSD is applied for validation. On success the payment is processed through the existing credit 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 required	string 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. Enum: "pain.001" "pacs.008"
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. Required when `Message-Type` is `pacs.008`. Not applicable for `pain.001`. 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.001 → urn:iso:std:iso:20022:tech:xsd:pain.001.001.09, containing <CstmrCdtTrfInitn>.
pacs.008 → urn:iso:std:iso:20022:tech:xsd:pacs.008.001.08, containing <FIToFICstmrCdtTrf>.

string

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/credit

Request samples

Payload
curl
JavaScript
Node.js

application/xml

<?xml version="1.0" encoding="UTF-8"?>
<Document xmlns="urn:iso:std:iso:20022:tech:xsd:pain.001.001.09">
  <CstmrCdtTrfInitn>
    <GrpHdr>
      <MsgId>MSG-PAIN001-0001</MsgId>
      <CreDtTm>2026-07-17T10:15:30Z</CreDtTm>
      <NbOfTxs>1</NbOfTxs>
      <CtrlSum>1000.00</CtrlSum>
      <InitgPty>
        <Nm>Acme Corp</Nm>
      </InitgPty>
    </GrpHdr>
    <PmtInf>
      <PmtInfId>PMTINF-0001</PmtInfId>
      <PmtMtd>TRF</PmtMtd>
      <ReqdExctnDt>2026-07-18</ReqdExctnDt>
      <Dbtr>
        <Nm>Acme Corp</Nm>
      </Dbtr>
      <DbtrAcct>
        <Id>
          <IBAN>DE89370400440532013000</IBAN>
        </Id>
      </DbtrAcct>
      <DbtrAgt>
        <FinInstnId>
          <BICFI>DEUTDEFF</BICFI>
        </FinInstnId>
      </DbtrAgt>
      <CdtTrfTxInf>
        <PmtId>
          <EndToEndId>E2E-0001</EndToEndId>
        </PmtId>
        <Amt>
          <InstdAmt Ccy="EUR">1000.00</InstdAmt>
        </Amt>
        <CdtrAgt>
          <FinInstnId>
            <BICFI>BNPAFRPP</BICFI>
          </FinInstnId>
        </CdtrAgt>
        <Cdtr>
          <Nm>Jane Beneficiary</Nm>
        </Cdtr>
        <CdtrAcct>
          <Id>
            <IBAN>FR1420041010050500013M02606</IBAN>
          </Id>
        </CdtrAcct>
        <RmtInf>
          <Ustrd>Invoice 12345</Ustrd>
        </RmtInf>
      </CdtTrfTxInf>
    </PmtInf>
  </CstmrCdtTrfInitn>
</Document>

Response samples

application/json

{"paymentIds": [9384712
]
}