From 5a66c8d410b4a3ca10c7401ee024ead4841a0a55 Mon Sep 17 00:00:00 2001
From: dkoeni <116151702+dkoeni@users.noreply.github.com>
Date: Mon, 17 Aug 2026 13:08:09 +0000
Subject: [PATCH] Add optional numberOfTransactionsPerStatus breakdown to
 payment status responses

SPS 2026 changes the status condition for NbOfTxsPerSts from "not
defined" to "optional", so financial institutions can report how many
transactions were assigned each status. Add the same breakdown as an
optional array to PaymentSubmissionStatus and StandingOrderSubmissionStatus,
reusing the existing transaction-level status codes.

Closes #7 (status report part only, see PR description for scope)

Co-Authored-By: sfti-agent <257322368+sfti-agent@users.noreply.github.com>
---
 .../pss/NumberOfTransactionsPerStatus.yaml    | 33 +++++++++++++++++++
 .../schemas/pss/PaymentSubmissionStatus.yaml  |  7 ++++
 .../pss/StandingOrderSubmissionStatus.yaml    |  7 ++++
 3 files changed, 47 insertions(+)
 create mode 100644 src/components/schemas/pss/NumberOfTransactionsPerStatus.yaml

diff --git a/src/components/schemas/pss/NumberOfTransactionsPerStatus.yaml b/src/components/schemas/pss/NumberOfTransactionsPerStatus.yaml
new file mode 100644
index 0000000..e603677
--- /dev/null
+++ b/src/components/schemas/pss/NumberOfTransactionsPerStatus.yaml
@@ -0,0 +1,33 @@
+title: Number of Transactions per Status
+description: |
+  A breakdown of how many of the underlying transactions were assigned a given status. Corresponds to the attribute
+  _NbOfTxsPerSts_ in SPS/ISO-20022.
+type: object
+required:
+  - statusCode
+  - numberOfTransactions
+properties:
+  statusCode:
+    type: string
+    description: |
+      The transaction status this count refers to. Corresponds to the attribute _NbOfTxsPerSts ⇾ DtldSts_ in SPS/ISO-20022.
+      Possible status values are:
+      - ACCC (accepted settlement completed, credit to the creditor account)
+      - ACCP (accepted)
+      - ACSC (accepted settlement completed, debit to the debtor account)
+      - ACWC (accepted with change)
+      - RJCT (rejected)
+    enum:
+      - ACCC
+      - ACCP
+      - ACSC
+      - ACWC
+      - RJCT
+    example: ACSC
+  numberOfTransactions:
+    type: integer
+    minimum: 0
+    description: |
+      The number of transactions that were assigned the given status. Corresponds to the attribute
+      _NbOfTxsPerSts ⇾ DtldNbOfTxs_ in SPS/ISO-20022.
+    example: 3
diff --git a/src/components/schemas/pss/PaymentSubmissionStatus.yaml b/src/components/schemas/pss/PaymentSubmissionStatus.yaml
index b64da03..7a1c935 100644
--- a/src/components/schemas/pss/PaymentSubmissionStatus.yaml
+++ b/src/components/schemas/pss/PaymentSubmissionStatus.yaml
@@ -33,6 +33,13 @@ properties:
   messageId:
     description: The unique identifier of the payment instruction message.
     $ref: ./MessageId.yaml
+  numberOfTransactionsPerStatus:
+    type: array
+    description: |
+      An optional breakdown of the number of transactions per status, if provided by the financial institution.
+      Corresponds to the attribute _NbOfTxsPerSts_ in SPS/ISO-20022.
+    items:
+      $ref: ./NumberOfTransactionsPerStatus.yaml
   transactions:
     type: array
     description: The payment transaction items.
diff --git a/src/components/schemas/pss/StandingOrderSubmissionStatus.yaml b/src/components/schemas/pss/StandingOrderSubmissionStatus.yaml
index eb49db7..c91e901 100644
--- a/src/components/schemas/pss/StandingOrderSubmissionStatus.yaml
+++ b/src/components/schemas/pss/StandingOrderSubmissionStatus.yaml
@@ -19,6 +19,13 @@ properties:
   messageId:
     # description: The unique identifier of the the standing order instruction message.
     $ref: ./MessageId.yaml
+  numberOfTransactionsPerStatus:
+    type: array
+    description: |
+      An optional breakdown of the number of transactions per status, if provided by the financial institution.
+      Corresponds to the attribute _NbOfTxsPerSts_ in SPS/ISO-20022.
+    items:
+      $ref: ./NumberOfTransactionsPerStatus.yaml
   transactions:
     type: array
     description: The standing order transaction items.