thebeardedbear / urssaf-tierce-declaration-paje
Client and domain model for the URSSAF "API Tierce Déclaration PAJE" (third-party Pajemploi declaration for childcare employers)
Package info
github.com/TheBeardedBearSAS/urssaf-tierce-declaration-paje
Type:symfony-bundle
pkg:composer/thebeardedbear/urssaf-tierce-declaration-paje
Requires
- php: >=8.2
- ext-filter: *
- ext-json: *
- ext-mbstring: *
- psr/cache: ^2.0 || ^3.0
- psr/clock: ^1.0
- psr/event-dispatcher: ^1.0
- psr/http-client: ^1.0
- psr/http-factory: ^1.1
- psr/http-message: ^1.1 || ^2.0
- psr/log: ^2.0 || ^3.0
- psr/simple-cache: ^2.0 || ^3.0
Requires (Dev)
- carthage-software/mago: ^1.59
- deptrac/deptrac: ^4.7
- doctrine/dbal: ^4.5
- doctrine/doctrine-bundle: ^2.19
- doctrine/orm: ^3.5.3
- doctrine/persistence: ^3.4.1 || ^4.0
- ergebnis/composer-normalize: ^2.56
- ergebnis/phpstan-rules: ^2.17
- friendsofphp/php-cs-fixer: ^3.95
- icanhazstring/composer-unused: ^0.9
- infection/infection: ^0.32
- maglnet/composer-require-checker: ^4.17
- nyholm/psr7: ^1.8.2
- php-http/client-common: ^2.7.2
- php-http/discovery: ^1.19.3
- php-http/httplug: ^2.4.1
- php-http/message: ^1.16.1
- php-http/mock-client: ^1.6.1
- php-http/promise: ^1.2.2
- phpstan/extension-installer: ^1.4
- phpstan/phpdoc-parser: ^2.0
- phpstan/phpstan: ^2.0
- phpstan/phpstan-deprecation-rules: ^2.0
- phpstan/phpstan-doctrine: ^2.1
- phpstan/phpstan-phpunit: ^2.1
- phpstan/phpstan-strict-rules: ^2.1
- phpstan/phpstan-symfony: ^2.1
- phpunit/phpunit: ^11.0
- rector/rector: ^2.8
- roave/security-advisories: dev-latest
- shipmonk/phpstan-rules: ^4.4
- symfony/cache: ^6.4 || ^7.4
- symfony/cache-contracts: ^2.5.3 || ^3.4.2
- symfony/clock: ^6.4.3 || ^7.4
- symfony/console: ^6.4 || ^7.4
- symfony/dependency-injection: ^6.4.26 || ^7.4
- symfony/error-handler: ^6.4.3 || ^7.4
- symfony/event-dispatcher-contracts: ^2.5.3 || ^3.4.2
- symfony/framework-bundle: ^6.4.3 || ^7.4
- symfony/http-client: ^6.4 || ^7.4
- symfony/lock: ^6.4.3 || ^7.4
- symfony/messenger: ^6.4.3 || ^7.4
- symfony/polyfill-php83: ^1.31
- symfony/property-access: ^6.4.3 || ^7.4
- symfony/property-info: ^6.4.3 || ^7.4
- symfony/scheduler: ^6.4.3 || ^7.4
- symfony/serializer: ^6.4.3 || ^7.4
- symfony/string: ^6.4.3 || ^7.4
- symfony/translation: ^6.4.3 || ^7.4
- symfony/translation-contracts: ^2.5.3 || ^3.4.2
- symfony/uid: ^6.4.3 || ^7.4
- symfony/validator: ^6.4.3 || ^7.4
- symfony/var-dumper: ^6.4.3 || ^7.4
- symfony/var-exporter: ^6.4.3 || ^7.4
- symfony/yaml: ^6.4 || ^7.4
- tomasvotruba/type-coverage: ^2.5
Suggests
- doctrine/dbal: Required by the Doctrine bridge (custom types)
- doctrine/doctrine-bundle: Required for the Doctrine bridge
- doctrine/orm: Required for the Doctrine bridge
- nyholm/psr7: PSR-17 factories for the HTTP gateway (any PSR-17 implementation works)
- symfony/cache: PSR-6 / PSR-16 pool for the OAuth2 token cache (Psr6TokenStore, Psr16TokenStore)
- symfony/config: Required by the Symfony bridge (bundle configuration)
- symfony/console: Provides the console commands of the bundle
- symfony/dependency-injection: Required by the Symfony bridge
- symfony/framework-bundle: Required to use the Symfony bundle
- symfony/http-client: PSR-18 compatible HTTP client for the API
- symfony/http-kernel: Required by the Symfony bridge (bundle)
- symfony/lock: Prevents overlapping runs of the same command / handler (see the "lock" bundle option)
- symfony/messenger: Asynchronous employer status refresh and integration event delivery
- symfony/scheduler: Runs the safety crons of the package as a Symfony Scheduler schedule (see the "scheduler" bundle option)
- symfony/translation: Translates the violation codes (English and French shipped)
- symfony/validator: Converts the violations of the package into a ConstraintViolationList
Provides
None
Conflicts
- doctrine/dbal: <4.0
- doctrine/doctrine-bundle: <2.19
- doctrine/orm: <3.5.3
- nyholm/psr7: <1.8.2
- symfony/clock: <6.4.3
- symfony/console: <6.4
- symfony/dependency-injection: <6.4.26
- symfony/framework-bundle: <6.4.3
- symfony/http-client: <6.4
- symfony/http-kernel: <6.4
- symfony/lock: <6.4.3
- symfony/messenger: <6.4.3
- symfony/scheduler: <6.4.3
Replaces
None
This package is auto-updated.
Last update: 2026-11-18 20:17:46 UTC
README
thebeardedbear/urssaf-tierce-declaration-paje — client, domain model and Symfony integration for the URSSAF API that
lets a platform, on behalf of a private employer, estimate the contributions of a Pajemploi activity, declare the
salary paid to a licensed childminder (assistante maternelle agréée) or a home childcare worker (garde d'enfants à
domicile), and apply the withholding at source.
Namespace: TheBeardedBear\UrssafTierceDeclarationPaje.
Developed and maintained by The Bearded Bear.
Important
Unofficial package. This project is an independent open-source implementation of a public API. It is not developed, endorsed, certified or supported by URSSAF, and it is not affiliated with URSSAF in any way. "URSSAF" is used only to name the API this package talks to. Using this package does not replace the URSSAF habilitation process; the URSSAF documentation remains the authority on the API, and you remain responsible for the data your application sends to URSSAF.
Status: 0.1.0 released; sandbox contract run still to do (see docs/roadmap.md). The 12 operations, the local workflow (employers, mandates, declarations, unknown outcomes, outbox), the standalone builder, the Symfony bundle (docs/symfony.md) and the Doctrine bridge (docs/doctrine.md) are in place; the open points of docs/api-reference.md §5 stay open until URSSAF publishes them or the sandbox contract run settles them. See the architecture decision records in docs/adr/.
Scope
| Operation | Endpoint |
|---|---|
| Check an employer account (PAJE020) | GET /employeurs/{numeroPajeEmployeur}/verifier |
| Check an employee account (PAJE021) | POST /salaries/verifier |
| Check the entitled children (PAJE022) | POST /employeurs/{numeroPajeEmployeur}/enfants/verifier |
| Associate an employee to an employer (PAJE023) | POST /employeurs/{numeroPajeEmployeur}/salarie/associer |
| Register a mandate (PAJE030) | POST /mandats |
| Cancel a mandate (PAJE031) | DELETE /mandats |
| Estimate contributions, childminder (PAJE040) | POST /ama/estimer |
| Estimate contributions, home childcare (PAJE041) | POST /ged/estimer |
| Pre-declare a childminder salary (PAJE045) | POST /employeurs/{numeroPajeEmployeur}/ama/predeclarer |
| Pre-declare a home childcare salary (PAJE046) | POST /employeurs/{numeroPajeEmployeur}/ged/predeclarer |
| Declare a childminder salary (PAJE050) | POST /employeurs/{numeroPajeEmployeur}/ama/declarer |
| Declare a home childcare salary (PAJE051) | POST /employeurs/{numeroPajeEmployeur}/ged/declarer |
OAuth2 client credentials, scope tiersdecl.paje, base URL https://api.urssaf.fr/tiersdecl/v1/paje (sandbox:
https://api-edi.urssaf.fr/tiersdecl/v1/paje).
Quick start (standalone)
Without a framework, the builder wires every use case from a PSR-18 client, PSR-17 factories and your credentials. Persistence is in memory by default (tests and prototypes); docs/standalone.md lists the options and docs/workflow.md explains the lifecycles. All values below are fictitious.
use TheBeardedBear\UrssafTierceDeclarationPaje\Application\Command\ImportEmployer; use TheBeardedBear\UrssafTierceDeclarationPaje\Application\Command\RegisterMandate; use TheBeardedBear\UrssafTierceDeclarationPaje\Application\Dto\EmployerSelector; use TheBeardedBear\UrssafTierceDeclarationPaje\Application\Port\Credentials; use TheBeardedBear\UrssafTierceDeclarationPaje\Domain\Employer\EmployerReference; use TheBeardedBear\UrssafTierceDeclarationPaje\Domain\Employer\PajeEmployerNumber; use TheBeardedBear\UrssafTierceDeclarationPaje\Domain\Shared\CalendarDate; use TheBeardedBear\UrssafTierceDeclarationPaje\Domain\Shared\ExternalReference; use TheBeardedBear\UrssafTierceDeclarationPaje\Domain\Shared\TenantId; use TheBeardedBear\UrssafTierceDeclarationPaje\Infrastructure\Credentials\StaticCredentialsProvider; use TheBeardedBear\UrssafTierceDeclarationPaje\Infrastructure\Urssaf\ApiConfiguration; use TheBeardedBear\UrssafTierceDeclarationPaje\Infrastructure\Urssaf\Environment; use TheBeardedBear\UrssafTierceDeclarationPaje\Infrastructure\Urssaf\HttpTransport; use TheBeardedBear\UrssafTierceDeclarationPaje\Standalone\UrssafTierceDeclarationPajeBuilder; // $httpClient is your PSR-18 client, $psr17Factory a PSR-17 request and stream factory. $urssaf = UrssafTierceDeclarationPajeBuilder::create( new HttpTransport($httpClient, $psr17Factory, $psr17Factory), new StaticCredentialsProvider(['tenant-1' => Credentials::of('my-client-id', 'my-client-secret')]), ApiConfiguration::forEnvironment(Environment::Sandbox), )->build(); $tenant = TenantId::fromString('tenant-1'); $employer = EmployerReference::of(PajeEmployerNumber::of('Y0000000000001'), CalendarDate::fromString('1980-01-01')); $reference = ExternalReference::fromString('employer-42'); // Record an employer you already know (no call to URSSAF), then register the mandate you hold for it (030). $urssaf->importEmployer()(new ImportEmployer($tenant, $reference, $employer)); $mandate = $urssaf->registerMandate()(new RegisterMandate($tenant, EmployerSelector::byExternalReference($reference))); $state = $mandate->state; // "registered"
Declaring a salary (declareSalary()), estimating contributions, checking the employer, the employee or the children,
resolving an unknown outcome and the safety crons are covered in docs/standalone.md and
docs/workflow.md. In tests, Testing\SimulatedPajeGateway replaces the HTTP gateway and never
contacts URSSAF.
Documentation
- docs/api-reference.md — technical reference (single source of truth for the package).
- docs/standalone.md — wiring without a framework, scheduling, testing with the simulator.
- docs/symfony.md — Symfony bundle: configuration, commands, Messenger, scheduler, locks, diagnostics, translations.
- docs/doctrine.md — Doctrine bridge: mapping, dedicated entity manager, concurrency, personal data.
- docs/workflow.md — lifecycles, outcome and re-entry tables, unknown outcomes, safety crons.
- docs/integration-events.md — public integration events
urssaf.paje.*and the outbox. - docs/testing.md — test suites, fakes, quality gates and the sandbox contract suite.
- docs/roadmap.md — planned architecture and order of work.
- docs/adr/ — architecture decision records.
- Security design and review: assurance case (threat model, trust boundaries, design principles, countered weaknesses) and security review.
- docs/openapi/ — official OpenAPI contract(s) from the URSSAF API portal.
docs/reference/— official URSSAF documentation: not versioned (URSSAF documents), download it from the links in docs/api-reference.md into this local, git-ignored folder.- Catalogue page: https://portailapi.urssaf.fr/fr/catalogue-api/prd/td-paje
Requirements
PHP 8.2+. Development only needs Docker: every make target runs in a container.
Development
make install # build the image, install dependencies make ci # full quality gate: cs, rector, phpstan, mago, deptrac, composer checks, hadolint, guard, coverage, infection make coverage-branches # branch coverage (Xdebug, slow), at least 96 % enforced make test # unit + functional tests make bench # benchmarks (PHPBench, tests/Benchmark), added with the implementation make test-contract # live sandbox contract tests (skipped without credentials), see below make help # every target
make ci PHP_VERSION=8.4 runs the gate on another PHP version.
Contract tests (URSSAF sandbox)
make test-contract runs the live contract suite against the URSSAF sandbox (https://api-edi.urssaf.fr; the production
host is refused). It is never part of make test or make ci. Without credentials every live test is skipped and the
target passes. Export the variables in your shell (they are forwarded to the container, nothing is written to a file):
| Variable | Purpose |
|---|---|
URSSAF_SANDBOX_CLIENT_ID, URSSAF_SANDBOX_CLIENT_SECRET |
OAuth2 credentials (secrets); without them every live test is skipped |
URSSAF_SANDBOX_BASE_URI, URSSAF_SANDBOX_TOKEN_URI |
optional host overrides (never api.urssaf.fr); when set, URSSAF_SANDBOX_TOKEN_URI receives every SDK token request, and the token test also probes the derived URI first |
URSSAF_SANDBOX_EMPLOYER_NUMBER, URSSAF_SANDBOX_EMPLOYER_BIRTH_DATE |
sandbox test employer (both or none) |
URSSAF_SANDBOX_EMPLOYEE_NUMBER |
sandbox test employee |
URSSAF_SANDBOX_CHILD_LAST_NAME, URSSAF_SANDBOX_CHILD_FIRST_NAME, URSSAF_SANDBOX_CHILD_BIRTH_DATE |
sandbox test child (all three or none) |
URSSAF_SANDBOX_ALLOW_WRITES |
1 also runs the tests that write sandbox state (030, 031, 023, 045, 046, 050, 051) |
A test whose variables are missing is skipped. The run writes var/contract/sandbox-report.json (statuses and error codes
only, never a body, a number, a name or a date). The same variables feed the manual contract job of the CI workflow
(secrets for the client id and secret, environment (or repository) variables for the others, a contract_writes input to write). Details
and the goals of the run: docs/testing.md.
Once the repository is public, main publishes its quality proofs, linked from the badges at the top of this file: the
coverage report on Codecov, the full mutation report on the Stryker Dashboard, the SonarQube Cloud quality gate and the
OpenSSF Scorecard. The benchmarks (tests/Benchmark, PHPBench in tools/phpbench, out of the package dependencies)
run on every pull request against the base commit, and the job fails on a regression of more than 20 %.
Versioning
Semantic Versioning. SpecVersion::CURRENT holds the version of the official URSSAF documentation implemented.
Other URSSAF packages
The same architecture, quality gate and conventions, one package per URSSAF API (overview: the-bearded-bear.com/open-source/urssaf):
| API | Package | Status |
|---|---|---|
| Tiers de prestations (immediate tax-credit advance) | thebeardedbear/urssaf-tiers-prestations |
Released (Packagist) |
| Attestations Vérification Code Sécurité (certificate verification) | thebeardedbear/urssaf-attestations-verification-code-securite |
Released (Packagist) |
| DPAE (pre-employment declaration) | thebeardedbear/urssaf-dpae |
Coming soon |
| Mobilité internationale (posting of workers abroad) | thebeardedbear/urssaf-mobilite-internationale |
Coming soon |
| Plateforme numérique (withholding of contributions by digital platforms) | thebeardedbear/urssaf-plateforme-numerique |
Released (Packagist) |
| Tierce Déclaration auto-entrepreneur | thebeardedbear/urssaf-tierce-declaration-auto-entrepreneur |
Released (Packagist) |
| Tierce Déclaration CESU | thebeardedbear/urssaf-tierce-declaration-cesu |
Released (Packagist) |
Professional support
This package is developed and maintained by The Bearded Bear. If you need help with an URSSAF integration, The Bearded Bear can help with:
- the URSSAF habilitation and homologation process (subscription, sandbox tests, move to production);
- integrating the package into your application (Symfony, Doctrine or framework-free);
- support with a guaranteed response time, including the follow-up of URSSAF API changes;
- custom developments on top of the package.
Project page and integration offer: the-bearded-bear.com/open-source/urssaf-tierce-declaration-paje.
Contributing and security
Contributions are welcome: see CONTRIBUTING.md and the Code of Conduct. The project's governance is described in GOVERNANCE.md and its direction in ROADMAP.md. Report vulnerabilities privately as described in SECURITY.md, never in a public issue.
License
MIT. See LICENSE. The software is provided "as is", without warranty of any kind.
The API specification summarised in docs/api-reference.md belongs to URSSAF; see the sources listed there.