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 usage, definition and structure

1.1. Usage

pacs.008  →  [Cancellation Request sent by Requester Bank]
                       ↓
camt.029  ←  [Resolution Response sent by Responder Bank]

1.2. XSD definition and structure

The XSD message is available here.

A simplified structure is shown below:

Document
└── FIToFICstmrCdtTrf                          ← Root: FI To FI Customer Credit Transfer
    ├── GrpHdr   [1..1]                        ← Group Header (mandatory)
    │   ├── MsgId                              ← Message ID, text 1..35
    │   ├── CreDtTm                            ← Creation date/time, ISODateTime
    │   ├── NbOfTxs                            ← Number of transactions
    │   ├── SttlmInf [1..1]                    ← Settlement Information (mandatory)
    │   │   ├── SttlmMtd                       ← Settlement method (e.g. CLRG)
    │   │   └── ClrSys   [0..1]                ← Clearing System (optional)
    │   │       ├── Cd                         ← ISO code, text 1..4 (exclusive with Prtry)
    │   │       └── Prtry                      ← Proprietary code, text 1..35
    │   ├── InstgAgt [0..1]                    ← Instructing Agent / sender (optional)
    │   │   └── FinInstnId
    │   │       ├── BICFI                      ← BIC of instructing agent
    │   │       └── ClrSysMmbId                ← Clearing system member ID
    │   └── InstdAgt [0..1]                    ← Instructed Agent / receiver (optional)
    │       └── FinInstnId
    │           ├── BICFI
    │           └── ClrSysMmbId
    └── CdtTrfTxInf [1..n]                     ← Credit Transfer Transaction Info (1 or more)
        ├── PmtId    [1..1]                    ← Payment Identification (mandatory)
        │   ├── InstrId                        ← Instruction ID, optional, text 1..35
        │   ├── EndToEndId                     ← End-to-end ID, mandatory, text 1..35
        │   ├── TxId                           ← Transaction ID, mandatory, text 1..35
        │   └── UETR                           ← UUID v4, optional
        ├── PmtTpInf [0..1]                    ← Payment Type Information (optional)
        │   ├── SvcLvl   [0..1]                ← Service Level (optional)
        │   │   ├── Cd                         ← ISO code, text 1..4 (exclusive with Prtry)
        │   │   └── Prtry                      ← Proprietary code, text 1..35
        │   └── LclInstrm [0..1]               ← Local Instrument (optional)
        │       ├── Cd                         ← ISO code, text 1..35 (exclusive with Prtry)
        │       └── Prtry                      ← Proprietary code, text 1..35
        ├── AccptncDtTm [0..1]                 ← Acceptance Date/Time — mandatory for real-time payments
        ├── IntrBkSttlmAmt [1..1]              ← Interbank Settlement Amount (mandatory)
        ├── IntrBkSttlmDt  [0..1]              ← Interbank Settlement Date (optional)
        ├── UltmtDbtr [0..1]                   ← Ultimate Debtor (optional)
        │   └── Nm                             ← Name
        ├── Dbtr      [1..1]                   ← Debtor / payer (mandatory)
        │   ├── Nm                             ← Name (mandatory in Mambu Payments)
        │   ├── PstlAdr  [0..1]                ← Postal Address (optional)
        │   │   ├── Dept                       ← Department
        │   │   ├── SubDept                    ← Sub-department
        │   │   ├── StrtNm                     ← Street name
        │   │   ├── BldgNb                     ← Building number
        │   │   ├── BldgNm                     ← Building name
        │   │   ├── Flr                        ← Floor
        │   │   ├── PstBx                      ← PO box
        │   │   ├── Room                       ← Room
        │   │   ├── PstCd                      ← Postal code
        │   │   ├── TwnNm                      ← Town name
        │   │   ├── TwnLctnNm                  ← Town location name
        │   │   ├── DstrctNm                   ← District name
        │   │   ├── CtrySubDvsn                ← State or province
        │   │   ├── Ctry                       ← Country, ISO alpha-2
        │   │   └── AdrLine [0..2]             ← Unstructured address lines (max 2 in Mambu Payments)
        │   └── Id       [0..1]                ← Identification (optional, OrgId XOR PrvtId)
        │       ├── OrgId  [0..1]              ← Organisation Identification
        │       │   ├── AnyBIC                 ← Business Identification Code
        │       │   ├── LEI                    ← Legal Entity Identifier
        │       │   └── Othr   [0..n]          ← Other identification
        │       │       ├── Id
        │       │       └── SchmeNm
        │       │           ├── Cd
        │       │           └── Prtry
        │       └── PrvtId [0..1]              ← Private / Individual Identification
        │           ├── DtAndPlcOfBirth [0..1]
        │           │   ├── BirthDt
        │           │   ├── PrvcOfBirth
        │           │   ├── CityOfBirth
        │           │   └── CtryOfBirth
        │           └── Othr   [0..n]
        │               ├── Id
        │               └── SchmeNm
        │                   ├── Cd
        │                   └── Prtry
        ├── DbtrAcct  [1..1]                   ← Debtor Account (mandatory)
        │   └── Id
        │       ├── IBAN                       ← Standard IBAN (mutually exclusive with Othr)
        │       └── Othr                       ← Proprietary account ID
        │           ├── Id
        │           └── SchmeNm
        │               ├── Cd
        │               └── Prtry
        ├── DbtrAgt   [1..1]                   ← Debtor Agent / debtor's bank (mandatory)
        │   └── FinInstnId
        │       ├── BICFI                      ← BIC 8 or BIC 11 (exclusive with ClrSysMmbId)
        │       └── ClrSysMmbId                ← Local clearing code
        │           ├── ClrSysId
        │           │   ├── Cd                 ← e.g. USABA, GBDSC, DEBLZ
        │           │   └── Prtry
        │           └── MmbId                  ← Member ID, text 1..35
        ├── CdtrAgt   [1..1]                   ← Creditor Agent / creditor's bank (mandatory)
        │   └── FinInstnId                     ← Same structure as DbtrAgt
        │       ├── BICFI
        │       └── ClrSysMmbId
        │           ├── ClrSysId
        │           │   ├── Cd
        │           │   └── Prtry
        │           └── MmbId
        ├── Cdtr      [1..1]                   ← Creditor / beneficiary (mandatory)
        │   ├── Nm                             ← Name (mandatory in Mambu Payments)
        │   ├── PstlAdr  [0..1]                ← Same structure as Dbtr/PstlAdr
        │   └── Id       [0..1]                ← Same structure as Dbtr/Id (OrgId XOR PrvtId)
        ├── CdtrAcct  [1..1]                   ← Creditor Account (mandatory)
        │   └── Id                             ← Same structure as DbtrAcct
        │       ├── IBAN
        │       └── Othr
        │           ├── Id
        │           └── SchmeNm
        │               ├── Cd
        │               └── Prtry
        ├── UltmtCdtr  [0..1]                  ← Ultimate Creditor (optional)
        │   ├── Nm                             ← Name (mandatory in Mambu Payments)
        │   ├── PstlAdr  [0..1]                ← Same structure as Dbtr/PstlAdr
        │   └── Id       [0..1]                ← Same structure as Dbtr/Id (OrgId XOR PrvtId)
        ├── Purp       [0..1]                  ← Purpose (optional)
        │   ├── Cd                             ← ISO code, text 1..4 (exclusive with Prtry)
        │   └── Prtry                          ← Proprietary code, text 1..35
        └── RmtInf                             ← Remittance information (optional)
            ├── Ustrd    [0..n]                ← Unstructured (exclusive with Strd)
            └── Strd     [0..n]                ← Structured

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

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

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