Unicorn Output Files

When Unicorn has processed your payment instructions, it creates XML output files (PSRs) conforming to the ISO 20022 standard’s PAIN.002.001.03 format. The output files provide information about the status of your transactions within Cross River’s (CR) banking core, such as whether the transactions were accepted or rejected.

Whereas legacy banks send you an acknowledgment file followed by a PSR later on, Cross River sends you the PSR immediately. Cross River achieves this by having Unicorn deliver your payment instructions to Cross River's API-based core banking system.

For more information on status and error codes, see here.

Output file naming convention

The output file PSRs conform to the following naming convention:

{InputFileName}.{date}.{time}-{number}

where "number" is the ordinal number of file from the specified date and time, and is used to differentiate among multiple possible files that were generated at that date and time. If only one file was generated at that date and time, the value of "number" will be "1".

How an output file is built

The root element in the Output file is CstmrPmtStsRpt (Customer Payment Status Report) and it contains the following 3 building blocks:

• GrpHdr that contains the file metadata.

• OrgnlGrpInfAndSts contains message identifiers based on the original input file and includes a status for the group.

• OrgnlPmtInfAndSts contains elements referencing the original transactions. This is an optional section that may appear multiple times in the file. It can contain an individual status for the original instruction, as well as elements from your original transaction file.

Here’s an example of the file structure:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<Document xmlns='urn:iso:std:iso:20022:tech:xsd:pain.002.001.03' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'>
  <CstmrPmtStsRpt>
    <GrpHdr>
      ...
    </GrpHdr>
    <OrgnlGrpInfAndSts>
      ...
    </OrgnlGrpInfAndSts>
    <OrgnlPmtInfAndSts>
      ...
      <TxInfAndSts>
        ...
      </TxInfAndSts>
    </OrgnlPmtInfAndSts>
  </CstmrPmtStsRpt>
</Document>

The Group Header

The GrpHdr block is a set of characteristics shared by all individual transactions included in the message. This building block is present once per output file. The group header includes the following elements:

1
2
3
4
5
6
7
<GrpHdr>
  <MsgId>11000000000a0a0</MsgId>
  <CreDtTm>2016-05-10T15:20:06.719Z</CreDtTm>
  <InitgPty>
    ...
  </InitgPty>
</GrpHdr>

• MsgId: Message ID. A unique ID that Unicorn generates for the file. It is unique per instructed party for a pre-agreed period. Best practice: Use a new for each file.**

• CreDtTm: Created Date and Time. This is the date and time at which the output file was created by Unicorn.

• InitgPty: Initiating Party. This element is used to indicate the party that initiated the file. With the output files this will always be CR. The InitgPty block appears as follows:

1
2
3
4
5
<InitgPty>
  <Nm>John Doe Corporation</Nm>
  <Id><OrgId> <BICOrBEI>JOHNDOE99</BICOrBEI>
  </OrgId></Id>
</InitgPty>

• Nm: Name used to identify the initiating party.

• Id: The unique identifier for 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.

Original Group Information And Status

Various information can be included for the group in the OrgnlGrpInfAndSts block. The information included will depend on the input file and the status of the original transaction.

• OrgnlMsgId is the message identification number from the original input file.

• OrgnlMsgNmId indicates the original message type, and will either be pain.001.001.03 for payments (USD) or pain.008.001.02 for direct debits (USD).

• OrgnlNbOfTxs shows the number of transactions in the original input file.

• OrgnlCtrlSum displays the control sum from the original input file.

• GrpSts indicates the status for a group of transactions. See here for details about the different statuses.

• AddtlInf shows details for the status in the case of a rejected file. The rejection reason can be due to an issue with the original XML file, as well as an issue arising during internal processing by CR.

The original transaction file was accepted

The following example of the OrgnlGrpInfAndSts block shows that the original input transaction file was accepted. You can see this in the GrpSts element, where "ACTC" indicates the file was accepted.

1
2
3
4
5
6
7
<OrgnlGrpInfAndSts>
    <OrgnlMsgId>ABCDEFG090301</OrgnlMsgId>
    <OrgnlMsgNmId>pain.001.001.03</OrgnlMsgNmId>
    <OrgnlNbOfTxs>1</OrgnlNbOfTxs>
    <OrgnlCtrlSum>42720.80</OrgnlCtrlSum>
    <GrpSts>ACTC</GrpSts>
</OrgnlGrpInfAndSts>

The original transaction file was rejected

The following example of the OrgnlGrpInfAndSts block shows that the original input transaction file was rejected. You can see this in the GrpSts element, where "RJCT" indicates the file was rejected. In this case, the output file will include the StsRsnInf element, which gives information about why the initial transaction was rejected. The reason will always be shown in the AddtlInf element.

In this example, the reason the file was rejected is shown as “Number of transactions in file does not match with control record:
Expected 1, but calculated 2”. This means that there is a mismatch between the OrgnlCtrlSum provided in the original file and the actual number of transactions provided there.

1
2
3
4
5
6
7
8
9
10
11
12
<OrgnlGrpInfAndSts>
  <OrgnlMsgId>ABCDEFG090301</OrgnlMsgId>
  <OrgnlMsgNmId>pain.001.001.03</OrgnlMsgNmId>
  <OrgnlCreDtTm>2015-08-10T10:48:47</OrgnlCreDtTm>
  <GrpSts>RJCT</GrpSts>
  <StsRsnInf>
    <Rsn>
      <Cd>NARR</Cd>
    </Rsn>
    <AddtlInf>Number of transactions in file does not match with control record: Expected 1, but calculated 2</AddtlInf>
  </StsRsnInf>
</OrgnlGrpInfAndSts>

Original Payment Information And Status

OrgnlPmtInfAndSts is a third and optional block, which contains elements referencing the original transactions. It corresponds to the batch level in the original file (specifically the PmtInf block), and can also include individual statuses for the original instructions.

1
2
3
4
5
6
7
8
9
<OrgnlPmtInfAndSts>
      <OrgnlPmtInfId>ABCDEFG00065</OrgnlPmtInfId>
      <OrgnlNbOfTxs>1</OrgnlNbOfTxs>
      <OrgnlCtrlSum>42720.80</OrgnlCtrlSum>
      <PmtInfSts>ACTC</PmtInfSts>
      <TxInfAndSts>
        ...
      </TxInfAndSts>
    </OrgnlPmtInfAndSts>

• OrgnlPmtInfId is a unique identifier, assigned by the original initiating party. It’s used to identify the original payment information block within the output file.

• OrgnlNbOfTxs indicates the number of payments in the original payment information block.

• OrgnlCtrlSum shows the sum total of all transactions included in the original payment information block.

• PmtInfSts indicates the status of the payment information block as follows:

Transaction-level information

The output file can include information about individual instructions in the original file in a building block called TxInfAndSts. This will be included as part of the OrgnlPmtInfAndSts building block. The transaction-level information includes the following:

• OrgnlInstrId contains the value of the Instruction Identification (InstrId) element provided in the input file. This element won’t be present if an InstrId value wasn’t provided in the input file.

• OrgnlEndToEndId contains the value of the EndtoEndId element provided in the input file.

• TxSts indicates the transaction status using one of the following codes:

In addition, the TxInfAndSts block contains the following elements:

• OrgnlTxRef: Contains information on the original transaction in its child elements, such as the transaction amount and the transaction's requested execution date.

• Amt: Contains the amount of the original transaction in a child element.

• InstdAmt: Contains the amount of the original transaction in the indicated currency.

• ReqdExtnDt: Requested Execution Date. The date on which the originator's account was to be debited.

If the status is shown as RJCT (rejected) an additional element, StsRsnInf, will be included in the TxInfAndSts block. This will provide information on why the transaction was rejected.

Here’s an example of the TxInfAndSts building block for when a transaction has succeeded:

1
2
3
4
5
6
7
8
9
10
11
<TxInfAndSts>
        <OrgnlInstrId>abcdefg000000</OrgnlInstrId>
        <OrgnlEndToEndId>0000000000001011</OrgnlEndToEndId>
        <TxSts>ACSC</TxSts>
        <OrgnlTxRef>
          <Amt>
            <InstdAmt Ccy="USD">42720.80</InstdAmt>
          </Amt>
          <ReqdExctnDt>2016-05-10</ReqdExctnDt>
        </OrgnlTxRef>
</TxInfAndSts>

Below is an example the TXInfAndSts building block for when a transaction has been rejected:

1
2
3
4
5
6
7
8
9
10
11
<TxInfAndSts>
        <OrgnlInstrId>abcdefg000000</OrgnlInstrId>
        <OrgnlEndToEndId>0000000000001011</OrgnlEndToEndId>
        <TxSts>RJCT</TxSts>
            <StsRsnInf>
            <Rsn>
                <Cd>NARR</Cd>
            </Rsn>
            <AddtlInf>The account 1234567890 is not setup in Unicorn for Client {clientID}. Please reach out to the Client Integration team.</AddtlInf>
            </StsRsnInf>
</TxInfAndSts>

The StsRsnInf block, which appears inside the TxInfAndSts block in the case of a rejected transaction, contains information on why the transaction was rejected, and contains the following elements:

• Rsn: Contains the reason code in a child element.

• Cd: Code. Currently, this code will always have the value of NARR, standing for "Narrative". The actual narrative text appears in the AddtlInf element.

• AddtlInf: Shows details for the status in the case of a rejected file. The rejection reason can be due to an issue with the original XML file, as well as an issue arising during internal processing by CR.

Full sample output files

Sample output files (successful transaction)

The examples below shows full output files generated when Unicorn has successfully processed the transaction file, for both the pain.001.001.03 and pain.008.001.002 formats. These examples include the Group Header, Original Information And Status, and Original Payment Information And Status blocks.

Output example from pain.001.001.03 input file (successful transaction)

The following is an example output file corresponding to a pain.001.001.03 input file, generated when the processing of the transaction file has succeeded.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<Document Xmlns="urn:iso:std:iso:20022:tech:xsd:pain.002.001.03" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <CstmrPmtStsRpt>
    <GrpHdr>
      <MsgId>abcdefg0000000</MsgId>
      <CreDtTm>2020-09-15T15:58:04.637Z</CreDtTm>
      <InitgPty>
        <Nm>John Doe Corporation</Nm>
        <Id>
          <OrgId>
            <BICOrBEI>JOHNDOE99</BICOrBEI>
          </OrgId>
        </Id>
      </InitgPty>
    </GrpHdr>
    <OrgnlGrpInfAndSts>
      <OrgnlMsgId>AMBCD10000000</OrgnlMsgId>
      <OrgnlMsgNmId>pain.001.001.03</OrgnlMsgNmId>
      <OrgnlNbOfTxs>3</OrgnlNbOfTxs>
      <OrgnlCtrlSum>5.0100</OrgnlCtrlSum>
      <GrpSts>ACTC</GrpSts>
    </OrgnlGrpInfAndSts>
    <OrgnlPmtInfAndSts>
      <OrgnlPmtInfId>ABCD10000000</OrgnlPmtInfId>
      <OrgnlNbOfTxs>3</OrgnlNbOfTxs>
      <OrgnlCtrlSum>5.0100</OrgnlCtrlSum>
      <PmtInfSts>ACTC</PmtInfSts>
      <TxInfAndSts>
        <OrgnlInstrId>100ABCD012345</OrgnlInstrId>
        <OrgnlEndToEndId>0000000000000108</OrgnlEndToEndId>
        <ClrSysRef>46456456</ClrSysRef>
        <TxSts>ACSP</TxSts>
      </TxInfAndSts>
    </OrgnlPmtInfAndSts>
  </CstmrPmtStsRpt>
</Document>

Output example from pain.008.001.02 input file (successful transaction)

The following is an example output file corresponding to a pain.008.001.02 input file, generated when the processing of the transaction file has succeeded.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<Document Xmlns="urn:iso:std:iso:20022:tech:xsd:pain.002.001.03" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <CstmrPmtStsRpt>
    <GrpHdr>
      <MsgId>abcdefg0123456789</MsgId>
      <CreDtTm>2020-11-02T11:30:11.055Z</CreDtTm>
      <InitgPty>
        <Nm>John Doe Corporation</Nm>
        <Id>
          <OrgId>
            <BICOrBEI>JOHNDOE99</BICOrBEI>
          </OrgId>
        </Id>
      </InitgPty>
    </GrpHdr>
    <OrgnlGrpInfAndSts>
      <OrgnlMsgId>DD1</OrgnlMsgId>
      <OrgnlMsgNmId>pain.008.001.02</OrgnlMsgNmId>
      <OrgnlNbOfTxs>3</OrgnlNbOfTxs>
      <OrgnlCtrlSum>6.0000</OrgnlCtrlSum>
      <GrpSts>ACTC</GrpSts>
    </OrgnlGrpInfAndSts>
    <OrgnlPmtInfAndSts>
      <OrgnlPmtInfId>DD1-1</OrgnlPmtInfId>
      <OrgnlNbOfTxs>3</OrgnlNbOfTxs>
      <OrgnlCtrlSum>6.0000</OrgnlCtrlSum>
      <PmtInfSts>ACTC</PmtInfSts>
      <TxInfAndSts>
        <OrgnlEndToEndId>DD1-1</OrgnlEndToEndId>
        <ClrSysRef>012345678901234</ClrSysRef>
        <TxSts>ACSP</TxSts>
      </TxInfAndSts>
      <TxInfAndSts>
        <OrgnlEndToEndId>DD1-2</OrgnlEndToEndId>
        <ClrSysRef>012345678901234</ClrSysRef>
        <TxSts>ACSP</TxSts>
      </TxInfAndSts>
      <TxInfAndSts>
        <OrgnlEndToEndId>DD1-3</OrgnlEndToEndId>
        <ClrSysRef>012345678901234</ClrSysRef>
        <TxSts>ACSP</TxSts>
      </TxInfAndSts>
    </OrgnlPmtInfAndSts>
  </CstmrPmtStsRpt>
</Document>

Sample output files (rejected transaction file)

The examples below show full output files generated when the transaction file has been rejected.

Rejected file (error on batch level)

The following example shows an output file generated when the transaction file has been rejected on the batch level, for an original file that came in pain.008.001.02 format.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<Document Xmlns="urn:iso:std:iso:20022:tech:xsd:pain.002.001.03" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <CstmrPmtStsRpt>
    <GrpHdr>
      <MsgId>abcdefg012345689</MsgId>
      <CreDtTm>2020-11-02T07:56:06.228Z</CreDtTm>
      <InitgPty>
        <Nm>John Doe Corporation</Nm>
        <Id>
          <OrgId>
            <BICOrBEI>JOHNDOE99</BICOrBEI>
          </OrgId>
        </Id>
      </InitgPty>
    </GrpHdr>
    <OrgnlGrpInfAndSts>
      <OrgnlMsgNmId>pain.008.001.02</OrgnlMsgNmId>
      <OrgnlNbOfTxs>0</OrgnlNbOfTxs>
      <OrgnlCtrlSum>0.0000</OrgnlCtrlSum>
      <GrpSts>RJCT</GrpSts>
      <StsRsnInf>
        <Rsn>
          <Cd>NARR</Cd>
        </Rsn>
        <AddtlInf><![CDATA[Error parsing file examplefile.xml: The 'MsgId' start tag on line 5 position 5 does not match the end tag of 'GrpHdr'. Line 19, position 5.]]></AddtlInf>
      </StsRsnInf>
    </OrgnlGrpInfAndSts>
  </CstmrPmtStsRpt>
</Document>

Rejected file (error on transaction level)

The following example shows an output file generated when the transaction file has been rejected on the transaction level, for an original file that came in pain.001.001.003 format.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<Document Xmlns="urn:iso:std:iso:20022:tech:xsd:pain.002.001.03" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <CstmrPmtStsRpt>
    <GrpHdr>
      <MsgId>abcdefg0123456789</MsgId>
      <CreDtTm>2020-10-26T11:49:33.620Z</CreDtTm>
      <InitgPty>
        <Nm>John Doe Corporation</Nm>
        <Id>
          <OrgId>
            <BICOrBEI>JOHNDOE99</BICOrBEI>
          </OrgId>
        </Id>
      </InitgPty>
    </GrpHdr>
    <OrgnlGrpInfAndSts>
      <OrgnlMsgId>missing2</OrgnlMsgId>
      <OrgnlMsgNmId>pain.001.001.03</OrgnlMsgNmId>
      <OrgnlNbOfTxs>3</OrgnlNbOfTxs>
      <OrgnlCtrlSum>5.0400</OrgnlCtrlSum>
      <GrpSts>ACTC</GrpSts>
    </OrgnlGrpInfAndSts>
    <OrgnlPmtInfAndSts>
      <OrgnlPmtInfId>missing2</OrgnlPmtInfId>
      <OrgnlNbOfTxs>3</OrgnlNbOfTxs>
      <OrgnlCtrlSum>5.0400</OrgnlCtrlSum>
      <PmtInfSts>RJCT</PmtInfSts>
      <TxInfAndSts>
        <OrgnlInstrId>example01234567</OrgnlInstrId>
        <OrgnlEndToEndId>sanity-10-1-12-1-21</OrgnlEndToEndId>
        <TxSts>RJCT</TxSts>
        <StsRsnInf>
          <Rsn>
            <Cd>NARR</Cd>
          </Rsn>
          <AddtlInf><![CDATA[Instruction ID example01234567 already exist]]></AddtlInf>
        </StsRsnInf>
      </TxInfAndSts>
      <TxInfAndSts>
        <OrgnlInstrId>example01234567</OrgnlInstrId>
        <OrgnlEndToEndId>example01234567</OrgnlEndToEndId>
        <TxSts>RJCT</TxSts>
        <StsRsnInf>
          <Rsn>
            <Cd>NARR</Cd>
          </Rsn>
          <AddtlInf><![CDATA[Instruction ID example01234567 already exist]]></AddtlInf>
        </StsRsnInf>
      </TxInfAndSts>
      <TxInfAndSts>
        <OrgnlInstrId>example012345678</OrgnlInstrId>
        <OrgnlEndToEndId>example012345678</OrgnlEndToEndId>
        <TxSts>RJCT</TxSts>
        <StsRsnInf>
          <Rsn>
            <Cd>NARR</Cd>
          </Rsn>
          <AddtlInf><![CDATA[Instruction ID example012345678 already exist]]></AddtlInf>
        </StsRsnInf>
      </TxInfAndSts>
    </OrgnlPmtInfAndSts>
  </CstmrPmtStsRpt>
</Document>