Penfold Payroll API v4

Create a Direct Debit session

Add MCP server to your AI tool

Allow AI tools and LLMs to interact with the API documentation portal through MCP.

MCP server URL

https://docs.getpenfold.dev/mcp

Standard setup for AI tools providing an mcp.json file

mcp.json 
{
  "Penfold Payroll API v4 MCP server": {
    "url": "https://docs.getpenfold.dev/mcp"
  }
}
Close
POST /employers/{employer_id}/direct-debit-sessions
O auth2 client credentials

Partner organisations only. A Payroll organisation calling this endpoint receives 405 Method Not Allowed.

Create a Direct Debit session for an employer. Returns a redirect_url that you open in the employer admin's browser so they can set up a Direct Debit mandate on Penfold's platform.

Path parameters

  • employer_id string Required
application/json

Body Required

  • return_url string Required

    The URL the employer is redirected to once the Direct Debit session reaches a terminal state. Must be HTTPS and must already be registered against your organisation.

Responses

  • 201 application/json

    Direct Debit session created successfully.

    Hide response attributes Show response attributes object
    • redirect_url string Required

      Full URL to send the employer admin to. Contains a Penfold-issued short-lived, one-time token. Do not construct or modify this URL.

    • expires_at string(date-time) Required

      ISO 8601 instant after which the session and redirect_url are invalid. Sessions expire 30 minutes after creation unless otherwise stated.
  • 400 application/json

    Bad request, the request is malformed or contains invalid data.

    Hide response attributes Show response attributes object
    • error string

      A descriptive error message.

    • validation_errors array[object]
      Hide validation_errors attributes Show validation_errors attributes object
      • field string Required

        The name of the field that failed validation.

      • message string Required

        A descriptive error message.
  • 401 application/json

    Unauthorized, the request requires authentication, and the provided credentials are either missing or incorrect.

    Hide response attribute Show response attribute object
    • error string

      A descriptive error message.
  • 404 application/json

    Employer not found, the specified employer_id does not match any employer your organisation can access.

    Hide response attribute Show response attribute object
    • error string

      A descriptive error message.
  • 405 application/json

    Method not allowed.

    Hide response attribute Show response attribute object
    • error string

      A descriptive error message.
  • 409 application/json

    Conflict — a Direct Debit session cannot be created because the employer is not eligible. This occurs when the employer does not pay by Direct Debit, when the employer is not held with Penfold, or when the employer's status is not MissingDD, Pending or Active.

    Hide response attribute Show response attribute object
    • error string

      A descriptive error message.
  • 500 application/json

    Internal server error

    Hide response attribute Show response attribute object
    • error string

      A descriptive error message.
POST /employers/{employer_id}/direct-debit-sessions 
curl \
 --request POST 'https://payroll-api.getpenfold.dev/v4/employers/{employer_id}/direct-debit-sessions' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --data '{
  "return_url": "https://partner.example.com/penfold/direct-debit-return"
}'
Request examples 
{
  "return_url": "https://partner.example.com/penfold/direct-debit-return"
}
Response examples (201) 
{
  "redirect_url": "https://platform.getpenfold.com/partner/direct-debit?token=eyJhbGciOiJIUzI1NiJ9...",
  "expires_at": "2026-05-06T10:35:00Z"
}
Response examples (400) 
{
  "error": "Bad request: invalid data provided.",
  "validation_errors": [
    {
      "field": "email",
      "message": "Email address is invalid."
    }
  ]
}
Response examples (401) 
{
  "error": "Bad request: invalid data provided."
}
Response examples (404) 
{
  "error": "Bad request: invalid data provided."
}
Response examples (405) 
{
  "error": "Bad request: invalid data provided."
}
Response examples (409) 
{
  "error": "Employer does not pay by Direct Debit"
}
{
  "error": "Employer is not set up for Direct Debit with Penfold"
}
{
  "error": "Employer is not eligible for Direct Debit setup - status must be 'MissingDD', 'Pending' or 'Active'"
}
Response examples (500) 
{
  "error": "Bad request: invalid data provided."
}