Skip to content

feat!: add payments webhook endpoint and schema #851

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
gcxero wants to merge 2 commits into
base: master
Choose a base branch
from
Open

feat!: add payments webhook endpoint and schema #851

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
37816b3
feat!: add payments webhook endpoint and schema
gcxero Sep 30, 2026
afc54d1
docs: update payment types to align with docs
gcxero Oct 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
127 changes: 127 additions & 0 deletions xero-webhooks.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
openapi: 3.1.1
info:
description: The Xero Webhooks API exposes event notifications relating to entities in the Xero Public API and can be used for a variety of purposes
Expand Down Expand Up @@ -171,6 +171,60 @@
$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:
Expand Down Expand Up @@ -235,6 +289,9 @@
- 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
Expand Down Expand Up @@ -440,6 +497,76 @@
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 Payment (Refund)
- type: string
const: APCREDITPAYMENT
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)
- type: string
const: APPREPAYMENTPAYMENT
description: Accounts Payable Prepayment 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
Expand Down
Loading