This document provides instructions for integrating with the Penfold Payroll API using OAuth 2.0 with PKCE (Proof Key for Code Exchange).

Overview

The Penfold Payroll API allows third-party applications (such as payroll providers) to access and manage workplace pension data with user consent. This integration uses the OAuth 2.0 Authorization Code flow with PKCE for secure authentication and authorization.

Support

If your organisation uses Slack we can invite you to our Penfold Slack workspace where our engineers can support you with the integration build. If you don’t use Slack, please use the email address below for support.

• Payroll API docs: https://docs.getpenfold.dev
• Support email: [email protected]

Environments

This section defines environment-specific URLs that you will need to use in your integration. Make sure to use the correct URLs depending on which environment you are targeting.

1. Staging (sandbox)

The staging environment is a complete replica of the production environment, meaning you can use it to test your integration end-to-end.

• API_URL:
  • Purpose: Payroll API requests
  • Value: https://payroll-api.getpenfold.dev/v4
  • Example: $API_URL/v4/employers/:employer_id/employees
• AUTH_URL:
  • Purpose: OAuth2 flow requests
  • Value: https://workplace-platform-staging.auth.eu-west-1.amazoncognito.com
  • Example: $AUTH_URL/oauth2/token

2. Production (live)

Penfold will set you up on the production environment once you are confident your integration works correctly. Just let us know!

• API_URL: https://payroll-api.getpenfold.com/v4
• AUTH_URL: https://workplace-platform-prod.auth.eu-west-1.amazoncognito.com

Prerequisites

Before beginning integration you should:

1. Register with Penfold to receive your client_id and payrollApiOrganisationId