Integrating Ason into your platform usually means getting access to the outputs that Ason generates: payslips, payroll journal, posting documents, Swissdec declarations and more - generated automatically. This can mean automatically importing positions from the accounting document or providing a platform-native way for your clients to access the document from the payroll process.
Ason makes this easy by allowing you to subscribe to webhook events for the closure / finalization of the payrun period. The event for the closure will be fired shortly after closing the period. Documents associated with the closure are AccountingDocument, Payslip, CumulativeJournal and PaymentFile. The finalization of the period can take longer: Ason handles the submission to regulatory bodies in each country and will fire the finalization event when the process is complete. Depending on the country, different documents will be available from this process.
What you get, and when
After each payment
- Payment file (pain.001)
After closing the payroll period
- Payslips (per employee)
- Cumulative payroll journal (per employee and overall)
- Posting documents and recap
- Payroll statements
After finalising the payroll period
- Swissdec payroll notifications (ELM)
- Declarations to authorities and insurance companies
- Withholding tax reports
- Year-end reports
The accounting posting document
Every closed payroll period produces an accounting posting document (Buchungsbeleg) - a structured export of all payroll-related bookings, ready to import into any accounting/Fibu software:
- Salary expense, deductions and employer contributions per employee and Cost Center
- Bank transfer totals matching the payout that was executed
- One posting document per closed payroll period, generated automatically - no manual booking
How wage types map to accounts is configured once per payroll via WageType-Accounting-Allocation - and must be complete before a period can close.
Going live: enabling Swissdec transmission
Closing a period does not send anything to Swissdec until the payroll has been switched to "live" - a one-time step, not something that happens automatically on signup. Until then, periods close normally, but the Swissdec-related documents (declarations, ELM notifications) are simply not generated or sent.
To go live, update the payroll with a transmissionStartDate (UI: Payroll → Settings → "Go live"; API: PUT /tenants/{tenantId}/payrolls/{payrollId} with transmissionStartDate set to the period you want transmission to start from). From that period onward, closing will also submit to Swissdec.
Webhook setup
First, let's set up a webhook to get notified about these events.
Code
payloadUrl: The endpoint Ason will try to send a HTTP POST request with the webhook payload to.events: List of events to subscribe to.secret: A secret. More on that below.payloadMetadata: This collection will be sent with each payload. Useful for adding mapping information.
To create webhooks you need to be an admin of the tenant.
Payload
All webhook payloads contain at least these fields:
$type: discriminator for the type of payload.correlationId: The correlationId of the event. Stable between redeliveries.timestamp: Timestamp of when Ason generated the payload.metadata: Metadata you provided when creating the webhook.
Additionally these fields are present for the PayrunPeriodClosed/Finalized events:
$type=WebhookPayloadPayrunPeriodClosed/WebhookPayloadPayrunPeriodFinalizedpayrollId: The ason id of the payroll.payrunPeriodId: The ason id of the payrun period.periodStart: Start date of the payrun period.periodEnd: End date of the payrun period.
Security
Your endpoint receiving the Ason webhook needs to verify that the incoming request is originating from Ason. Requests from Ason will contain the header X-Ason-Signature: sha256=<signature>. Ason generates signatures using a hash-based message authentication code (HMAC) with SHA-256. To verify the signature, take the secret you provided when creating the webhook as the key and use the request body as message.
Retrieval
The webhook events are thin events thus they do not contain any documents. Use the payrun period documents endpoint to list what's available once the webhook fires.
Code
The response is an array of documents:
Code
To fetch a single document instead of the whole list, use GET /api/tenants/{tenantId}/payrolls/{payrollId}/payrunperiods/{payrunPeriodId}/documents/{documentId}.
Testing
In the sandbox environment the finalization of the period is faked. Shortly after closing the period a finalized event will be sent with a document for each listed category.
FAQ
What's the difference between Outputs and the documents I upload myself?
Outputs are generated by Ason (payslips, declarations, posting documents). Files you attach to a case value are yours to upload - see Company Data incl. Documents / Employee Data incl. Documents.
Why isn't anything being sent to Swissdec after I close a period?
The payroll hasn't been switched to "live" yet - see "Going live" above.
Why does generating the accounting document fail?
The wage type to account mapping isn't complete for every wage type used in the period - see WageType-Accounting-Allocation.
Can the accounting document be generated as JSON?
No - generated documents (including the accounting document) only come as Word, Excel, Pdf, Xml, XmlRaw or Csv, whichever the assigned accountingDocument regulation produces. Xml/XmlRaw is the closest structured-data option; if you specifically need JSON, get in touch.
Do I need to poll for outputs?
No - subscribe via webhook (see "Webhook setup" above). The payment file is also returned directly when you create a payout.
How do outputs fit into an accounting product?
See Embedded Into Your Platform.
Are payslips always up to date before a period closes?
The payslip file itself is only generated once the period closes - while the period is still open, use Results to see up-to-date numbers, not a draft payslip file.
Where do I see the cumulative journal and payslips across all employees?
The cumulative journal is part of the period's Documents view, generated on close. Individual payslips are per-employee documents within that same set - there isn't a single "all payslips at once" page in the standard product UI, but the period's Documents endpoint returns every payslip document if you want to build that view yourself.
Can the layout of the payslip or cumulative journal be customized?
No customization option was found - treat the layout as fixed per regulation; get in touch if you need something different.
Where do I see which reports/documents were sent via ELM?
There's no dedicated "ELM submission log" - the closest is the period's Documents view after finalization, which includes the Swissdec-related declaration documents that were generated and sent.
When are year-end declarations sent?
As part of period finalization for the relevant year-end period, alongside the other Swissdec declarations - there's no separate manual trigger specific to year-end.
How do I automatically email payslips to employees after a period closes?
That's not a built-in Ason feature - Ason delivers the documents to you (webhook + documents endpoint); actually emailing them to employees is something you'd build on your platform, or check with support if you need this natively.
API Endpoints
| What | Call |
|---|---|
| List a payrun period's documents | GET .../payrunperiods/{payrunPeriodId}/documents |
| Get a specific payrun period document | GET .../payrunperiods/{payrunPeriodId}/documents/{documentId} |
| Create a webhook | POST /tenants/{tenantId}/webhooks |
| Update a payroll (e.g. set the go-live date) | PUT /tenants/{orgId}/payrolls/{payrollId} |