PAIN.001.001.03 input file
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:
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.
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.
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: Unicorn supports 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.
The Initiating Party is the party initiating the payment (the debtor).
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.
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.
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: 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.
- ReqdExctnDt: 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.
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.
For ACH Push CCD, the following PmtTpInf block is used:
For ACH Push PPD, the following PmtTpInf block is used:
For Fedwires and Book transfers, the following PmtTpInf block is used:
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").
The Dbtr block contains information on the name and postal address of the originator (debtor).
- Nm: Debtor name.
- PstlAdr: A block containing the postal address tags of the debtor.
All the above fields in the Dbtr block are required.
The DbtrAccount block contains information on the account of the originator that will be debited.
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.
The DbtrAgt block contains information on the originator's financial institution.
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.
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).
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.
The CdtrAgt block contains information on the creditor's financial institution for the transaction.
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.
Wrapping it all up, an example with all payment types
