feat!: add payments webhook endpoint and schema

BREAKING CHANGE: adds PAYMENT as a new eventCategory oneOf value in xero-webhooks.yaml. Existing strict schema validators may reject this new enum value in webhook payloads; this is expected since subscribers must explicitly opt in to payment events.

Author: gcxero

xero-webhooks.yaml

@@ -171,6 +171,60 @@ webhooks:
           $ref: "#/components/responses/200WebhookDataReceivedOk"
         "401":
           $ref: "#/components/responses/401InvalidWebhookData"
+  payments:
+    post:
+      summary: Payments Webhook Endpoint
+      description: Payment (Create, Update)
+      operationId: publishPaymentEvent
+      tags:
+        - Events
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/PaymentWebhookEvent"
+            examples:
+              paymentCreate:
+                summary: Payment Create Event
+                value:
+                  events:
+                    - resourceUrl: https://api.xero.com/api.xro/2.0/Payments/717f2bfc-c6d4-41fd-b238-3f2f0c0cf777
+                      resourceId: 717f2bfc-c6d4-41fd-b238-3f2f0c0cf777
+                      tenantId: c2cc9b6e-9458-4c7d-93cc-f02b81b0594f
+                      tenantType: ORGANISATION
+                      eventCategory: PAYMENT
+                      eventType: CREATE
+                      eventDateUtc: 2025-10-21T01:15:39.902
+                      data:
+                        PaymentType: ACCRECPAYMENT
+                        Status: AUTHORISED
+                        UpdatedDateUTCString: 2025-10-21T01:15:39Z
+                  firstEventSequence: 76
+                  lastEventSequence: 76
+                  entropy: FXNGWLCCGVANWHKILRUB
+              paymentUpdate:
+                summary: Payment Update Event
+                value:
+                  events:
+                    - resourceUrl: https://api.xero.com/api.xro/2.0/Payments/717f2bfc-c6d4-41fd-b238-3f2f0c0cf777
+                      resourceId: 717f2bfc-c6d4-41fd-b238-3f2f0c0cf777
+                      tenantId: c2cc9b6e-9458-4c7d-93cc-f02b81b0594f
+                      tenantType: ORGANISATION
+                      eventCategory: PAYMENT
+                      eventType: UPDATE
+                      eventDateUtc: 2025-10-21T02:20:04.117
+                      data:
+                        PaymentType: ACCRECPAYMENT
+                        Status: DELETED
+                        UpdatedDateUTCString: 2025-10-21T02:20:04Z
+                  firstEventSequence: 77
+                  lastEventSequence: 77
+                  entropy: FXNGWLCCGVANWHKILRUB
+      responses:
+        "200":
+          $ref: "#/components/responses/200WebhookDataReceivedOk"
+        "401":
+          $ref: "#/components/responses/401InvalidWebhookData"
 components:
   headers:
     x-xero-signature:
@@ -235,6 +289,9 @@ components:
                   - type: string
                     const: OVERPAYMENT
                     description: For organisation overpayment-related events
+                  - type: string
+                    const: PAYMENT
+                    description: For organisation payment-related events
               tenantId:
                 type: string
                 format: uuid
@@ -440,6 +497,76 @@ components:
                             description: The date and time the overpayment was last updated in UTC ISO format
                     required:
                       - data
+    PaymentWebhookEvent:
+      allOf:
+        - $ref: "#/components/schemas/WebhookEvent"
+        - type: object
+          properties:
+            events:
+              type: array
+              items:
+                allOf:
+                  - $ref: "#/components/schemas/WebhookEvent/properties/events/items"
+                  - type: object
+                    properties:
+                      eventCategory:
+                        const: PAYMENT
+                      data:
+                        type: object
+                        description: Payment lifecycle events for payments applied to and removed from accounting documents
+                        required:
+                          - PaymentType
+                          - Status
+                          - UpdatedDateUTCString
+                        properties:
+                          PaymentType:
+                            type: string
+                            description: The specific type of payment, determined by the type of the document the payment was applied to
+                            externalDocs:
+                              url: https://developer.xero.com/documentation/api/accounting/types#payments
+                            oneOf:
+                              - type: string
+                                const: ACCRECPAYMENT
+                                description: Accounts receivable payment
+                              - type: string
+                                const: ACCPAYPAYMENT
+                                description: Accounts payable payment
+                              - type: string
+                                const: ARCREDITPAYMENT
+                                description: Accounts receivable credit note payment (refund)
+                              - type: string
+                                const: APCREDITPAYMENT
+                                description: Accounts payable credit note payment (refund)
+                              - type: string
+                                const: ARPREPAYMENTPAYMENT
+                                description: Accounts receivable prepayment payment (refund)
+                              - type: string
+                                const: APPREPAYMENTPAYMENT
+                                description: Accounts payable prepayment payment (refund)
+                              - type: string
+                                const: AROVERPAYMENTPAYMENT
+                                description: Accounts receivable overpayment payment (refund)
+                              - type: string
+                                const: APOVERPAYMENTPAYMENT
+                                description: Accounts payable overpayment payment (refund)
+                          Status:
+                            type: string
+                            description: The current lifecycle status of the payment
+                            externalDocs:
+                              url: https://developer.xero.com/documentation/api/accounting/types#payment-status-codes
+                            oneOf:
+                              - type: string
+                                const: AUTHORISED
+                                description: Authorised payment
+                              - type: string
+                                const: DELETED
+                                description: Deleted payment
+                          UpdatedDateUTCString:
+                            type: string
+                            format: date-time
+                            description: The date and time the parent document was last updated in UTC ISO format
+                    required:
+                      - data
   responses:
     401InvalidWebhookData:
       description: Return a 401 status to indicate that the webhook subscription failed