PAIN.008.001.02 input file

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 cr best practice use a new for each file 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 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 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 cr 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 drctdbttxinf 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 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 cr's routing number (021214891) pstladr postal address sub block ctry country code the country code for the creditor's financial institution 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 dbtrag t 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 debtor's financial institution all the above elements in the dbtragt block are required