pacs.008.001.08 XSD schema and business logic

A pacs.008.001.08 is a Financial Institution to Financial Institution Customer Credit Transfer, used to move funds from a debtor to a creditor via a payment scheme.

Mambu Payments supports the following transfer types:

Standard credit transfers
Real-time credit transfers
RTGS / high-value credit transfers

The payment scheme determines which transfer type applies. See supported payment schemes for a high level description.

1. Message definition and structure

Access the message definition and structure here.

2. Business logic

2.1. Payment identification

A payment is identified by the Payment Information block inside CdtTrfTxInf:

<CdtTrfTxInf>
  <PmtId>
    <InstrId></InstrId>     <!-- Instruction ID, optional, text 1..35 -->
    <EndToEndId></EndToEndId> <!-- End-to-end ID, mandatory, text 1..35 -->
    <TxId></TxId>           <!-- Transaction ID, mandatory, text 1..35 -->
    <UETR></UETR>           <!-- Unique end-to-end transaction reference, optional, UUID v4 -->
  </PmtId>
</CdtTrfTxInf>

Field	Tag	Required	Description
End-to-end ID	`<EndToEndId>`	Mandatory	Unique reference set by the first originator PSP in the payment chain. Use `NOTPROVIDED` if unavailable.
Transaction ID	`<TxId>`	Mandatory	Unique reference assigned by the instructing party to the instructed party. May equal the end-to-end ID.
Instruction ID	`<InstrId>`	Optional	Unique instruction reference assigned by the instructing party. May equal the transaction ID or end-to-end ID.
UETR	`<UETR>`	Optional	UUID v4 end-to-end reference. Originally defined by SWIFT, now adopted outside of SWIFT.

2.2. Determination of payment type

Mambu Payments determines the payment type from three fields in the message:

Clearing System (ClrSys) – the payment infrastructure used to settle the payment, located in the Settlement Information block
Service Level (SvcLvl) – the rulebook or business rules that apply, located in the Payment Type Information block
Local Instrument (LclInstrm) – the local product or processing stream, located in the Payment Type Information block

<FIToFICstmrCdtTrf>
  <GrpHdr>
    <SttlmInf>
      <SttlmMtd>CLRG</SttlmMtd>
      <ClrSys>  <!-- only one of Cd or Prtry must be present -->
        <Cd></Cd>       <!-- ISO code, text 1..4 -->
        <Prtry></Prtry> <!-- Proprietary code, text 1..35 -->
      </ClrSys>
    </SttlmInf>
  </GrpHdr>
</FIToFICstmrCdtTrf>

<FIToFICstmrCdtTrf>
  <CdtTrfTxInf>
    <PmtTpInf>
      <SvcLvl>    <!-- only one of Cd or Prtry must be present -->
        <Cd></Cd>       <!-- ISO code, text 1..4 -->
        <Prtry></Prtry> <!-- Proprietary code, text 1..35 -->
      </SvcLvl>
      <LclInstrm> <!-- only one of Cd or Prtry must be present -->
        <Cd></Cd>       <!-- ISO code, text 1..35 -->
        <Prtry></Prtry> <!-- Proprietary code, text 1..35 -->
      </LclInstrm>
    </PmtTpInf>
  </CdtTrfTxInf>
</FIToFICstmrCdtTrf>

Although these fields are optional in the ISO 20022 standard, Mambu Payments requires some of them to route your payment correctly.

This is fully described in this spreadsheet that details the different property values in order to identify the scheme for both outgoing and incoming pacs.008.

For example, a US wire payment would be created as follows:

<FIToFICstmrCdtTrf>
  <GrpHdr>
    <SttlmInf>
      <SttlmMtd>CLRG</SttlmMtd>
      <ClrSys>
        <Cd>FDW</Cd> <!-- ISO FDW code -->
      </ClrSys>
    </SttlmInf>
    <!-- ... -->
  </GrpHdr>
  <CdtTrfTxInf>
    <PmtTpInf>
      <SvcLvl> 
        <Cd>URGP</Cd>       <!-- ISO code, text 1..4 -->
      </SvcLvl>
      <!-- no local instrument -->
    </PmtTpInf>
    <!-- ... -->
  </CdtTrfTxInf>
</FIToFICstmrCdtTrf>

2.3. Payment initiation date time

For real-time payments, capture the exact initiation date time in the Acceptance Date Time tag inside CdtTrfTxInf. Payment schemes use this to enforce processing time limits.

<CdtTrfTxInf>
  <AccptncDtTm></AccptncDtTm> <!-- ISO date time, millisecond precision -->
</CdtTrfTxInf>

2.4. Party identification

The parties involved in the transfer are declared in CdtTrfTxInf. This includes the Debtor (payer), the Creditor (beneficiary), and optionally an Ultimate Debtor or Ultimate Creditor for on-behalf-of payments.

2.4.1. Party roles

Role	Tag	Required	Description
Debtor	`<Dbtr>`	Mandatory	The party that owes funds to the creditor.
Creditor	`<Cdtr>`	Mandatory	The party to which funds are due.
Ultimate Debtor	`<UltmtDbtr>`	Optional	The original source of funds, when the Debtor acts on behalf of another party (e.g. a subsidiary).
Ultimate Creditor	`<UltmtCdtr>`	Optional	The ultimate recipient of funds, when the Creditor acts on behalf of another party (e.g. a collection agency). Not supported in Mambu Payments.

<CdtTrfTxInf>
  <UltmtDbtr>             <!-- optional -->
    <Nm>Ultimate debtor name</Nm>
  </UltmtDbtr>
  <Dbtr>                  <!-- mandatory -->
    <Nm>Debtor name</Nm>
  </Dbtr>
  <Cdtr>                  <!-- mandatory -->
    <Nm>Creditor name</Nm>
  </Cdtr>
  <UltmtCdtr>             <!-- optional, not supported in Mambu Payments -->
    <Nm>Ultimate creditor name</Nm>
  </UltmtCdtr>
</CdtTrfTxInf>

2.4.2. Postal address

Provide the postal address of a party inside the <PstlAdr> block within the party identification. Mambu Payments supports unstructured (up to 2 lines), hybrid, and structured addresses.

<CdtTrfTxInf>
  <Dbtr>
    <Nm>Debtor Name</Nm>
    <PstlAdr>
      <Dept>Department Name</Dept>
      <SubDept>Sub Department</SubDept>
      <StrtNm>Street Name</StrtNm>
      <BldgNb>123</BldgNb>
      <BldgNm>Building Name</BldgNm>
      <Flr>5</Flr>
      <PstBx>PO Box 456</PstBx>
      <Room>Room 101</Room>
      <PstCd>10001</PstCd>
      <TwnNm>Town Name</TwnNm>
      <TwnLctnNm>Town Location</TwnLctnNm>
      <DstrctNm>District Name</DstrctNm>
      <CtrySubDvsn>State or Province</CtrySubDvsn>
      <Ctry>US</Ctry>     <!-- ISO alpha-2 country code -->
      <AdrLine>Unstructured Address Line 1</AdrLine>
      <AdrLine>Unstructured Address Line 2</AdrLine>
    </PstlAdr>
  </Dbtr>
</CdtTrfTxInf>

2.4.3. Organisation or private identification

Identify a party using either an organisation identification (<OrgId>) for companies or a private identification (<PrvtId>) for individuals. The two are mutually exclusive.

<!-- Organisation identification -->
<CdtTrfTxInf>
  <Dbtr>
    <Nm>Debtor Name</Nm>
    <Id>
      <OrgId>
        <AnyBIC></AnyBIC> <!-- Business Identification Code -->
        <LEI></LEI>       <!-- Legal Entity Identifier -->
        <Othr>
          <Id></Id>
          <SchmeNm>
            <Cd></Cd>
            <Prtry></Prtry>
          </SchmeNm>
        </Othr>
      </OrgId>
    </Id>
  </Dbtr>
</CdtTrfTxInf>

<!-- Private identification -->
<CdtTrfTxInf>
  <Dbtr>
    <Nm>Debtor Name</Nm>
    <Id>
      <PrvtId>
        <DtAndPlcOfBirth>
          <BirthDt></BirthDt>       <!-- Birth date -->
          <PrvcOfBirth></PrvcOfBirth> <!-- Birth province -->
          <CityOfBirth></CityOfBirth> <!-- Birth city -->
          <CtryOfBirth></CtryOfBirth> <!-- Birth country -->
        </DtAndPlcOfBirth>
        <Othr>
          <Id></Id>
          <SchmeNm>
            <Cd></Cd>
            <Prtry></Prtry>
          </SchmeNm>
        </Othr>
      </PrvtId>
    </Id>
  </Dbtr>
</CdtTrfTxInf>

2.5. Debtor account and creditor account

Declare the debtor account (<DbtrAcct>) and creditor account (<CdtrAcct>) inside CdtTrfTxInf. The account identification is mandatory and uses one of two formats:

IBAN – standard identifier for cross-border and SEPA domestic payments
Other – proprietary identification for non-IBAN accounts, optionally qualified by a scheme name (e.g. BBAN) or issuer

<!-- IBAN format -->
<CdtTrfTxInf>
  <DbtrAcct>
    <Id>
      <IBAN></IBAN>
    </Id>
  </DbtrAcct>
</CdtTrfTxInf>

<!-- Other format -->
<CdtTrfTxInf>
  <DbtrAcct>
    <Id>
      <Othr>
        <Id></Id>
        <SchmeNm>
          <Cd></Cd>
          <Prtry></Prtry>
        </SchmeNm>
        <Issr></Issr>
      </Othr>
    </Id>
  </DbtrAcct>
</CdtTrfTxInf>

2.6. Debtor agent and creditor agent

Declare the debtor agent (<DbtrAgt>, the debtor's bank) and creditor agent (<CdtrAgt>, the creditor's bank) inside CdtTrfTxInf. Identify the agent using one of:

BICFI – ISO 9362 Business Identifier Code for financial institutions (BIC 8 or BIC 11)
Clearing System Member ID – local clearing code (for instance. Sort Code in the UK, Fedwire Routing Number in the US, or BLZ in Germany)

<!-- BICFI identification -->
<CdtTrfTxInf>
  <DbtrAgt>
    <FinInstnId>
      <BICFI></BICFI>
    </FinInstnId>
  </DbtrAgt>
</CdtTrfTxInf>

<!-- Clearing System Member ID -->
<CdtTrfTxInf>
  <DbtrAgt>
    <FinInstnId>
      <ClrSysMmbId>
        <ClrSysId>
          <Cd></Cd>       <!-- text 1..5 -->
          <Prtry></Prtry> <!-- text 1..35 -->
        </ClrSysId>
        <MmbId></MmbId>   <!-- text 1..35 -->
      </ClrSysMmbId>
    </FinInstnId>
  </DbtrAgt>
</CdtTrfTxInf>

Find the full list of clearing system codes in the ISO 20022 External Code Sets under ExternalClearingSystemIdentification1Code. The ISO 20022 Registration Authority updates this list quarterly.

Common clearing system codes include:

Country	Code	System	Bank ID format
Austria	`ATBLZ`	Austrian Bankleitzahl	5 digits
Australia	`AUBSB`	Australian Bank State Branch (BSB)	6 digits
Canada	`CACPA`	Canadian Payments Association Routing Number	9 digits
China	`CNAPS`	CNAPS Identifier	12 digits
Germany	`DEBLZ`	German Bankleitzahl	8 digits
Spain	`ESNCC`	Spanish Domestic Interbanking Code	8–9 digits
United Kingdom	`GBDSC`	UK Domestic Sort Code	6 digits
Hong Kong	`HKNCC`	Hong Kong Bank Code	3 digits
India	`INFSC`	Indian Financial System Code (IFSC)	11 chars
Ireland	`IENCC`	Irish National Clearing Code (NSC)	6 digits
Italy	`ITNCC`	Italian Domestic Identification Code	10 digits
Japan	`JPZGN`	Japan Zengin Clearing Code	7 digits
New Zealand	`NZNCC`	New Zealand National Clearing Code	6 digits
Poland	`PLKNR`	Polish National Clearing Code (KNR)	8 digits
Russia	`RUCBC`	Russian Central Bank Identification Code	9 digits
Singapore	`SGIBG`	IBG Sort Code	7 digits
Switzerland	`CHSIC`	Swiss Clearing Code (SIC)	6 digits
Switzerland	`CHBCC`	Swiss Clearing Code (BC Code)	3–5 digits
USA	`USABA`	Routing Number (Fedwire, NACHA)	9 digits
USA	`USPID`	CHIPS Participant Identifier	4 digits
South Africa	`ZANCC`	South African National Clearing Code	6 digits