Initiate Credit 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 whether the body contains a pain.001, pacs.008, or pacs.009 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" "pacs.009"
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>.
  • pacs.009 → urn:iso:std:iso:20022:tech:xsd:pacs.009.001.08, containing <FICdtTrf>.

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

One of:

The CustomerCreditTransferInitiation message is sent by the initiating party to the forwarding agent or debtor agent. It is used to request movement of funds from the debtor account to a creditor.

The message can contain one or more customer credit transfer instructions and can be used to exchange:

  • one or more instances of a credit transfer initiation
  • payment transactions that result in book transfers at the debtor agent or payments to another financial institution
  • payment transactions that result in an electronic cash transfer to the creditor account or in the emission of a cheque

The message can be used in direct or relay scenarios:

  • In a direct scenario, the message is sent directly to the debtor agent, which acts as the account servicer of the debtor.
  • In a relay scenario, the message is sent to a forwarding agent that concentrates and forwards the CustomerCreditTransferInitiation message to the debtor agent.

The message can also be used by an initiating party that has authority to send the message on behalf of the debtor, including payment factory scenarios. It can be used in domestic and cross-border scenarios.

This message must not be used by the debtor agent to execute the credit transfer instruction(s). The FIToFICustomerCreditTransfer message must be used instead.

required
object

Complete customer credit transfer initiation 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/credit
Request samples
application/xml
<?xml version="1.0" encoding="UTF-8"?>
<Document xmlns="urn:iso:std:iso:20022:tech:xsd:pain.001.001.09" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <CstmrCdtTrfInitn>
        <GrpHdr>
            <MsgId>SAMPLEPAIN001V09-0000123456</MsgId>
            <CreDtTm>2026-08-21T09:15:00-04:00</CreDtTm>
            <NbOfTxs>1</NbOfTxs>
            <InitgPty>
                <Nm>Fictional Freight &amp; Trading Co LLC</Nm>
                <Id>
                    <OrgId>
                        <AnyBIC>FKFRUS33XXX</AnyBIC>
                        <Othr>
                            <Id>FFT-CID-0009182736</Id>
                        </Othr>
                    </OrgId>
                </Id>
            </InitgPty>
        </GrpHdr>
        <PmtInf>
            <PmtInfId>SAMPLEPMTINF-0001</PmtInfId>
            <PmtMtd>TRF</PmtMtd>
            <PmtTpInf>
                <SvcLvl>
                    <Cd>URGP</Cd>
                </SvcLvl>
                <LclInstrm>
                    <Cd>CTRC</Cd>
                </LclInstrm>
            </PmtTpInf>
            <ReqdExctnDt>
                <Dt>2026-08-21</Dt>
            </ReqdExctnDt>
            <Dbtr>
                <Nm>Fictional Freight &amp; Trading Co LLC</Nm>
                <PstlAdr>
                    <StrtNm>4820 Meridian Commerce Parkway</StrtNm>
                    <BldgNb>Suite 300</BldgNb>
                    <PstCd>60606</PstCd>
                    <TwnNm>Chicago</TwnNm>
                    <CtrySubDvsn>IL</CtrySubDvsn>
                    <Ctry>US</Ctry>
                    <AdrLine>4820 Meridian Commerce Parkway, Suite 300</AdrLine>
                    <AdrLine>Chicago, IL 60606</AdrLine>
                </PstlAdr>
            </Dbtr>
            <DbtrAcct>
                <Id>
                    <Othr>
                        <Id>1234567890123</Id>
                    </Othr>
                </Id>
            </DbtrAcct>
            <DbtrAgt>
                <FinInstnId>
                    <BICFI>FKFRUS33XXX</BICFI>
                    <ClrSysMmbId>
                        <MmbId>071000013</MmbId>
                    </ClrSysMmbId>
                    <Nm>Fictional First National Bank</Nm>
                </FinInstnId>
            </DbtrAgt>
            <UltmtDbtr>
                <Nm>Fictional Holdings Parent Corp</Nm>
            </UltmtDbtr>
            <ChrgBr>SHAR</ChrgBr>
            <CdtTrfTxInf>
                <PmtId>
                    <InstrId>SAMPLEINSTR-0001</InstrId>
                    <EndToEndId>SAMPLEE2E-0001</EndToEndId>
                </PmtId>
                <Amt>
                    <InstdAmt Ccy="USD">125000.00</InstdAmt>
                </Amt>
                <ChrgBr>SHAR</ChrgBr>
                <IntrmyAgt1>
                    <FinInstnId>
                        <BICFI>FKINUS44XXX</BICFI>
                        <ClrSysMmbId>
                            <MmbId>021000021</MmbId>
                        </ClrSysMmbId>
                        <Nm>Fictional Intermediary Bank One</Nm>
                    </FinInstnId>
                </IntrmyAgt1>
                <IntrmyAgt2>
                    <FinInstnId>
                        <BICFI>FKINUS55XXX</BICFI>
                        <ClrSysMmbId>
                            <MmbId>026009593</MmbId>
                        </ClrSysMmbId>
                        <Nm>Fictional Intermediary Bank Two</Nm>
                    </FinInstnId>
                </IntrmyAgt2>
                <CdtrAgt>
                    <FinInstnId>
                        <BICFI>FKRCUS66XXX</BICFI>
                        <ClrSysMmbId>
                            <MmbId>091000019</MmbId>
                        </ClrSysMmbId>
                        <Nm>Fictional Receiving Bank NA</Nm>
                    </FinInstnId>
                </CdtrAgt>
                <Cdtr>
                    <Nm>Sample Vendor Supply Corp</Nm>
                    <PstlAdr>
                        <StrtNm>1500 Innovation Drive</StrtNm>
                        <BldgNb>Building 7</BldgNb>
                        <PstCd>75201</PstCd>
                        <TwnNm>Dallas</TwnNm>
                        <CtrySubDvsn>TX</CtrySubDvsn>
                        <Ctry>US</Ctry>
                        <AdrLine>1500 Innovation Drive, Building 7</AdrLine>
                        <AdrLine>Dallas, TX 75201</AdrLine>
                    </PstlAdr>
                </Cdtr>
                <CdtrAcct>
                    <Id>
                        <Othr>
                            <Id>9988776655443</Id>
                        </Othr>
                    </Id>
                </CdtrAcct>
                <UltmtCdtr>
                    <Nm>Sample Vendor Supply Corp Parent Group</Nm>
                </UltmtCdtr>
                <InstrForCdtrAgt>
                    <Cd>HOLD</Cd>
                    <InstrInf>Hold for customer pickup per prior arrangement</InstrInf>
                </InstrForCdtrAgt>
                <RmtInf>
                    <Ustrd>Invoice 88231 - August fuel and freight settlement</Ustrd>
                </RmtInf>
            </CdtTrfTxInf>
        </PmtInf>
    </CstmrCdtTrfInitn>
</Document>
Response samples
application/json
{
  • "paymentIds": [
    ]
}