This guide walks you through how to collect permissions from end users to apply for the government bonus; collecting the required data for the application and how to track the progress of the application made by Upvest on your behalf.
Eligible individuals can receive various types of government bonuses into their pension accounts. Before they can begin receiving these bonuses, users must first submit a bonus application (Antrag auf Altersvorsorgezulage) - either directly or via their provider - to the Zentrale Zulagenstelle für Altersvermögen (ZfA).
Once the ZfA approves the application, the user will automatically receive their eligible bonuses into their account during the ZfA’s defined distribution periods. Upvest can manage the application process on behalf of clients when permissions are granted and the relevant application details are submitted.
Before submitting the bonus application, the user must grant permission to apply for the bonus on their behalf. The permission can be provided as recurring permission which is set once and valid until revoked, or one which must be renewed annually.
In the permission, the user must also state their eligibility for bonus payments. There are two types of eligibility based on the user’s situation:
Directly eligible (unmittelbar berechtigt): the user meets the requirements to apply for bonus payments and is part of one of the following eligible groups:
- Compulsory members of the statutory pension insurance (gesetzliche Rentenversicherung), including members of the agricultural pension fund (Alterssicherung der Landwirte), recipients of a full disability pension, and persons credited with child-raising periods.
- Civil servants and equivalent public-sector employees (Beamte, Richter, Berufssoldaten).
- Self-employed individuals who are not compulsory members of the statutory pension insurance.
- Employed members of professional pension schemes (berufsständische Versorgungseinrichtungen) who are exempt from statutory pension insurance.
- Cross-border commuters (Grenzgänger) who are compulsory members of a comparable foreign statutory pension system and subject to unlimited tax liability in Germany.
Indirectly eligible (mittelbar berechtigt): the pension owner is not eligible but has an eligible spouse which makes them indirectly eligible to apply for the bonus.
The user might be eligible for:
- Bonus (Grundzulage) - the general bonus. Up to €540 for directly eligible and €175 for indirectly eligible
- Child bonus (Kinderzulage) - up to €300 per child. See chapter below
- Young adult bonus (Berufseinsteigerbonus)
To receive the child bonus for a pension account, each child must be added to the permission entity. The child entry can be revoked at a future date if needed.
By default, the child bonus is disbursed to the parent actively receiving the Child Benefit (Kindergeld) for the specified period. To bypass this default and transfer the bonus to the other parent, the spouse's details must be added in the permissions to validate the transfer claim.
The government grants €200 one-off bonus for young adults aged 18-25. No additional information is required in the application to claim this bonus. The ZfA distributes this automatically.
- Webhook handler ready — Set up a webhook endpoint to listen for updates relating to the bonus
- Subscribe to
PENSION_DE_BONUS_PERMISSION.*events. - Subscribe to
PENSION_DE_BONUS_APPLICATION.*events.
- Subscribe to
- For more information, refer to Implementing webhooks.
The bonus application process encompasses two main steps:
- Storing the bonus application permissions for the owner of the pension account.
- Adding information on users included in the application, such as their own details and their spouse’s and children’s details.
Once the steps are completed, Upvest processes the application and shares the application’s progress with the client.
You can use the /bonus_permissions endpoint to store the details of the permission including the type of permission and the start date when the permission was provided. Once this information is added, it can be referenced for all future applications until the details are revoked.
Permission is linked to the pension account, if the user has two pension accounts they will need to apply a permission to each account they wish to make a bonus application from.
For pension owners, all mandatory fields in /users must be filled out, along with the fields that were optional during onboarding (gender, social security number and birth city). For more details, see the Onboarding: Creating new and updating existing users section in this guide.
POST /pension_de/wrappers/{tax_wrapper_id}/bonus_permissions
{
"qualifying_user": "PENSION_OWNER",
"permission_type": "RECURRING",
"eligibility_type": "STATUTORY_PENSION",
"valid_from": "2027-07-21T14:10:00.00Z",
"valid_to": ""
}See the Request fields for the /bonus_permissions endpoint section for details on each field.
Within the bonus permission entity, you can also enter additional application details for associated individuals by setting the qualifying_user field to SPOUSE or CHILD.
The permission_type field is not required for these users, permission is automatically recurring until revoked.
POST /pension_de/wrappers/{tax_wrapper_id}/bonus_permissions
{
"qualifying_user": "CHILD",
"valid_from": "2027-07-21T14:10:00.00Z",
"first_name": "Fred",
"last_name": "Schmidt",
"birth_date":"2021-05-01",
"bonus_transfer_consent": false,
"child_benefit_number":"123FK678901",
"tax_identifier_number":"12345678901"
}See the Request fields for the /bonus_permissions endpoint section for details on each field.
If the end user is indirectly eligible, the details for the spouse must be added. The details must also be added if the spouse grants permission for a child bonus transfer.
POST /pension_de/wrappers/{tax_wrapper_id}/bonus_permissions
{
"qualifying_user": "SPOUSE",
"valid_from": "2027-04-22T10:00:00.000Z",
"title":"DR",
"first_name": "Kate",
"last_name": "Schmidt",
"gender": "FEMALE",
"birth_city":"Berlin",
"birth_date":"1983-05-01",
"tax_identifier_number":"12345678901",
"social_security_number": "25300972S014"
}See the Request fields for the /bonus_permissions endpoint section for details on each field.
| Field | REQUIRED | Description |
|---|---|---|
qualifying_user | All applicants | The type of user being added to the bonus application. This field accepts the following values: - PENSION_OWNER: the main applicant and owner of the pension account. - SPOUSE: the life partner to be included in the application. - CHILD: an eligible child to be included in the application. |
permission_type | Pension owner only | The type of permission being granted. - RECURRING: the user has granted a recurring permission (Dauerzulagenantrag) to apply for the government bonus until the permission is revoked. - ANNUAL: the user has granted temporary permission which must be renewed each year. You must set the valid_to field when permission_type equals ANNUAL. |
eligibility_type | Pension owner only | The type of eligibility for the user. - STATUTORY_PENSION: Compulsory member of the German statutory pension insurance (gesetzliche Rentenversicherung) or the agricultural pension fund (Alterssicherung der Landwirte). This also covers recipients of a full disability pension and persons credited with child-raising periods (Kindererziehungszeiten) who were previously in an eligible group. - CIVIL_SERVANT: Recipients of domestic public-sector remuneration, including civil servants, judges, professional soldiers, and equivalent categories.- SELF_EMPLOYED: Self-employed individuals earning income from a trade (Gewerbebetrieb) or freelance activity (selbständige Arbeit), who are not compulsory members of the statutory pension insurance. - PROFESSIONAL_PENSION: Employed individuals who are compulsory members of a professional pension scheme (berufsständische Versorgungseinrichtung) and exempt from statutory pension insurance. - CROSS_BORDER: Individuals who are compulsory members of a comparable foreign statutory pension system and subject to unlimited tax liability in Germany. - INDIRECTLY_ELIGIBLE: The user is not directly eligible but has a spouse who is directly eligible.Note: When set to INDIRECTLY_ELIGIBLE, the details of the eligible spouse must be added to the bonus permission as shown below. |
valid_from | All applicants | The start date when the permission was granted. |
valid_to | All applicants | The end date for the granted permission, or date of revoked permission. Required when permission_type equals ANNUAL. |
For spouses and children, use the /bonus_permissions endpoint fields below to add their user details.
Use the /bonus_permissions endpoint to set the pension owner's bonus_transfer_consent, if applicable.
For pension owners, user details can be added using the /users endpoint when onboarding a new user or updating an existing one.
| Field | REQUIRED | Description |
|---|---|---|
title | Optional | The user’s title. You can use one of the following values: - (empty string) - DR: Doctor. - PROF: Professor - PROF_DR: PHD/Professor and Doctor - DIPL_ING: Graduate engineer (Diplom-Ingenieur) - MAGISTER: Master of arts |
first_name | Required: Spouse and children | The user’s first name. |
last_name | Required: Spouse and children | The user’s family name. |
birth_date | Required: Spouse and children | The user’s birth date. |
gender | Required: Spouse only | The spouse’s gender. This field allows the following values: - MALE - FEMALE - DIVERSE Note: Gender is required for both the owner of the pension account and their spouse. However for the owner of the pension account, gender is added using the /users endpoint. Use the /bonus_permissions endpoint to list the gender for the spouse. |
birth_city | Required: Spouse only | The city where the user was born. |
birth_name | Optional: Spouse only | The user’s birth name. Note: You must add the optional birth_name field if the last name is different from the given birth name. |
bonus_transfer_consent | Optional: Child only | Used when the pension's owner wishes to transfer the child bonus payments to their spouse. - false: The child bonus is not transferred and does not require consent for a transfer. - true: Consent has been given to transfer the child bonus to a spouse. When set to true, the user must also provide the spouse's details. |
tax_identifier_number | Required: Spouse and children | The user’s tax identification number (TIN) |
child_benefit_number | Required: Child only | The child’s assigned benefit number (Kindergeldnummer). |
social_security_number | Required: Spouse | The eligible spouse’s assigned social security number or bonus_id. |
If an indirectly eligible spouse does not have a `social_security_number`, the ZfA assigns a `bonus_id`. This id will be updated to the bonus application when Upvest receives this value from the ZfA. If a `social_security_number` is provided in future, this number will be used in the application instead.
You can retrieve the relevant permission details on a pension account and the associated individuals by using a GET call. In the following example, the applicant is directly eligible and has added their child to apply for the child bonus.
GET /pension_de/wrappers/{tax_wrapper_id}/bonus_permissions
{
"meta": {
"offset": 0,
"limit": 20,
"count": 3,
"total_count": 3,
"sort": "qualifying_user",
"order": "ASC"
},
"data": [
{
"created_at": "2027-04-22T10:00:00.000Z",
"updated_at": "2027-04-22T10:00:00.000Z",
"permission_id": "b2c3d4e5-6789-0123-4567-890123456789",
"qualifying_user": "PENSION_OWNER",
"status": "ACTIVE",
"valid_from": "2027-01-01T00:00:00.000Z",
"permission_type": "RECURRING",
"eligibility_type": "STATUTORY_PENSION"
},
{
"created_at": "2027-04-22T10:00:00.000Z",
"updated_at": "2027-04-22T10:00:00.000Z",
"permission_id": "c3d4e5f6-7890-1234-5678-901234567890",
"qualifying_user": "CHILD",
"status": "ACTIVE",
"valid_from": "2027-01-01T00:00:00.000Z",
"first_name": "Fred",
"last_name": "Schmidt",
"birth_date": "2021-05-01",
"child_benefit_number": "123FK678901",
"tax_identifier_number": "12345678901",
"bonus_transfer_consent": false
},
{
"created_at": "2027-04-22T10:00:00.000Z",
"updated_at": "2027-04-22T10:00:00.000Z",
"permission_id": "d4e5f6a7-8901-2345-6789-012345678901",
"qualifying_user": "SPOUSE",
"status": "ACTIVE",
"valid_from": "2027-01-01T00:00:00.000Z",
"first_name": "Kate",
"last_name": "Schmidt",
"birth_date": "1983-05-01",
"tax_identifier_number": "98765432109",
"gender": "FEMALE",
"birth_city": "Berlin",
"social_security_number": "151280S123"
}
]
}Permissions can be updated with new data or revoked at a later date if the application circumstances change using PATCH. Updating a child or spouse status to REVOKED will remove them from the next bonus application.
To revoke a bonus permission, include the permission_id in the request path and "status": "REVOKED" in the request body.
PATCH /pension_de/wrappers/{tax_wrapper_id}/bonus_permissions/{permission_id}
{
"status": "REVOKED"
}The final step is for Upvest to submit the bonus application to the ZfA of all pension accounts with an ACTIVE bonus permission from the pension owner. This is an annual process that is triggered using the /bonus_applications entity and can be tracked by clients using the /bonus_applications webhook and endpoint.
Upvest will perform the following steps:
Stage 1: Create application
Prior to submitting to the ZfA, Upvest will create applications for all pension accounts with a valid permission from the pension owner for this year's submission. It will also collect data from all other permissions for spouse and children and flag any missing data needed for a successful submission. Every pension account will be assigned an application id with a status of NEW, BONUS_APPLICATION_INCOMPLETE or READY_FOR_SUBMISSION.
Stage 2: Submit to ZfA
At a communicated cut off date, following the contribution year, Upvest will send all pension accounts with a valid permission to the ZfA. Upvest will not exclude BONUS_APPLICATION_INCOMPLETE as this status is only designed to aid successful applications and not to make a determination. On sending the application to the ZfA, the status will update to SUBMISSION_ACCEPTED or SUBMISSION_REJECTED. Where a submission is rejected, Upvest will review if this is due to a technical issue and resubmit. If the issue is with the application itself (e.g., incorrect data), Upvest will coordinate with the client for fast resolution.
Stage 3: Process ZfA response
Following the ZfA's review, the application status will be updated with the outcome of either BONUS_APPLICATION_CONFIRMED or BONUS_APPLICATION_REJECTED depending on the ZfA decision to award bonuses.
The bonus application goes through the following statuses:
| Application stage | Status | Description |
|---|---|---|
| Stage 1: Create application | NEW | The application has been created. |
| Stage 1: Create application | BONUS_APPLICATION_INCOMPLETE | The application is missing some of the required data. |
| Stage 1: Create application | READY_FOR_SUBMISSION | The minimum required information is available in the Upvest system and ready to send to the ZfA. |
| Stage 2: Submit to ZfA | SUBMISSION_ACCEPTED | The application has been sent and the ZfA has verified the information is correct. |
| Stage 2: Submit to ZfA | SUBMISSION_REJECTED | The submitted application was rejected by the ZfA. |
| Stage 3: Process ZfA response | BONUS_APPLICATION_CONFIRMED | The application was submitted and the bonus has been confirmed. |
| Stage 3: Process ZfA response | BONUS_APPLICATION_REJECTED | The application was submitted but the ZfA decided the user was not eligible for the bonus. |
The /bonus_applications endpoint can also be used to query historic applications. The entity will also be updated where the ZfA assigns a bonus_id (the ZfA will do this when a social security number is unavailable but the user is qualifying for a bonus).
GET /pension_de/wrappers/{tax_wrapper_id}/bonus_applications
{
"meta": {
"offset": 0,
"limit": 100,
"count": 2,
"total_count": 2,
"sort": "valid_from",
"order": "DESC"
},
"data": [
{
"application_id": "0d68fea2-66e8-4ea8-b507-276e7a1eb4ab",
"application_year": "2028",
"submission_date": "2028-12-31T14:10:00.00",
"identification": {
"type": "SOCIAL_SECURITY_NUMBER",
"id": "25300972S014"
},
"status": "BONUS_APPLICATION_CONFIRMED"
},
{
"application_id": "0d68fea2-66e8-4ea8-b507-276e7a1eb4aa",
"application_year": "2027",
"submission_date": "2027-12-31T14:10:00.00",
"identification": {
"type": "BONUS_ID",
"id": "40300972S345"
},
"status": "BONUS_APPLICATION_CONFIRMED"
}
]
}Upvest handles the process of applying for bonuses and the ZfA sends the aggregated bonus payment to the provider’s pooling account. The process for investing the bonuses can be configured depending on whether the client would like to control how the bonus is invested or have Upvest execute investments on their behalf. This varies depending on your payment and settlement flow.
Client is certified and utilises post-trade settlement
- ZfA confirms receipt of the bonus application.
- ZfA completes their assessment and:
- sends aggregated funds to the client’s pooling account.
- sends Upvest a breakdown of the individual allocations.
- Upvest sends a treasury report to the client to confirm the total received to the bank matches the total in the ZfA allocations.
- Client confirms that the treasury report reconciles via API call.
- Upvest creates the individual bonus payments based on the ZfA’s allocations which increases the individuals’ pension account cash balance.
- The bonus cash can then be invested according to client/account preference (either processed by the client or auto-invested by Upvest).
Client uses pre-funding settlement, Upvest is certified/ operates the pooling account
- ZfA confirms receipt of the bonus application.
- ZfA completes their assessment and:
- sends aggregated funds to the Upvest managed cash pooling bank account.
- sends Upvest a breakdown of the individual allocations.
- Upvest creates individual bonus payments based on the ZfA allocations which increases the individuals’ pension account cash balance.
- The bonus cash can then be invested according to client/account preference (either processed by the client or auto-invested by Upvest).
While the pension products are tax-deferred by nature, each transaction and gains must be allocated into different tax pots. Upvest handles the tax pot administration on behalf of the clients.