How to integrate PEA tax wrappers

Integrating tax wrapper functionality for PEAs

1. Onboarding

   After creating your user, the next onboarding step is the creation of an account group. Tax-wrapped investment account groups must set type equal to FRENCH_PEA during the account group creation API call:

   {
     "user_id": "413715f2-5401-4b97-8055-034a6b879f8c",
     "type": "FRENCH_PEA"
   }

   Note: Tax-wrapped investment accounts are typically only available to (tax) residents of the country which regulates the specific tax wrapper. The account group will not transition to ACTIVE until the customer has confirmed their eligibility by creating a tax residency with an associated tax identification number (‘TIN’).

   After creating the account group, you can proceed with creating an account using the standard account creation flow.

2. Tax Wrapper Creation

   The business rules and logic applicable to a tax-wrapped investment product are managed through the Tax Wrapper entity.

   A dedicated API call is available for each tax wrapper type.

   POST /pea/wrappers

   {
     "type": "PEA_CLASSIQUE",
     "account_group_id": "0d68fea2-66e8-4ea8-b507-276e7a1eb4aa"
   }

   Tax Wrapper Status

   Created Tax Wrappers transition to ACTIVE if the linked account group is ACTIVE.

   The PEA_CLASSIQUE account group type requires a confirmed tax residency. To accomplish this, you must create a tax residency as shown in the User Tax Onboarding section.

3. Allowance events

   Once the Tax Wrapper has transitioned to ACTIVE, the Investment API will automatically create the underlying Allowance resource and confirm its creation via webhook emission.

   {
     "id": "295cf14f-368c-450e-b57e-48d115d30fe4",
     "created_at": "2025-08-01T10:34:43Z",
     "type": "PEA_WRAPPER_ALLOWANCE.CREATED",
     "object": {
       "id": "f1a57a04-1a89-4dab-ae3a-ff9b2a9377c1",
       "created_at": "2025-10-05T14:48:00.000Z",
       "updated_at": "2025-10-05T14:48:00.000Z",
       "tax_wrapper_id": "0d68fea2-66e8-4ea8-b507-276e7a1eb4aa",
       "type": "LIFETIME",
       "status": "ACTIVE",
       "currency": "EUR",
       "total_amount": "150000.00",
       "used_amount": "1000.00",
       "remaining_amount": "149000.00",
       "valid_from": "2025-04-06T00:00:00.000Z",
       "first_contribution_at": "2025-05-13T00:00:00.000Z"
     },
     "webhook_id": "4a80c45f-204c-4498-ac20-d900a846e166"
   }

   PEA allowance events

   The PEA allowance events contain a lot of metadata, but the following values are related to the key business logic for PEA products.

   • type: The ‘Lifetime’ type refers to how the regulatory contribution limit is applicable across the PEA’s lifetime. For PEAs this value is set at €150,000. Regulatory changes to this limit are managed by Upvest and will automatically be applied for newly opened PEA accounts.

   • Allowance values:

     • total_amount: Regulatory determined contribution limit.
     • used_amount: How much of the regulatory contribution limit has been used, determined by inflow into the tax wrapped product.
     • remaining_amount: Mathematical difference between total and used amount.
     • first_contribution_at: Populated at the first inflow.

   

   Allowance events are emitted upon:

   • Creation: PEA_WRAPPER_ALLOWANCE.CREATED
   • Every time an inflow takes place into the tax wrapped product: PEA_WRAPPER_ALLOWANCE.UPDATED
   • Every time an outflow takes place from the tax wrapped product: PEA_WRAPPER_ALLOWANCE.UPDATED
   • When hitting the valid_to dateTime: TAX_WRAPPER_ALLOWANCE.EXPIRED
4. Display allowance status

   The Investment API supports a synchronous endpoint to display the current state of allowances to an PEA account holder on your app or website.

   GET /pea/wrappers/{tax_wrapper_id}/allowances/

   {
     "meta": {
       "offset": 0,
       "limit": 100,
       "count": 2,
       "total_count": 2,
       "sort": "valid_from",
       "order": "DESC",
     },
     "data": [ 
       {
         "allowance_id": "",  
         "tax_wrapper_id": "",
         "tax_year": {null}, 
         "type": "LIFETIME, PME...",
         "status": "ACTIVE, EXPIRED",
         "currency": "EUR",
         "total_amount": "",
         "used_amount": "",
         "remaining_amount": "",
         "first_contribution_at": "2021-07-21T14:10:00.00Z",
         "created_at": "2021-07-21T14:10:00.00Z",
         "updated_at": "2021-07-21T14:10:00.00Z",
         "valid_from": "2021-07-21T14:10:00.00Z",
         "valid_to": {null},
       },
     ]
   }