From 6a3e7ec9ef14161a6de79d362db02bc86df01e74 Mon Sep 17 00:00:00 2001
From: Diego Pereira <dpereira@trace.finance>
Date: Fri, 8 May 2026 10:34:18 -0300
Subject: [PATCH 1/2] docs(webhook): wrap PaymentInstructionEvent.status in
 currentState
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Match the SNS payload now emitted by fx-payment (PR #79) and align
with the State<T> wrapper already used by OperationEvent and
TransactionEvent — `currentState.status` plus `currentState.reason`
(populated on REJECTED) and `currentState.createdAt`.

The PaymentInstructionEventStatus enum is preserved as
PaymentInstructionState.status — no enum value changes.
---
 apis/fx-webhook/openapi.yml | 38 ++++++++++++++++++++++++++++---------
 1 file changed, 29 insertions(+), 9 deletions(-)

diff --git a/apis/fx-webhook/openapi.yml b/apis/fx-webhook/openapi.yml
index 04a7df9..0fe97e7 100644
--- a/apis/fx-webhook/openapi.yml
+++ b/apis/fx-webhook/openapi.yml
@@ -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/PaymentInstructionEventStatus"
+        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:

From 33b817bbb4c9c6eeb740d5c92eb7f17a20d796ed Mon Sep 17 00:00:00 2001
From: Diego Pereira <dpereira@trace.finance>
Date: Fri, 8 May 2026 10:47:51 -0300
Subject: [PATCH 2/2] docs(webhook): rename PaymentInstructionEventStatus to
 PaymentInstructionStatus

The `Event` suffix was an artifact of when this enum lived directly on `PaymentInstructionEvent.status`. Now that it sits inside `PaymentInstructionState.status`, the suffix no longer reflects the schema's role. Rename to match the surrounding `PaymentInstructionEvent` / `PaymentInstructionState` family.

Companion to the same rename in fx-payment.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 apis/fx-webhook/openapi.yml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/apis/fx-webhook/openapi.yml b/apis/fx-webhook/openapi.yml
index 0fe97e7..94c40a9 100644
--- a/apis/fx-webhook/openapi.yml
+++ b/apis/fx-webhook/openapi.yml
@@ -557,7 +557,7 @@ components:
         - PHONE
         - EVP
       description: PIX key flavour.
-    PaymentInstructionEventStatus:
+    PaymentInstructionStatus:
       type: string
       enum:
         - PENDING_REVIEW
@@ -843,7 +843,7 @@ components:
       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/PaymentInstructionEventStatus"
+          $ref: "#/components/schemas/PaymentInstructionStatus"
         reason:
           allOf:
             - $ref: "#/components/schemas/Reason"