ISO20022 payments
Preparing your input XML file

PAIN.001.001.03 input file

20min
this page contains a description of the input xml file for the pain 001 001 03 format, which is used for book transfers, ach push ccd/ppd, and fedwires the following is a high level example of a pain 001 001 03 input xml file \<?xml version="1 0" encoding="utf 8" ?> \<document xmlns="urn\ iso\ std\ iso 20022\ tech\ xsd\ pain 001 001 03" xmlns\ xsi="http //www w3 org/2001/xmlschema instance"> \<cstmrcdttrfinitn> \<grphdr> \</grphdr> \<pmtinf> \</pmtinf> \<pmtinf> \</pmtinf> \</cstmrcdttrfinitn> \</document> the root document tag for the input file is cstmrcdttrfinitn 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 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 instruction blocks, see the credit transfer 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 we support usd only initgpty indicates the party initiating the transfer (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 (the debtor) \<initgpty> \<nm>john doe corporation\</nm> \<id> \<orgid> \<bicorbei>johndoe99\</bicorbei> \</orgid> \</id> \</initgpty> here's an explanation of the different tags in the initgpty block as shown above nm name by which the initiating party is known and which is usually used to identify that party id identification the parent element of the orgid element containing the identifying information about the initiating party orgid organization identification, containing the bicorbei code bicorbei business identification code a unique and unambiguous identifier of 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, debtor, payment type and debited account) once at the level of the pmtinf block you might want to use multiple pmtinf blocks if the file includes instructions to debit more than one account in that case, you need a pmtinf block for each account that is going to be debited \<pmtinf> \<pmtinfid>cash10002273\</pmtinfid> \<pmtmtd>trf\</pmtmtd> \<btchbookg>false\</btchbookg> \<nboftxs>1\</nboftxs> \<ctrlsum>0 01\</ctrlsum> \<pmttpinf> \</pmttpinf> \<reqdexctndt>2019 11 19\</reqdexctndt> \<dbtr> \</dbtr> \<dbtracct> \</dbtracct> \<dbtragt> \</dbtragt> \<chrgbr>shar\</chrgbr> \<cdttrftxinf> \</cdttrftxinf> \</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 cdttrftxinf block, which can appear multiple times, representing multiple transactions each of the other tags and blocks applies to all cdttrftxinf blocks that appear in the pmtinf block pmtinf this block contains payment information, such as debtor 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 credit transfers you should define it as "trf" 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 we support "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 reqdexctnd t requested execution 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 dbtr debtor block contains the name and postal address of the originator see the debtor section below for an example of the dbtr block note this element is required dbtracct debtor account the account of the originator that will be debited see the debtor account section below for more details on the dbtracct block note this element is required dbtragt debtor agent block details on the debtor's financial institution see the debtor agent section below for more details on the dbtragt block note this element is required chrgbr chargebearer specifies the bearer of any transaction charges possible values ‘cred’ all transaction charges are to be borne by the creditor ‘debt’ all transaction charges are to be borne by the debtor ‘shar’ both parties bear their own charges note this element is required you should set the value to "shar" cdttrftxinf credit transfer transaction information includes elements related to the credit side of the transaction, such as creditor and remittance information this block can appear multiple times within the same pmtinf block see the credit transfer transaction information section below for more details on the cdttrftxinf block note one or more of the cdttrftxinf element is required payment type information (pmttpinf) the pmttpinf block contains information on the payment type the following example is generic, while each example after it is specific to a rail type \<pmttpinf> \<instrprty>norm\</instrprty> \<svclvl> \<cd>nurg\</cd> \</svclvl> \</pmttpinf> for ach push ccd, the following pmttpinf block is used \<pmttpinf> \<instrprty>norm\</instrprty> \<svclvl> \<cd>nurg\</cd> \</svclvl> \<lclinstrm> \<prtry>ccd\</prtry> \</lclinstrm> \</pmttpinf> for ach push ppd, the following pmttpinf block is used \<pmttpinf> \<instrprty>norm\</instrprty> \<svclvl> \<cd>nurg\</cd> \</svclvl> \<lclinstrm> \<prtry>ppd\</prtry> \</lclinstrm> \</pmttpinf> for fedwires and book transfers, the following pmttpinf block is used \<pmttpinf> \<instrprty>norm\</instrprty> \<svclvl> \<cd>urgp\</cd> \</svclvl> \</pmttpinf> here's an explanation of the different tags in the pmttpinf block as shown in the examples above instrprty instruction priority priority of the instruction (transaction request) value reflects whether the payment processor is providing priority processing or normal processing currently "norm" is the only available value note this element is required svclvl service level contains the payment urgency level ( cd ) in a child element note this element is required cd code the payment urgency level this element is required note for fedwires and book transfers, the cd value must be "urgp" for ach push ccd and ppd, the cd value must be "nurg" lclinstrm local instrument used to specify a local instrument, local clearing option and/or to further qualify the service or service level this element is required for ach push ccd and ppd prtry proprietary this element is required for ach push ccd and ppd the prtry value must be the ach push type ("ccd" or "ppd") debtor (dbtr) the dbtr block contains information on the name and postal address of the originator (debtor) \<dbtr> \<nm>john doe corporation\</nm> \<pstladr> \<strtnm>999 any street\</strtnm> \<pstcd>99999\</pstcd> \<twnnm>anytown\</twnnm> \<ctrysubdvsn>ca\</ctrysubdvsn> \<ctry>us\</ctry> \</pstladr> \</dbtr> nm debtor name pstladr a block containing the postal address tags of the debtor all the above fields in the dbtr block are required debtor account (dbtracct) the dbtraccount block contains information on the account of the originator that will be debited \<dbtracct> \<id> \<othr> \<id>2000526789\</id> \</othr> \</id> \<ccy>usd\</ccy> \</dbtracct> here's an explanation of the different tags in the dbtraccount block as shown above id the sub block containing the debtor's account identification information othr the sub block containing the debtor's id tag id the unique identifier of the debtor's account ccy currency the iso currency code of the debtor's account note this element is required all the above fields in the dbtracct block are required debtor agent (dbtragt) the dbtragt block contains information on the originator's financial institution \<dbtragt> \<fininstnid> \<clrsysmmbid> \<clrsysid> \<cd>usaba\</cd> \</clrsysid> \<mmbid>123456789\</mmbid> \</clrsysmmbid> \<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 clrsysid clearing system identification specification of the pre agreed offering between clearing agents or the channel through which the payment instruction is processed cd code identifier of the debtor's clearing system, in a coded form as published in an external list mmbid member identification identification (routing number) of the debtor's financial institution in the debtor's clearing system note for book transfers, the value of this element must always be cr's routing number (021214891) pstladr postal address sub block ctry country code the country code for the debtor's financial institution all the above elements in the dbtragt block are required credit transfer transaction information (cdttrftxinf) the cdttrftxinf block includes elements related to the credit side of the transaction, such as creditor and remittance information for the transaction you can use this block repeatedly within the same pmtinf block the number of occurrences of the cdttrftxinf block within a file is indicated by the nboftxs field in the group header ( grphdr) \<cdttrftxinf> \<pmtid> \<instrid>100ach000019\</instrid> \<endtoendid>0000000000000003\</endtoendid> \</pmtid> \<amt> \<instdamt ccy="usd">0 01\</instdamt> \</amt> \<cdtragt> \</cdtragt> \<cdtr> \<nm>john doe funding llc\</nm> \<pstladr> \<strtnm>999 any avenue\</strtnm> \<pstcd>10000\</pstcd> \<twnnm>new york\</twnnm> \<ctrysubdvsn>ny\</ctrysubdvsn> \<ctry>us\</ctry> \</pstladr> \</cdtr> \<cdtracct> \<id> \<othr> \<id>0123456789\</id> \</othr> \</id> \<tp> \<cd>cacc\</cd> \</tp> \<ccy>usd\</ccy> \</cdtracct> \<rmtinf> \<ustrd>testing\</ustrd> \</rmtinf> \</cdttrftxinf> here's an explanation of the different tags in the cdttrftxinf block as shown above pmtid payment identification sub block provides identifying information regarding the transaction in child elements note this element is required instrid instruction identification reference of the remitter, referring to a set of payments of which this payment is a part of this information is not sent to the beneficiary 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 amt amount sub block contains the transaction amount in a child element note this element is required instdamt instructed amount the amount of the credit transfer in the indicated currency note this element is required cdtragt creditor agent sub block contains details on the creditor's financial institution for the transaction see the creditor agent section below for more details on the cdtragt block note this element is required cdtr the creditor sub block contains details on the creditor for the transaction, including nm (name) and pstladr (postal address) elements note the cdtr block and its nm element are required the pstladr element is not required cdtracct creditor account sub block for the transaction, containing the creditor account number and currency in its child elements note this element is required id identification sub block contains an identification of the creditor's account in child elements note this element is required othr sub block containing the creditor's id tag note this element is required id the unique identifier of the creditor's account note this element is required tp type contains the code in its child elements cd code the code of the account type ccy iso currency code of the beneficiary account rmtinf the remittance information to send along with the transaction note this element is required ustrd unstructured description of the transaction maximum limit of 50 characters including spaces note this element is required creditor agent (cdtragt) the cdtragt block contains information on the creditor's financial institution for the transaction \<cdtragt> \<fininstnid> \<clrsysmmbid> \<clrsysid> \<cd>usaba\</cd> \</clrsysid> \<mmbid>123456789\</mmbid> \</clrsysmmbid> \<nm>cross river bank nj\</nm> \<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 clrsysid clearing system identification specification of the pre agreed offering between clearing agents or the channel through which the payment instruction is processed cd code identification of the creditor's clearing system, in a coded form as published in an external list nm name of the creditor's financial institution mmbid member identification identification (routing number) of the creditor's financial institution in the creditor's clearing system note for book transfers, the value of this element must always be cr's routing number (021214891) pstladr postal address sub block ctry country code the iso country code for the creditor's financial institution all the above elements in the cdtragt block are required for a fedwire transaction request, the cdtragt must not be cross river all payment types example wrapping it all up, an example with all payment types \<?xml version="1 0" encoding="utf 8" standalone="no" ?> \<document xmlns="urn\ iso\ std\ iso 20022\ tech\ xsd\ pain 001 001 03"> \<cstmrcdttrfinitn> \<grphdr> \<msgid>domt11234562allrails1\</msgid> \<credttm>2020 06 29t10 24 09\</credttm> \<nboftxs>3\</nboftxs> \<ctrlsum>3 03\</ctrlsum> \<initgpty> \<nm>shach corp\</nm> \<id> \<orgid> \<bicorbei>theshach99\</bicorbei> \</orgid> \</id> \</initgpty> \</grphdr> \<pmtinf> \<pmtinfid>domt12345678ach1\</pmtinfid> \<pmtmtd>trf\</pmtmtd> \<btchbookg>false\</btchbookg> \<nboftxs>1\</nboftxs> \<ctrlsum>0 01\</ctrlsum> \<pmttpinf> \<instrprty>norm\</instrprty> \<svclvl> \<cd>nurg\</cd> \</svclvl> \<lclinstrm> \<prtry>ccd\</prtry> \</lclinstrm> \</pmttpinf> \<reqdexctndt>2020 06 29\</reqdexctndt> \<dbtr> \<nm>john doe corporation\</nm> \<pstladr> \<strtnm>999 battery street, 13th floor\</strtnm> \<pstcd>99999\</pstcd> \<twnnm>anytown\</twnnm> \<ctrysubdvsn>ca\</ctrysubdvsn> \<ctry>us\</ctry> \</pstladr> \</dbtr> \<dbtracct> \<id> \<othr> \<id>2756493439\</id> \</othr> \</id> \<ccy>usd\</ccy> \</dbtracct> \<dbtragt> \<fininstnid> \<clrsysmmbid> \<clrsysid> \<cd>usaba\</cd> \</clrsysid> \<mmbid>123456789\</mmbid> \</clrsysmmbid> \<pstladr> \<ctry>us\</ctry> \</pstladr> \</fininstnid> \</dbtragt> \<chrgbr>shar\</chrgbr> \<cdttrftxinf> \<pmtid> \<instrid>234achc123455ach1\</instrid> \<endtoendid>0000000000000011ach1\</endtoendid> \</pmtid> \<amt> \<instdamt ccy="usd">0 01\</instdamt> \</amt> \<cdtragt> \<fininstnid> \<clrsysmmbid> \<clrsysid> \<cd>usaba\</cd> \</clrsysid> \<mmbid>123456789\</mmbid> \</clrsysmmbid> \<nm>cross river bank nj\</nm> \<pstladr> \<ctry>us\</ctry> \</pstladr> \</fininstnid> \</cdtragt> \<cdtr> \<nm>john doe funding llc\</nm> \<pstladr> \<strtnm>999 any avenue\</strtnm> \<pstcd>10000\</pstcd> \<twnnm>new york\</twnnm> \<ctrysubdvsn>ny\</ctrysubdvsn> \<ctry>us\</ctry> \</pstladr> \</cdtr> \<cdtracct> \<id> \<othr> \<id>0123456789\</id> \</othr> \</id> \<tp> \<cd>cacc\</cd> \</tp> \<ccy>usd\</ccy> \</cdtracct> \<rmtinf> \<ustrd>testing\</ustrd> \</rmtinf> \</cdttrftxinf> \</pmtinf> \<pmtinf> \<pmtinfid>domt10000000wire1\</pmtinfid> \<pmtmtd>trf\</pmtmtd> \<btchbookg>false\</btchbookg> \<nboftxs>1\</nboftxs> \<ctrlsum>3 00\</ctrlsum> \<pmttpinf> \<instrprty>norm\</instrprty> \<svclvl> \<cd>urgp\</cd> \</svclvl> \</pmttpinf> \<reqdexctndt>2020 07 15\</reqdexctndt> \<dbtr> \<nm>john doe corporation\</nm> \<pstladr> \<strtnm>999 any street, 13th floor\</strtnm> \<pstcd>99999\</pstcd> \<twnnm>anytown\</twnnm> \<ctrysubdvsn>ca\</ctrysubdvsn> \<ctry>us\</ctry> \</pstladr> \</dbtr> \<dbtracct> \<id> \<othr> \<id>2756493439\</id> \</othr> \</id> \<ccy>usd\</ccy> \</dbtracct> \<dbtragt> \<fininstnid> \<clrsysmmbid> \<clrsysid> \<cd>usaba\</cd> \</clrsysid> \<mmbid>123456789\</mmbid> \</clrsysmmbid> \<pstladr> \<ctry>us\</ctry> \</pstladr> \</fininstnid> \</dbtragt> \<chrgbr>shar\</chrgbr> \<cdttrftxinf> \<pmtid> \<instrid>100fed000000xxxwire1\</instrid> \<endtoendid>0000000000000065xxxwire1\</endtoendid> \</pmtid> \<amt> \<instdamt ccy="usd">3 00\</instdamt> \</amt> \<cdtragt> \<fininstnid> \<clrsysmmbid> \<clrsysid> \<cd>usaba\</cd> \</clrsysid> \<mmbid>123456789\</mmbid> \</clrsysmmbid> \<nm>cross river bank nj\</nm> \<pstladr> \<ctry>us\</ctry> \</pstladr> \</fininstnid> \</cdtragt> \<cdtr> \<nm>john doe funding llc\</nm> \<pstladr> \<strtnm>999 any avenue\</strtnm> \<pstcd>10000\</pstcd> \<twnnm>new york\</twnnm> \<ctrysubdvsn>ny\</ctrysubdvsn> \<ctry>us\</ctry> \</pstladr> \</cdtr> \<cdtracct> \<id> \<othr> \<id>0123456789\</id> \</othr> \</id> \<ccy>usd\</ccy> \</cdtracct> \<rmtinf> \<ustrd>allrails wire 1\</ustrd> \</rmtinf> \</cdttrftxinf> \</pmtinf> \<pmtinf> \<pmtinfid>domt12345678rtp1\</pmtinfid> \<pmtmtd>trf\</pmtmtd> \<btchbookg>false\</btchbookg> \<nboftxs>1\</nboftxs> \<ctrlsum>0 02\</ctrlsum> \<pmttpinf> \<instrprty>norm\</instrprty> \<svclvl> \<cd>urns\</cd> \</svclvl> \<lclinstrm> \<prtry>rtp\</prtry> \</lclinstrm> \</pmttpinf> \<reqdexctndt>2020 06 29\</reqdexctndt> \<dbtr> \<nm>john doe corporation\</nm> \<pstladr> \<strtnm>999 battery street, 13th floor\</strtnm> \<pstcd>99999\</pstcd> \<twnnm>anytown\</twnnm> \<ctrysubdvsn>ca\</ctrysubdvsn> \<ctry>us\</ctry> \</pstladr> \</dbtr> \<dbtracct> \<id> \<othr> \<id>2756493439\</id> \</othr> \</id> \<ccy>usd\</ccy> \</dbtracct> \<dbtragt> \<fininstnid> \<clrsysmmbid> \<clrsysid> \<cd>usaba\</cd> \</clrsysid> \<mmbid>123456789\</mmbid> \</clrsysmmbid> \<pstladr> \<ctry>us\</ctry> \</pstladr> \</fininstnid> \</dbtragt> \<chrgbr>shar\</chrgbr> \<cdttrftxinf> \<pmtid> \<instrid>234achc123455rtp1\</instrid> \<endtoendid>0000000000000011rtp1\</endtoendid> \</pmtid> \<amt> \<instdamt ccy="usd">0 02\</instdamt> \</amt> \<cdtragt> \<fininstnid> \<clrsysmmbid> \<clrsysid> \<cd>usaba\</cd> \</clrsysid> \<mmbid>123456789\</mmbid> \</clrsysmmbid> \<nm>cross river bank nj\</nm> \<pstladr> \<ctry>us\</ctry> \</pstladr> \</fininstnid> \</cdtragt> \<cdtr> \<nm>john doe funding llc\</nm> \<pstladr> \<strtnm>999 any avenue\</strtnm> \<pstcd>10000\</pstcd> \<twnnm>new york\</twnnm> \<ctrysubdvsn>ny\</ctrysubdvsn> \<ctry>us\</ctry> \</pstladr> \</cdtr> \<cdtracct> \<id> \<othr> \<id>0123456789\</id> \</othr> \</id> \<tp> \<cd>cacc\</cd> \</tp> \<ccy>usd\</ccy> \</cdtracct> \<rmtinf> \<ustrd>allrails rtp 1\</ustrd> \</rmtinf> \</cdttrftxinf> \</pmtinf> \</cstmrcdttrfinitn> \</document>