fix(reimbursement): introduce reimbursementbreakdown

Author: Sami Rmili

docs/reimbursement-breakdown.md

@@ -0,0 +1,56 @@
+# Reviewer note — #1369 reimbursement breakdown
+
+> **Temporary.** This file documents the diff for reviewers and will be **deleted
+> before merge**. It is not meant to ship.
+
+Issue [#1369](https://github.com/UnionInternationalCheminsdeFer/OSDM/issues/1369) ·
+branch `1369-reimbursement-breakdown` · **purely additive, non-breaking.**
+
+## Why
+
+A refund/exchange today can't say **how** money comes back to the passenger *with
+amounts*: `ReimbursementMethod.paymentMethod` is a single value (no split) and
+`issuedVouchers` carries issuer+code but **no amount**. So neither "€80 voucher +
+€40 to card" nor "several vouchers re-credited individually" is expressible.
+
+## What changed
+
+| File | Change |
+|---|---|
+| `schemas/aftersales.yml` | New `ReimbursementBreakdownItem` (`additionalProperties:false`; required `type` → `PaymentType`; optional `reimbursementAmount` → `Price`, `voucherInformation`). New `reimbursementBreakdown` array on `RefundOffer`, `ExchangeOperation`, `ExchangeOffer`. New `usedPaymentMethods` (array of `PaymentMethod`) on `ExchangeOperationPatchRequest`. |
+| `OSDM-online-api.yml` | Hub `$ref` for `ReimbursementBreakdownItem`. |
+
+Nothing is deprecated, renamed, or removed. `ReimbursementMethod`, `issuedVouchers`
+and `complaint.yml` are **untouched**.
+
+## Review notes
+
+- **`reimbursementBreakdown` = the realized per-channel split.** Per-item `type`
+  (one entry per channel) is what lets it express a mix; single-channel is a
+  one-element array.
+- **`reimbursementAmount` is optional on purpose.** It's authoritative for the
+  `VOUCHER` channel (system knows the credited amount, like `appliedVoucherAmount`
+  on `PaymentMethod`); for other channels it's declarative and may be omitted. So
+  "sum of items = total" holds only when every item carries an amount.
+- **No new voucher-issuance flag.** A voucher in `issuedVouchers` is newly issued;
+  one in the breakdown but not in `issuedVouchers` is a re-credit — membership
+  already encodes it. The breakdown's `voucherInformation` is just the key to
+  attach a per-voucher amount.
+- **`usedPaymentMethods` on the exchange PATCH** settles the exchange surcharge
+  (`ExchangeOffer.amountToBePaid`), mirroring `BookingPatchRequest`. The exchange
+  PATCH is idempotency-key protected, so payment is retry-safe.
+
+## Scope / out of scope
+
+Voucher consolidation (`issuedVoucherRefs`/`VoucherRef` already on `dev-osdm-v4`),
+target-instrument identity for non-voucher items, and first-class
+eligible-methods + customer choice (EU Reg 2021/782) are **deferred to the v4
+payment module** — not introduced here.
+
+Ships identically to **3.8, 3.9 and master** (three additive PRs).
+
+## Validation
+
+`redocly lint specification/OSDM-online-api.yml` — passes (only pre-existing
+`houseNumber` example warnings). Don't commit `OSDM-online-api.bundled.yml` (CI
+regenerates it).

specification/OSDM-online-api.yml

@@ -1037,6 +1037,8 @@ components:
       $ref: ./schemas/_common.yml#/RegulatoryCondition
     Reimbursement:
       $ref: ./schemas/complaint.yml#/Reimbursement
+    ReimbursementBreakdownItem:
+      $ref: ./schemas/aftersales.yml#/ReimbursementBreakdownItem
     ReimbursementDecision:
       $ref: ./schemas/complaint.yml#/ReimbursementDecision
     ReimbursementMethod:

specification/schemas/aftersales.yml

@@ -291,6 +291,15 @@ ExchangeOffer:
       type: array
       items:
         $ref: '#/ExchangeBreakdownItem'
+    reimbursementBreakdown:
+      description: |
+        Per-channel breakdown of the amount to be reimbursed to the purchaser
+        (the refundableAmount), supporting split reimbursements (e.g. part to a
+        voucher, part to the original payment mean). Lets the reimbursable split
+        be seen at quotation stage, before the exchange is confirmed.
+      type: array
+      items:
+        $ref: '#/ReimbursementBreakdownItem'
     admissionOfferParts:
       type: array
       items:
@@ -443,6 +452,15 @@ ExchangeOperation:
       type: array
       items:
         $ref: ./_common.yml#/VoucherInformation
+    reimbursementBreakdown:
+      description: |
+        Per-channel breakdown of the amount reimbursed to the purchaser,
+        supporting split reimbursements (e.g. part to a voucher, part to the
+        original payment mean). Each voucher channel carries its voucher
+        information and amount inline.
+      type: array
+      items:
+        $ref: '#/ReimbursementBreakdownItem'
     trips:
       type: array
       items:
@@ -461,6 +479,13 @@ ExchangeOperationPatchRequest:
       $ref: ./fulfillment.yml#/FulfillmentType
     preferredFulfillmentMedia:
       $ref: ./fulfillment.yml#/FulfillmentMediaType
+    usedPaymentMethods:
+      description: |
+        Payment methods used to settle the exchange surcharge (the
+        amountToBePaid of the selected exchange offer).
+      type: array
+      items:
+        $ref: ./_common.yml#/PaymentMethod
     embed:
       description: |
         Influences whether referenced resources are returned in full or as references only.
@@ -599,6 +624,17 @@ RefundOffer:
       type: array
       items:
         $ref: '#/RefundOfferBreakdownItem'
+    reimbursementBreakdown:
+      description: |
+        Per-channel breakdown of the amount reimbursed to the purchaser (the
+        refundableAmount), supporting split reimbursements (e.g. part to a
+        voucher, part to the original payment mean). Each voucher channel
+        carries its voucher information and amount inline. This is authoritative
+        for the realized per-channel amounts; reimbursementMethod only states
+        the offer's headline channel.
+      type: array
+      items:
+        $ref: '#/ReimbursementBreakdownItem'
     reimbursementMethod:
       $ref: ./complaint.yml#/ReimbursementMethod
     _links:
@@ -727,6 +763,38 @@ RefundType:
   - 'YES'
   - 'NO'
   - WITH_CONDITION
+ReimbursementBreakdownItem:
+  type: object
+  additionalProperties: false
+  description: |
+    One channel through which (part of) the reimbursable amount is returned to
+    the purchaser. A list of these expresses split reimbursements (e.g. part to
+    a voucher, part to the original payment mean), which the singular
+    reimbursementMethod cannot represent.
+  required:
+  - type
+  properties:
+    type:
+      $ref: ./_common.yml#/PaymentType
+    reimbursementAmount:
+      description: |
+        Amount returned to the purchaser through this channel. Authoritative for
+        the VOUCHER channel, where the system knows the credited amount (mirroring
+        appliedVoucherAmount on PaymentMethod). For other channels such as
+        ORIGINAL_ACCOUNT the amount is declarative and may be omitted when the
+        system cannot state it.
+      allOf:
+      - $ref: ./_common.yml#/Price
+    voucherInformation:
+      description: |
+        Identifies the voucher this amount is credited to when type is VOUCHER.
+        This is the per-voucher key that lets a specific amount be attached to a
+        specific voucher (which issuedVouchers cannot express). A voucher that
+        also appears in issuedVouchers is newly issued; one that appears here but
+        not in issuedVouchers is a re-credit of an existing voucher. Provided once
+        the voucher is known; not available at quotation stage.
+      allOf:
+      - $ref: ./_common.yml#/VoucherInformation
 ReleaseOffer:
   type: object
   additionalProperties: false