From 37816b383ca98913f89d1c95330951926ff06452 Mon Sep 17 00:00:00 2001 From: gcxero Date: Thu, 1 Oct 2026 09:29:51 +1000 Subject: [PATCH 1/2] 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. --- xero-webhooks.yaml | 127 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 127 insertions(+) diff --git a/xero-webhooks.yaml b/xero-webhooks.yaml index 094063703..c31195a8b 100644 --- a/xero-webhooks.yaml +++ b/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 From afc54d11b8149880dd95811709c1285df80c908f Mon Sep 17 00:00:00 2001 From: gcxero Date: Thu, 1 Oct 2026 10:49:52 +1000 Subject: [PATCH 2/2] docs: update payment types to align with docs --- xero-webhooks.yaml | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/xero-webhooks.yaml b/xero-webhooks.yaml index c31195a8b..1f985810a 100644 --- a/xero-webhooks.yaml +++ b/xero-webhooks.yaml @@ -527,28 +527,28 @@ components: oneOf: - type: string const: ACCRECPAYMENT - description: Accounts receivable payment + description: Accounts Receivable Payment - type: string const: ACCPAYPAYMENT - description: Accounts payable payment + description: Accounts Payable Payment - type: string const: ARCREDITPAYMENT - description: Accounts receivable credit note payment (refund) + description: Accounts Receivable Credit Payment (Refund) - type: string const: APCREDITPAYMENT - description: Accounts payable credit note payment (refund) + description: Accounts Payable Credit Payment (Refund) + - type: string + const: AROVERPAYMENTPAYMENT + description: Accounts Receivable Overpayment Payment (Refund) - type: string const: ARPREPAYMENTPAYMENT - description: Accounts receivable prepayment payment (refund) + 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) + description: Accounts Payable Prepayment Payment (Refund) - type: string const: APOVERPAYMENTPAYMENT - description: Accounts payable overpayment payment (refund) + description: Accounts Payable Overpayment Payment (Refund) Status: type: string description: The current lifecycle status of the payment