pacs.002.001.10 XSD schema and business logic

A pacs.002.001.10 is a Financial Institution to Financial Institution Payment Status Report (PSR) messages.

When it concerns a payment pacs.008 , pacs.003 or pacs.004 message, PSRs provide an update of the payment status at a point of time during its processing.

Note that a given payment can have one or multiple pacs.002.001.10 messages. In case of multiple pacs.002.001.10 messages, they must be ordered to respect the lifecycle of a payment (see Payment order lifecycle and Return lifecycle). For instance, a payment order cannot be executed after it has been rejected.

The definitions and business rules below are applied by Mambu Payments. Your application should send pacs.002.001.10 complying with these definitions in business rules.

1. Message definition and structure

1.1. Usage

pacs.008  →  [FI to FI Customer Credit Transfer]
                       ↓
pacs.002  ←  [FI to FI Payment Status Update]

pacs.004  →  [Payment return]
                       ↓
pacs.002  ←  [FI to FI Payment Status Update]

pacs.003  →  [FI to FI Customer Direct Debit]
                       ↓
pacs.002  ←  [FI to FI Payment Status Update]

1.2. XSD definition and structure

The pacs.002.001.10 message definition and structure is available here.

The simplified structure is shown below:

Document
└── FIToFIPmtStsRpt                         ← Root: FI To FI Payment Status Report
    ├── GrpHdr         [1..1]               ← Group Header (mandatory)
    │   ├── MsgId                           ← Message ID, text 1..35
    │   ├── CreDtTm                         ← Creation date/time, ISODateTime
    │   └── InstgAgt   [0..1]               ← Instructing Agent (optional)
    │       └── FinInstnId
    │           └── BICFI                   ← BIC of instructing agent
    ├── OrgnlGrpInfAndSts [1..1]            ← Original Group Information and Status (mandatory)
    │   ├── OrgnlMsgId                      ← Original message ID, text 1..35
    │   ├── OrgnlMsgNmId                    ← Original message name, e.g. pacs.008
    │   ├── GrpSts     [0..1]               ← Group-level status (optional)
    │   │   ├── RCVD                        ← Received — not yet accepted or processed
    │   │   ├── ACTC                        ← Accepted: technical validation
    │   │   ├── ACCP                        ← Accepted: customer profile
    │   │   ├── ACWC                        ← Accepted: with change
    │   │   ├── ACSP                        ← Accepted: settlement in progress
    │   │   ├── ACSC                        ← Accepted: settlement completed
    │   │   ├── PDNG                        ← Pending
    │   │   ├── PART                        ← Partially accepted
    │   │   └── RJCT                        ← Rejected (reason mandatory if RJCT)
    │   └── StsRsnInf  [0..n]               ← Status Reason Information (mandatory if RJCT)
    │       ├── Orgtr  [0..1]               ← Originator of the status reason
    │       │   └── Nm                      ← Name
    │       └── Rsn    [0..1]               ← Reason (Cd XOR Prtry)
    │           ├── Cd                      ← ISO ExternalStatusReason1Code
    │           └── Prtry                   ← Proprietary reason code, text 1..35
    └── TxInfAndSts    [0..n]               ← Transaction Information and Status (0 or more)
        │                                     ⚠ At least 1 required if GrpSts = PART
        ├── StsId      [0..1]               ← Status identification (optional)
        ├── OrgnlInstrId    [0..1]          ← Original Instruction ID (optional)
        ├── OrgnlEndToEndId [0..1]          ← Original End-to-end ID (optional)
        ├── OrgnlTxId       [0..1]          ← Original Transaction ID (optional)
        ├── OrgnlUETR       [0..1]          ← Original UETR, UUID v4 (optional)
        │                                     ℹ All four above used by Mambu Payments
        │                                       to identify the original payment —
        │                                       see priority lookup table (§3.1.1)
        ├── TxSts      [0..1]               ← Transaction-level status (optional)
        │   ├── RCVD                        ← Received — pacs.008 only
        │   ├── ACCP                        ← Accepted — pacs.008, pacs.004, pacs.003
        │   ├── ACSP                        ← Accepted: settlement in progress — pacs.008
        │   ├── ACSC                        ← Accepted: settlement completed — pacs.008
        │   ├── PDNG                        ← Pending — pacs.008 only
        │   └── RJCT                        ← Rejected — pacs.008, pacs.004, pacs.003
        │                                       (reason mandatory if RJCT)
        └── StsRsnInf  [0..n]               ← Status Reason Information (mandatory if RJCT)
            ├── Orgtr  [0..1]               ← Originator of the status reason
            │   └── Nm                      ← Name
            └── Rsn    [0..1]               ← Reason (Cd XOR Prtry)
                ├── Cd                      ← ISO ExternalStatusReason1Code
                │                             e.g. AB05..AB10 (instant payment timeouts)
                │                                 AC01, AC04, AC06 (account errors)
                │                                 AM02, AM04, AM05 (amount errors)
                │                                 MD01, MD02 (mandate errors)
                │                                 RR01..RR04 (regulatory)
                │                                 TECH, FRAD, FF01…
                └── Prtry                   ← Proprietary reason code, text 1..35

2. Business logic

2.1. Original Group Information and Status

2.1.1. Original message

The original message that a pacs.002.001.10 refers to is given by the Original Group Information and Status tag:

<FIToFIPmtStsRpt>
  <!-- ... -->
  <OrgnlGrpInfAndSts>
    <OrgnlMsgId>originalMsgId</OrgnlMsgId> <!-- Original message id -->
    <OrgnlMsgNmId>pacs.008</OrgnlMsgNmId> <!-- Original message name id -->
  </OrgnlGrpInfAndSts>
  <!-- ... -->
</FIToFIPmtStsRpt>

2.1.2. Group status

The Group Status is located under the Original Group Information and Status tag OrgnlGrpInfAndSts.GrpSts. Accepted values are the following:

Status code	Status name	Definition
`RCVD`	Received	The related payment message has been received by the instructed agent. It has not yet been accepted or processed.
`ACTC` `ACCP` `ACWC` `ACSP` `ACSC`	Accepted	The related payment message has been accepted by the instructed agent. The following list is allowed: `ACTC`: accepted technical validation `ACCP`: accepted customer profile `ACWC`: accepted with change `ACSP`: accepted settlement in progress `ACSC`: accepted settlement completed
`RJCT`	Rejected	All payments in the group have been rejected by the instructed agent.
`PDNG`	Pending	All payments in the group are pending at the instructed agent side.
`PART`	Partially accepted	Some payments have been accepted and others have been rejected. Payments rejected are included at the transaction level.

If the group status is rejected, the reason of the rejection must be provided, either as an official ISO 20022 ExternalStatusReason1Code, or a proprietary code. Mambu Payments will not interpret the reason code passed by the user.

The XML snippets below show a few examples of group status:

<FIToFIPmtStsRpt>
  <!-- ... -->
  <OrgnlGrpInfAndSts>
    <GrpSts>ACCP</GrpSts>
  </OrgnlGrpInfAndSts>
  <!-- ... -->
</FIToFIPmtStsRpt>

<FIToFIPmtStsRpt>
  <!-- ... -->
  <OrgnlGrpInfAndSts>
    <GrpSts>RJCT</GrpSts>
    <StsRsnInf>
      <Rsn> <!-- one of: code Cd or proprietary Prtry -->
        <Cd></Cd>  <!-- e.g. RR04: regulatory reason -->
        <Prtry></Prtry>
      </Rsn>
    </StsRsnInf>
  </OrgnlGrpInfAndSts>
  <!-- ... -->
</FIToFIPmtStsRpt>

<FIToFIPmtStsRpt>
  <!-- ... -->
  <OrgnlGrpInfAndSts>
    <GrpSts>PDNG</GrpSts>
  </OrgnlGrpInfAndSts>
  <!-- ... -->
</FIToFIPmtStsRpt>

2.2. Transaction information and status

There can be 0 to N occurrences of transaction in a PSR message, unless the Group Status is PART, in which case there must be at least one occurrence.

ℹ️
The ISO 20022 language commonly refers to a transaction which corresponds to a payment in Mambu Payments.

2.2.1. Original Transaction information

The original payment identifiers are provided below. Note that all these fields are optional

<FIToFIPmtStsRpt>
  <!-- ... -->
  <TxInfAndSts>
    <OrgnlInstrId></OrgnlInstrId> <!-- original payment instruction id -->
    <OrgnlEndToEndId></OrgnlEndToEndId> <!-- original payment end to end id -->
    <OrgnlTxId></OrgnlTxId> <!-- original payment transaction id -->
    <OrgnlUETR></OrgnlUETR> <!-- original payment UETR -->
  </TxInfAndSts>
</FIToFIPmtStsRpt>

2.2.2. Transaction statuses

When applicable, individual payments are included in the Transaction Information and Status tag TxInfAndSts.TxSts. Accepted values are the following:

Status code	Status name	Definition	Applicable to
`RCVD`	Received	The payment has been received	pacs.008
`ACCP`	Accepted	The payment has been processed by the instructed agent.	pacs.008, pacs.004, pacs.003
`ACSP`	Accepted, settlement in progress	The payment has been processed by the instructed agent and is undergoing clearing and settlement.	pacs.008
`ACSC`	Accepted, settlement completed	The payment has been processed, cleared, and settled by the instructed agent.	pacs.008
`PDNG`	Pending	The payment has been put on hold and is waiting verification (e.g., compliance checks) and validation by the instructed agent.	pacs.008
`RJCT`	Rejected	The message has been rejected by the instructed agent.	pacs.008, pacs.004, pacs.003

If the transaction status is rejected, the reason of the rejection must be provided, either as an official ISO 20022 ExternalStatusReason1Code, or a proprietary code. Mambu Payments will not interpret the reason code passed by the user.

The XML snippets below show a few examples of transaction status:

<FIToFIPmtStsRpt>
  <!-- ... -->
  <TxInfAndSts>
    <OrgnlInstrId></OrgnlInstrId> <!-- original payment instruction id -->
    <OrgnlEndToEndId></OrgnlEndToEndId> <!-- original payment end to end id -->
    <OrgnlTxId></OrgnlTxId> <!-- original payment transaction id -->
    <OrgnlUETR></OrgnlUETR> <!-- original payment UETR -->
    <TxSts>ACCP</TxSts>
  </TxInfAndSts>
</FIToFIPmtStsRpt>

<FIToFIPmtStsRpt>
  <!-- ... -->
  <TxInfAndSts>
    <OrgnlInstrId></OrgnlInstrId> <!-- original payment instruction id -->
    <OrgnlEndToEndId></OrgnlEndToEndId> <!-- original payment end to end id -->
    <OrgnlTxId></OrgnlTxId> <!-- original payment transaction id -->
    <OrgnlUETR></OrgnlUETR> <!-- original payment UETR -->
    <TxSts>RJCT</TxSts>
    <StsRsnInf>
      <Rsn> <!-- one of: code Cd or proprietary Prtry -->
        <Cd></Cd>  <!-- e.g. RR04: regulatory reason -->
        <Prtry></Prtry>
      </Rsn>
    </StsRsnInf>
  </TxInfAndSts>
</FIToFIPmtStsRpt>

3. Mambu Payments Business rules

3.1 Rules for incoming PSR

3.1.1 Identification of original payment

Mambu Payments will try to identify an original payment based on the following table in order of priority:

Priority level	Combination
1	`OrgnlMsgId` and `OrgnlTxId` `OrgnlMsgId` and `OrgnlUETR`
2	`OrgnlMsgId` and `OrgnlEndToEndId`
3	`OrgnlMsgId` and `OrgnlInstrId`
4	`OrgnlTxId` or `OrgnlUETR`
5	`OrgnlEndToEndId`
6	`OrgnlInstrId`
7	`OrgnlMsgId` only if `TxInfAndSts` is absent

If no original payment can be found, then the transaction occurrence in the PSR will be discarded.

3.1.2. Status priority processing

Mambu Payments will evaluate the status of a payment in this order:

Priority level Description

Priority level	Description
1	Evaluate individual payment status first if present If `TxInfAndSts` tag is present at least once, then the status of the individual payment referenced by `TxInfAndSts` is updated as follows : `RJCT`: the individual payment is `rejected` `PDNG`: the individual payment is `pending` `Axxx`: depending on the payment scheme, the `Axxx` status will be considered as accepted (no payment status change) or `executed`
2	Evaluate payment group status next If `TxInfAndSts` tag is present at least once, then the status of the group of payments referenced by `GrpInfAndSts` tag are updated as follows: `RJCT` or `ACCP`: ignored as it has already been handled at transaction level `RCVD`: not expected `PART`: all remaining payments in the group that were not explicitly mentioned are `executed`
3	If there is no individual payment status level If `TxInfAndSts` tag is absent, then the status of the group of payments referenced by `GrpInfAndSts` tag are updated as follows: `RJCT`: all payments in the group are `rejected` `RCVD`: ignored `Axxx`: depending on the payment scheme, the `Axxx` status will be considered as accepted (no payment status change) or `executed` `PART`: should not happen as transaction level detail is expected

Evaluate individual payment status first if present

If TxInfAndSts tag is present at least once, then the status of the individual payment referenced by TxInfAndSts is updated as follows :

RJCT: the individual payment is rejected
PDNG: the individual payment is pending
Axxx: depending on the payment scheme, the Axxx status will be considered as accepted (no payment status change) or executed

Evaluate payment group status next

If TxInfAndSts tag is present at least once, then the status of the group of payments referenced by GrpInfAndSts tag are updated as follows:

RJCT or ACCP: ignored as it has already been handled at transaction level
RCVD: not expected
PART: all remaining payments in the group that were not explicitly mentioned are executed

If there is no individual payment status level

If TxInfAndSts tag is absent, then the status of the group of payments referenced by GrpInfAndSts tag are updated as follows:

RJCT: all payments in the group are rejected
RCVD: ignored
Axxx: depending on the payment scheme, the Axxx status will be considered as accepted (no payment status change) or executed
PART: should not happen as transaction level detail is expected

3.1.3 Outgoing payment status lifecycle

The lifecycle below is a snapshot of the complete lifecycle available at: https://docs.numeral.io/reference/payment-order-lifecycle that focuses on the PSR statuses:

stateDiagram-v2

[*] --> sent
sent --> sent: if RCVD or accepted Axxx status
sent --> pending: if PDNG
sent --> rejected: if RJCT
pending --> executed: if executed Axxx status
pending --> rejected: if RJCT
sent --> executed: if executed Axxx status
executed --> rejected: if RJCT

3.2 Rules for outgoing PSR

3.2.1 When does Mambu Payments send an outgoing PSR

Situation	Send outgoing PSR	Comment
When receiving a credit transfer or RTGS payment `pacs.008`	No	In case of acceptance, no message is sent In case of "rejection", a return should be performed instead
When receiving an instant payment `pacs.008`	Yes	Mambu Payments will send a PSR to notify the acceptance or rejection of the instant payment
When receiving a direct debit collection `pacs.003`	depends	In case of acceptance, no message is sent In case of rejection, a reject `pacs.002` can be issued before the settlement date
When receiving a return `pacs.004`	No	A return cannot be accepted or rejected

3.2.2 Outgoing PSR structure

Original payment identification

Mambu Payments will put any identification data received on the original payment message

PSR statuses

Mambu Payments will only send ACCP or RJCT status to notify the acceptance or rejection of a payment message. In case of rejection, the user needs to provide a rejection reason code among the list defined below.

3.2.3 Rejection reason codes

The authorized list of rejection reason codes is provided below. It is the user's responsibility to translate this reason code to the one expected by the scheme

Code	Description	Definition	Applicable operations
`AB05`	Timeout creditor agent	Transaction stopped due to timeout at the creditor agent	Instant payment only
`AB06`	Timeout instructed agent	Transaction stopped due to timeout at the instructed agent	Instant payment only
`AB07`	Offline agent	Agent of message is not online. Generic usage if it cannot be determined which agent is not online	Instant payment only
`AB08`	Offline creditor agent	Creditor agent is not online	Instant payment only
`AB09`	Error creditor agent	Transaction stopped due to error at the creditor agent	Instant payment only
`AB10`	Error instructed agent	Transaction stopped due to error at the instructed agent	Instant payment only
`AC01`	Incorrect account number	Account identifier invalid or incorrect	Instant payment Direct debit
`AC04`	Closed account number	Account closed	Instant payment Direct debit
`AC06`	Blocked account	Account blocked	Direct debit
`AG01`	Transaction forbidden	Operation forbidden on this account	Instant payment Direct debit
`AG02`	Invalid bank operation code	Operation code / transaction code incorrect or invalid file format	Instant payment Direct debit
`AM02`	Not allowed amount	Amount exceeds the maximum authorized amount	Instant payment Direct debit
`AM04`	Insufficient funds	Insufficient funds on the account	Direct debit
`AM05`	Duplication	Duplicate payment	Direct debit
`BE04`	Missing creditor address	Account address invalid	Instant payment Direct debit
`CNOR`	Creditor bank is not registered	Beneficiary PSP is not registered in the CSM	Instant payment Direct debit
`DNOR`	Debtor bank is not registered	Originator PSP is not registered	Instant payment Direct debit
`FF01`	Invalid file format	Operation / transaction code incorrect or invalid file format	Instant payment Direct debit
`FRAD`	Fraudulent origin	Fraudulent originated credit transfer	Instant payment
`MD01`	No mandate	No valid mandate	Direct debit
`MD02`	Missing mandatory mandate information	Mandate data missing or incorrect.	Direct debit
`MD07`	End customer deceased	Beneficiary deceased	Instant payment Direct debit
`MS02`	Not specified reason customer generated	By order of the beneficiary	Instant payment Direct debit
`MS03`	Not specified reason agent generated	Reason not specified	Instant payment Direct debit
`RC01`	Bank identifier incorrect	PSP identifier incorrect (i.e., invalid BIC)	Instant payment Direct debit
`RR01`	Missing debtor account or identification	Regulatory reason	Instant payment Direct debit
`RR02`	Missing debtor name or address	Regulatory reason	Instant payment Direct debit
`RR03`	Missing creditor name or address	Regulatory reason	Instant payment Direct debit
`RR04`	Regulatory reason	Regulatory reason	Instant payment Direct debit
`TECH`	Technical problem	Technical problems resulting in erroneous payments	Instant payment Direct debit