Input XML File for PAIN.008.001.02

This page contains a description of the input XML file for the PAIN.008.001.02 specification, which is used for ACH Direct Debit (ACH Pull) CCD and PPD payments.

The following is a high-level example of a PAIN.008.001.02 input XML file:

<?xml version="1.0" encoding="UTF-8" ?>
<Document xmlns="urn:iso:std:iso:20022:tech:xsd:pain.008.001.02">
    <CstmrDrctDbtInitn>
        <GrpHdr>
            ...
        </GrpHdr>    
        <PmtInf>
           ...
        </PmtInf>
    </CstmrDrctDbtInitn>
</Document>

The root document tag for the input file is CstmrDrctDbtInitn. It contains a Group Header and at least one Payment Information building block (corresponding to a batch). The Group Header contains metadata that relates to all the batches in the file. Each batch contains meta data for all the transactions within.

Group Header (GrpHdr)

Your XML Input file must include a group header using the GrpHdr building block. This building block is only present once in a file and contains a set of characteristics shared by all the individual instructions included in the message.

<GrpHdr>
    <MsgId>ABCDEFG090301</MsgId>
    <CreDtTm>2013-08-28T17:12:44</CreDtTm>
    <NbOfTxs>5</NbOfTxs>
    <CtrlSum>43236.93</CtrlSum>
    <InitgPty>
      ...
    </InitgPty>
</GrpHdr>

Here's an explanation of the different tags in the GrpHdr block as shown above:

  • MsgId: An ID number for the message, which you assign before sending the file to CRB.
  • CreDtTm: The date and time the payment instruction was created.
  • NbOfTxs: The total number of transaction instruction blocks in the message. Each instruction corresponds to one transaction, and will form a separate instruction block. For more information on the transaction instruction blocks, see the Direct Debit Transaction Information section below.
  • CtrlSum: The total amount (as a number) of all the instructions included in the file, irrespective of currencies, used as a control sum. Note: Unicorn currently supports USD only.
  • InitgPty: Indicates the party initiating the transfer. This is the party initiating the credit transfer on behalf of the debtor. See the Initiating Party section that follows for more details on the tags inside the InitgPty block.

Note: All the above elements in the GrpHdr block are required.

Initiating Party (InitgPty)

The Initiating Party is the party initiating the payment. This is the party that initiates the credit transfer on behalf of the debtor.

<InitgPty>
    <Nm>John Doe Corporation</Nm>
    <Id>
        <OrgId>
            <Othr>
                <Id>0123456789</Id>
            </Othr>
        </OrgId>
    </Id>
</InitgPty>

Here's an explanation of the different tags in the InitgPty block as shown above:

  • Nm: Name by which the originating party is known and which is usually used to identify that party.
  • Id: Identifier. The parent element of the OrgId element containing the identifying information about the initiating party.
  • OrgId: Organization Identification block containing the initiating party's identification in its child elements.
  • Othr: A block containing the initiating party's identification in a child element.
  • Id: The unique and unambiguous identifier the initiating party, which can be an organization or an individual person.

Note: All the above elements in the InitgPty block are required.

Payment Information (PmtInf)

The PmtInf block contains payment information per batch in your file. You must include at least one PmtInf block in your file. In most cases the input file contains only one PmtInf block, with one set of payment instructions. This enables you to indicate general properties (such as execution date, creditor information, and credited account) once at the level of the PmtInf block.

You might want to use multiple PmtInf blocks if the file includes instructions to credit more than one account. In that case, you need a PmtInf block for each account that is going to be credited.

<PmtInf>
    <PmtInfId>DOMC10000025</PmtInfId>
    <PmtMtd>DD</PmtMtd>
    <BtchBookg>false</BtchBookg>
    <NbOfTxs>5</NbOfTxs>
    <CtrlSum>12.01</CtrlSum>
    <PmtTpInf>
        ...
    </PmtTpInf>
    <ReqdColltnDt>2020-08-21</ReqdColltnDt>
    <Cdtr>
        ...
    </Cdtr>
    <CdtrAcct>
        ...
    </CdtrAcct>
    <CdtrAgt>
        ...
    </CdtrAgt> 
    <DrctDbtTxInf>
        ...
    </DrctDbtTxInf>
</PmtInf>

Below is an explanation of the different top-level tags and blocks found in the PmtInf block as shown above. These tags and blocks appear once for each PmtInf block, except for the DrctDbtTxInf block, which can appear multiple times, representing multiple transactions. Each of the other tags and blocks applies to all DrctDbtTxInf blocks that appear in the PmtInf block:

  • PmtInf: This block contains payment information, such as creditor and payment type information. You can use this block repeatedly within the same input file. Note: One or more instances of the PmtInf element is required.
  • PmtInfId: The unique ID number for this batch, which is assigned by the originating party. Note: This element is required.
  • PmtMtd: Payment Method. For direct debit transactions you should define it as "DD". Note: This element is required.
  • BtchBookg: Defines how CRB should handle the debit. If the tag is set to "TRUE", then all debit instructions will be handled as one consolidated debit. If the tag is set to "FALSE", it means that you want each debit to be handled separately. Note: Currently the system will always behave as if the value is "FALSE".
  • NbOfTxs: The number of transactions within this batch. Note: This element is required.
  • CtrlSum: The sum total of all instructions within this batch, irrespective of currencies, used as a control sum. Note: Unicorn currently supports "USD" only. Note: This element is required.
  • PmtTpInf: The Payment Type Information block, including a priority level. See the Payment Type Information section below for more details on the PmtTpInf block. Note: This element is required.
  • ReqdColltnDt: Requested Collection Date. The date on which the originator's account is to be debited. This tag currently supports current dates. Support for future dates will come in a future release. Note: This element is required.
  • Cdtr: Creditor block. Contains the name and postal address of the originator. See the Creditor section below for an example of the Cdtr block. Note: This element is required.
  • CdtrAcct: Creditor Account. The account of the originator that will be credited. See the Creditor Account section below for more details on the CdtrAcct block. Note: This element is required.
  • CdtrAgt: Creditor Agent block. Details on the creditor's financial institution. See the Creditor Agent section below for more details on the CdtrAgt block. Note: This element is required.
  • DrctDbtTxInf: Direct Debit Transaction Information. Includes elements related to the debit side of the transaction, such as debtor and remittance information. This block can appear multiple times within the same PmtInf block. See the Direct Debit Transaction Information section below for more details on the DrctDbtTxInf block. Note: One or more of the CdtTrfTxInf element is required.

Payment Type Information (PmtTpInf)

The PmtTpInf block contains information on the payment type.

<PmtTpInf>
    <SvcLvl>
        <Cd>NURG</Cd>
    </SvcLvl>
    <LclInstrm>
        <Prtry>CCD</Prtry>
    </LclInstrm>
</PmtTpInf>

Here's an explanation of the different tags in the PmtTpInf block as shown in the examples above:

  • SvcLvl: Service Level. Contains the payment urgency level (Cd) in a child element.
  • Cd: Code: Payment urgency level. Note: This element is required. For direct debit transactions this has a fixed value of "NURG".
  • LclInstrm: Local Instrument. Used to specify a local instrument, local clearing option and/or to further qualify the service or service level. Note: This element is required.
  • Prtry: Proprietary. Note: This element is required. The value must be the ACH Pull type ("CCD" or "PPD").

Creditor (Cdtr)

The Cdtr block contains information on the name, postal address and ID of the originator (creditor).

<Cdtr>
    <Nm>John Doe Corporation</Nm>
    <PstlAdr>
        <Ctry>US</Ctry>
        <AdrLine>999 Any Street, 13th Floor</AdrLine>
        <AdrLine>99999 Anytown</AdrLine>
    </PstlAdr>
    <Id>
        <OrgId>
            <Othr>
                <Id>0123456789</Id>
            </Othr>
        </OrgId>
    </Id>
</Cdtr>
  • Nm: Creditor name.
  • PstlAdr: A block containing the postal address of the creditor, including country and address lines.
  • Id: Identification block, containing information used to identify the creditor in child elements.
  • OrgId: Organization Identification block containing the creditor identification in its child elements.
  • Othr: A block containing the creditor identification in a child element.
  • Id: A unique and unambiguous identifier of the creditor. This ID is identical to the Id field in the InitgPty block described above.

Creditor Account (CdtrAcct)

The CdtrAccount block contains information on the account of the originator that will be credited.

<CdtrAcct>
    <Id>
        <Othr>
            <Id>0123456789</Id>
        </Othr>
    </Id>
    <Ccy>USD</Ccy>
</CdtrAcct>

Here's an explanation of the different tags in the CdtrAccount block as shown above:

  • Id: The sub-block containing the creditor's account identification information.
  • Othr: The sub-block containing the creditor's Id tag.
  • Id: The unique identifier of the creditor's account.
  • Ccy: Currency. The ISO currency code of the debtor's account.

Note: All the above elements in the CdtrAcct block are required.

Creditor Agent (CdtrAgt)

The CdtrAgt block contains information on the originator's financial institution.

<CdtrAgt>
    <FinInstnId>
        <ClrSysMmbId>
            <MmbId>123456789</MmbId>
        </ClrSysMmbId>
        <PstlAdr>
            <Ctry>US</Ctry>
        </PstlAdr>
    </FinInstnId>
</CdtrAgt>

Here's an explanation of the different tags in the CdtrAgt block as shown above:

  • FinInstnId: Financial Institution Identification sub-block.
  • ClrSysMmbId: Clearing System Member Identification sub-block. Contains Information used to identify a member within a clearing system.
  • MmbId: Member Identification: Identifier (routing number) of the creditor's financial institution in the creditor's clearing system. For Direct Debit, this value must always be CRB's routing number (021214891).
  • PstlAdr: Postal Address sub-block.
  • Ctry: Country code. The country code for the debtor's financial institution.

Note: All the above elements in the CdtrAgt block are required.

Direct Debit Transaction Information (DrctDbtTxInf)

The DrctDbtTxInf block includes elements related to the debit side of the transaction, such as debitor and remittance information for the transaction. You can use this block repeatedly within the same PmtInf block. The number of occurrences of the DrctDbtTxInf block within a file is indicated by the NbOfTxs field in the Group Header (GrpHdr).

<DrctDbtTxInf>
    <PmtId>
        <EndToEndId>100DDEB000000</EndToEndId>
    </PmtId>
    <InstdAmt Ccy="USD">0.01</InstdAmt>
    <DbtrAgt>
        <FinInstnId>
            <ClrSysMmbId>
                <MmbId>123456789</MmbId>
            </ClrSysMmbId>
            <Nm>DUMMY</Nm>
            <PstlAdr>
                <Ctry>US</Ctry>
            </PstlAdr>
        </FinInstnId>
    </DbtrAgt>
    <Dbtr>
        <Nm>John Doe</Nm>
        <PstlAdr>
            <Ctry>US</Ctry>
        </PstlAdr>
    </Dbtr>
    <DbtrAcct>
        <Id>
            <Othr>
                    <Id>01234567890</Id>
            </Othr>
        </Id>
    </DbtrAcct>
    <RmtInf>
        <Ustrd>Testing</Ustrd>
    </RmtInf>
</DrctDbtTxInf>

Here's an explanation of the different tags in the DrctDbtTxInf block as shown above:

  • PmtId: Payment Identification sub-block. Provides identifying information regarding the transaction in child elements. Note: This element is required.
  • EndToEndId: End to End Identification: End-to-end reference number of the credit transfer. This information is sent to the beneficiary. Note: This element is required.
  • InstdAmt: Instructed Amount. The amount of the credit transfer in the indicated currency. Note: This element is required.
  • DbtrAgt: Debtor Agent block. Details on the debtor's financial institution for the transaction. See the Debtor Agent section below for more details on the DbtrAgt block. Note: This element is required.
  • Dbtr: The debtor sub-block. Contains details on the debtor for the transaction, including Nm (name) and PstlAdr (postal address) elements. Note: The Dbtr block and its Nm element are required. The PstlAdr element is not required.
  • DbtrAcct: Debtor account sub-block for the transaction, containing the debtor account number in its child elements. Note: This element is required.
  • Id: Identification sub-block. Contains an identification of the debtor account in child elements. Note: This element is required.
  • Othr: Sub-block containing the debtor's Id tag. Note: This element is required.
  • Id: The unique identifier of the debtor's account. Note: This element is required.
  • RmtInf: The remittance information to send along with the transaction. Note: This element is required for ACH Direct Debit.
  • Ustrd: Unstructured description of the transaction. Note: This element is required.

Debtor Agent (DbtrAgt)

The DbtrAgt block contains information on the debtor's financial institution.

<DbtrAgt>
    <FinInstnId>
        <ClrSysMmbId>
            <MmbId>123456789</MmbId>
        </ClrSysMmbId>
        <Nm>John Doe Bank</Nm>
        <PstlAdr>
            <Ctry>US</Ctry>
        </PstlAdr>
    </FinInstnId>
</DbtrAgt>

Here's an explanation of the different tags in the DbtrAgt block as shown above:

  • FinInstnId: Financial Institution Identification sub-block.
  • ClrSysMmbId: Clearing System Member Identification sub-block. Contains Information used to identify a member within a clearing system.
  • MmbId: Member Identification: Identification (routing number) of the debtor's financial institution in the debtor's clearing system.
  • Nm: Name of the debtor's financial institution.
  • PstlAdr: Postal Address sub-block.
  • Ctry: Country code. The ISO country code for the creditor's financial institution.

Note: All the above elements in the DbtrAgt block are required.


Did this page help you?