docs(webhook): restructure PaymentInstructionEvent status payload

apis/fx-webhook/openapi.yml

@@ -557,7 +557,7 @@ components:
         - PHONE
         - EVP
       description: PIX key flavour.
-    PaymentInstructionEventStatus:
+    PaymentInstructionStatus:
       type: string
       enum:
         - PENDING_REVIEW
@@ -828,16 +828,34 @@ components:
           readOnly: true
         asset:
           $ref: "#/components/schemas/Asset"
-        status:
-          $ref: "#/components/schemas/PaymentInstructionEventStatus"
-          readOnly: true
+        currentState:
+          $ref: "#/components/schemas/PaymentInstructionState"
+          description: Status the payment instruction is in at the time the event fires. `reason` is populated only on `REJECTED`.
         address:
           $ref: "#/components/schemas/FinancialAddressEvent"
       required:
         - id
         - asset
-        - status
+        - currentState
         - address
+    PaymentInstructionState:
+      type: object
+      description: A single entry in a payment instruction's review history. Carries a status, optional reason, and the time the state was entered.
+      properties:
+        status:
+          $ref: "#/components/schemas/PaymentInstructionStatus"
+        reason:
+          allOf:
+            - $ref: "#/components/schemas/Reason"
+          nullable: true
+          description: Justification for entering this status. Present for `REJECTED`; `null` for `PENDING_REVIEW` and `APPROVED`.
+        createdAt:
+          type: string
+          format: date-time
+          description: Time the payment instruction entered this status.
+      required:
+        - status
+        - createdAt
     HolderReferenceEvent:
       type: object
       description: Snapshot of a beneficiary holder included in operation payloads.
@@ -1567,8 +1585,9 @@ webhooks:
       description: >
         Fires when one of the beneficiary's payment instructions is approved
         and becomes usable. The payload carries the approved `instruction`
-        (with `status: APPROVED`) plus the beneficiary context. A beneficiary
-        with multiple instructions emits this event once per approval.
+        (with `currentState.status: APPROVED`) plus the beneficiary context.
+        A beneficiary with multiple instructions emits this event once per
+        approval.
       tags:
         - Beneficiary
       requestBody:
@@ -1586,9 +1605,10 @@ webhooks:
       description: >
         Fires when one of the beneficiary's payment instructions is rejected
         in compliance review and cannot be used. The payload carries the
-        rejected `instruction` (with `status: REJECTED`) plus the beneficiary
-        context. A beneficiary with multiple instructions emits this event
-        once per rejection.
+        rejected `instruction` (with `currentState.status: REJECTED` and
+        `currentState.reason` describing why) plus the beneficiary context.
+        A beneficiary with multiple instructions emits this event once per
+        rejection.
       tags:
         - Beneficiary
       requestBody: