Getting started with Maventa ePayslip

A short guide for partners moving from the existing SOAP API to the new REST API. Most of the work is on the wire — the underlying behavior, payslip XML schema (v2.0), and business rules are unchanged.

For full per-endpoint usage details (request bodies, examples, response schemas), use the interactive API browser at https://verkkopalkkademo.maventa.fi/api/scalar/v1 or feed https://verkkopalkkademo.maventa.fi/api/openapi/v1.json into your code generator. The reference is hosted on the demo environment; demo and production expose the same API surface, so it applies to both. This guide only describes what is different between SOAP and REST.

Environments

Use the demo host while integrating; switch to the production host when ready to go live. All REST API endpoints sit under the /api/ path of these hosts.

Endpoint mapping

Both SOAP and REST run in parallel — there is no flag day. Migrate one operation at a time and switch traffic at your own pace.

What you have to change in your integration

Authentication: token instead of header credentials

Username + password are no longer in every request’s SOAP header. Instead, call POST /api/connect/token once, cache the returned bearer token, and send it as Authorization: Bearer <token> on every other call.

• Token lifetime: 1 hour. Cache it.
• Same credentials as the SOAP service — no new accounts to provision. Treat them as one credential: a leak, rotation, or password change on either side applies to both APIs at once.
• Token endpoint is rate-limited to 20 requests per 10 minutes, so don’t fetch a new token per call.
• Repeated wrong-password attempts will temporarily lock the account (same behaviour as SOAP). Contact support if you need a password reset.

Batch upload: multipart instead of base64

ZIP file is sent as raw binary in a multipart/form-data field named zipFile instead of base64-encoded inside <ZipFile>…</ZipFile>. About 25 % less bytes on the wire (base64 expansion goes away).

• OriginalFileName SOAP header → fileName form field.
• BatchId is always generated by the server. If you sent your own externally-generated ID before, store the server’s response batchId instead.
• Convert flag is gone. Payslip XML must be v2.0. If you still produce 1.1, convert before sending.
• Same ZIP rules: ≤ 100 MB, only .xml and .pdf, optional PDF attachments matched by exact path.

Request and response format: JSON

All non-batch requests use JSON bodies (or query strings) and return JSON responses. The SOAP Acks / Products XML envelopes are replaced with simple JSON arrays and objects — see Scalar UI for the exact shapes.

• Property names use camelCase.
• Date-range filters use half-open intervals [start, end). To query all of March 2026: startDate=2026-03-01&endDate=2026-04-01.
• Status query date range max 24 hours; transactions max 31 days.

Errors: HTTP status codes + ProblemDetails JSON

FaultException<BatchDeliveryFault> is replaced by HTTP status codes plus an RFC 9457 application/problem+json body. The human-readable error reasons in the detail field are the same strings you handle today (BankNotIdentified, NoValidContract, Duplicate, Print delivery requires CountryCode, etc.).

Dates: UTC with Z

Always serialize as UTC with the Z suffix: 2026-05-04T10:32:11Z. Local-time strings are not accepted.

SOAP fields and operations that no longer exist

A small list so you don’t go hunting for them:

Migration checklist

1. Implement a token cache that fetches on startup and refreshes before the 1-hour expiry.
2. Switch your batch upload from base64-in-XML to multipart form upload. Drop your client-side BatchId — store the server’s response.
3. Make sure your code records MessageId per submitted payslip — it’s the only stable selector for DELETE /api/v1/payslips.
4. Switch SOAP XML parsing to JSON for status, payer, transaction, and BIC code responses. The error strings in description / detail are unchanged — map them through.
5. Switch Activate / Deactivate payload construction to the JSON / URL-path shapes documented in Scalar.
6. Handle HTTP status codes plus ProblemDetails JSON for error responses.
7. Ensure all outbound dates are UTC with Z.
8. Test in our demo environment

Where to find usage details

• Full REST documentation (concepts, packaging rules, print delivery, payer activation, billing): https://maventaverkkopalkka.fi/verkkopalkan-kayttoonotto/
• Interactive UI (try every endpoint, generate code samples in your language):
  • Demo: https://verkkopalkkademo.maventa.fi/api/scalar/v1
  • Production: not available — use the demo environment for testing
• OpenAPI 3 schema (feed into NSwag, openapi-generator, etc.):
  • Demo: https://verkkopalkkademo.maventa.fi/api/openapi/v1.json
  • Production: not available — use the demo schema
• Support: same channel as for the SOAP API. When reporting an issue, include the traceId field from the error response body, the timestamp, and the endpoint you called.

Close

Print delivery

Print delivery is configured in the payslip XML, so it works the same whether you submit batches via the REST API or the SOAP API.

When a payslip is delivered as a physical letter, the print-specific settings live inside the payslip XML — they are part of the schema rather than separate REST fields.

Recipient address

The recipient block is built from <Delivery><Recipient> and from the print delivery channel’s <DeliveryInfo>. The table below shows where each XML element goes: onto the cover page (the first printed page, visible through the envelope window), into a form field sent to the printing service, or both.

Sender address

The sender block is built from <Delivery><Sender> and <HeaderData><PartyIdentifications>.

The values in the Required column mean:

• Schema — required by the PayslipXML 2.0 schema. Missing-element payslips fail XSD validation and the whole batch is rejected.
• Print delivery — required only when the payslip uses print delivery (DeliveryMethodCode = 02 or both). Missing-element payslips are rejected during batch processing with the message ”Print delivery requires CountryCode (ISO 3166-1 alpha-2)”.
• Foreign print — required only for foreign print delivery (CountryCode ≠ FI). Rejection message: ”Foreign print delivery requires both CountryCode and Country (full name for envelope)”.
• Optional — not enforced; supplying it just enables additional functionality (e.g. OmaPosti routing, digital-post matching).

Cover-page address layout

Both blocks are rendered in Arial 10 pt into fixed boxes whose dimensions and positions match the printing service’s cover page layout. The printing service publishes the full specification — see the layout design instructions and the cover page template.

Capacity (in addition to the fixed name + postal/city + country lines):

• Sender box fits up to 4 AddressLine lines (7 lines total).
• Recipient box fits up to 5 AddressLine lines (8 lines total).

Wrapping rules:

• A line that is too wide is wrapped at word boundaries onto the next line, consuming one of the available lines above.
• A single word wider than the box itself is broken across characters.
• If the resulting text does not fit vertically into the box, the whole payslip is rejected during batch processing — the address would otherwise be silently clipped on the printed letter. The rejection message names which box (sender or recipient) and asks you to shorten the name, address lines, postal code, city, or country.

If a partner’s data hits the limit consistently, the practical fix is to reduce the number of AddressLine entries — for example, merge ”Long Street Name 12” and ”A 5” into a single AddressLine. Empty <AddressLine></AddressLine> elements are dropped automatically and do not consume a line, so they are safe to leave in.

Letter options (PrintingInfo)

<DeliveryChannel>
  <DeliveryMethodCode>02</DeliveryMethodCode>
  <DeliveryInfo>
    <PrintingInfo>
      <LetterClass>economy</LetterClass>     <!-- economy (default) | priority -->
      <Form>color_print,duplex</Form>        <!-- comma-separated, optional   -->
    </PrintingInfo>
  </DeliveryInfo>
</DeliveryChannel>

Attachments

PDF attachments referenced from the payslip XML are appended after the payslip pages. They are printed as supplied, so leave at least a 17 mm top margin and 3 mm side and bottom margins in any PDF you reference — otherwise content near the edge can be clipped.

OmaPosti routing

If the recipient has registered for OmaPosti and chosen to receive mail digitally, the letter is delivered to their OmaPosti inbox instead of being physically mailed. Recipients activate the service themselves at posti.fi; we cannot enroll them. The digital lookup uses the sender OVT (see the sender table above) plus, when supplied, the recipient phone and email; without an OVT the letter is still printed and mailed normally, only the digital routing step is skipped.

Close