---
title: "Hooks & Filters"
description: "Reference for the deliberate extension hooks exposed by Payment Page 1.5.3, with the source file and argument shape for each documented hook."
url: "https://docs.paymentpageplugin.com/advanced-configuration/hooks-and-filters/"
---
Payment Page exposes a small extension surface. Each entry below cites the source file so you can verify the argument signature against the exact plugin version you are running. Internal observability and test-only seams are intentionally not presented as public extension APIs.

## Filters

<a id="payment-page-register-post-type-payment-form-args"></a>

### `payment_page_register_post_type_payment_form_args`

Filters the `register_post_type` arguments used to register the `pp_payment_form` custom post type, before it's registered with WordPress.

*   **Fires in:** `app/PostTypes/Form.php`
*   **Arguments:** `array $args`

```php
add_filter( 'payment_page_register_post_type_payment_form_args', function ( $args ) {
    $args['menu_icon'] = 'dashicons-money-alt';
    return $args;
} );
```

<a id="payment-page-administration-form-field-map"></a>

### `payment_page_administration_form_field_map`

Filters the form-builder field map (Display, Pricing Plans, Payment Methods, Field Map, Actions on Submit, etc.) that powers the admin form-builder UI.

*   **Fires in:** `app/PostTypes/Form/FieldMap.php`
*   **Arguments:** `array $fields`

```php
add_filter( 'payment_page_administration_form_field_map', function ( $fields ) {
    // Inspect or augment the admin builder's field map.
    return $fields;
} );
```

<a id="payment-page-administration-dashboard"></a>

### `payment_page_administration_dashboard`

Filters the response payload returned by `GET /wp-json/payment-page/v1/administration/dashboard` — the data the admin SPA uses to render the gateway dashboard and Quick Setup steps.

*   **Fires in:** `app/PaymentGateway.php`
*   **Arguments:** `array $response`

```php
add_filter( 'payment_page_administration_dashboard', function ( $response ) {
    $response['custom_widget'] = [ 'title' => 'Hello from my plugin' ];
    return $response;
} );
```

<a id="payment-page-get-template"></a>

### `payment_page_get_template`

Filters the located template path before Payment Page renders one of its template parts.

*   **Fires in:** `app/Template.php`
*   **Arguments:** `string $located, string $template_name, array $args, string $template_path, string $default_path`

```php
add_filter( 'payment_page_get_template', function ( $located, $template_name ) {
    if ( 'single-pp_payment_form.php' === $template_name ) {
        return get_stylesheet_directory() . '/payment-page/single-pp_payment_form.php';
    }
    return $located;
}, 10, 2 );
```

<a id="payment-page-locate-template"></a>

### `payment_page_locate_template`

Filters the result of `locate_template` before Payment Page falls back to its bundled default.

*   **Fires in:** `app/Template.php`
*   **Arguments:** `string $template, string $template_name, string $template_path`

<a id="payment-page-template-path"></a>

### `payment_page_template_path`

Filters the relative template-path prefix Payment Page looks for inside a theme. Defaults to `payment-page/`.

*   **Fires in:** `app/Template.php`
*   **Arguments:** `string $template_path`

<a id="payment-page-update-settings"></a>

### `payment_page_update_settings`

Filters the settings array right before it's persisted to the `payment_page_settings` option.

*   **Fires in:** `app/Settings.php`
*   **Arguments:** `array $options`

```php
add_filter( 'payment_page_update_settings', function ( $options ) {
    // Force test-mode-only on a staging site.
    if ( defined( 'WP_ENVIRONMENT_TYPE' ) && 'staging' === WP_ENVIRONMENT_TYPE ) {
        $options['stripe_is_live'] = 0;
    }
    return $options;
} );
```

<a id="payment-page-stripe-payment-methods-administration"></a>

### `payment_page_stripe_payment_methods_administration`

Filters the Stripe payment-method definitions presented in the admin gateway settings (Cards, ACH Direct Debit through Stripe Financial Connections, SEPA Direct Debit, Apple Pay, Google Pay, Alipay, and WeChat Pay). Use this to hide a released method from the admin UI.

*   **Fires in:** `app/PaymentGateway/Stripe.php`
*   **Arguments:** `array $response`

<a id="payment-page-stripe-payment-methods-frontend"></a>

### `payment_page_stripe_payment_methods_frontend`

Filters the Stripe payment-method list returned to the front-end form (each entry has `id`, `name`, `payment_method`, `has_recurring_support`, etc.). Use this to suppress a method on a specific form context or to add front-end metadata.

*   **Fires in:** `app/PaymentGateway/Stripe.php`
*   **Arguments:** `array $response, array $active_payment_methods`

```php
add_filter( 'payment_page_stripe_payment_methods_frontend', function ( $methods, $active ) {
    return array_filter( $methods, function ( $m ) {
        return 'wechat' !== $m['id']; // Hide WeChat Pay on the front end.
    } );
}, 10, 2 );
```

<a id="payment-page-paypal-payment-methods-administration"></a>

### `payment_page_paypal_payment_methods_administration`

Filters the PayPal payment-method definitions in the admin gateway settings. In 1.5.3 only `standard_checkout` is registered and it is one-time only.

*   **Fires in:** `app/PaymentGateway/PayPal.php`
*   **Arguments:** `array $response`

<a id="payment-page-paypal-payment-methods-frontend"></a>

### `payment_page_paypal_payment_methods_frontend`

Filters the PayPal payment-method list returned to the front-end form.

*   **Fires in:** `app/PaymentGateway/PayPal.php`
*   **Arguments:** `array $response, array $active_payment_methods`

<a id="payment-page-form-templates"></a>

### `payment_page_form_templates`

Filters the payment-form setting template catalog returned to the builder. The plugin uses this hook to prepend its 10 bundled JSON templates to any valid templates returned by the public website endpoint.

*   **Fires in:** `app/API/PaymentPage.php`
*   **Arguments:** `array $templates`

<a id="payment-page-stripe-advanced-fraud-signals"></a>

### `payment_page_stripe_advanced_fraud_signals`

Controls the `advancedFraudSignals` option passed when Payment Page loads Stripe.js. It defaults to `false` in 1.5.3 to avoid cached-form failures in browsers that restrict third-party storage.

*   **Fires in:** `app/PaymentForm.php`
*   **Arguments:** `bool $enabled`

<a id="payment-page-force-universal-interface"></a>

### `payment_page_force_universal_interface`

Forces Payment Page's front-end assets to enqueue on the current request. Use this only when a custom renderer bypasses the plugin's shortcode, Elementor-widget, and singular-form detection.

*   **Fires in:** `app/Controller.php`
*   **Arguments:** `bool $should_enqueue`

## Actions

<a id="payment-page-before-template-part"></a>

### `payment_page_before_template_part`

Fires immediately before Payment Page renders one of its template parts.

*   **Fires in:** `app/Template.php`
*   **Arguments:** `string $template_name, string $template_path, string $located, array $args`

<a id="payment-page-after-template-part"></a>

### `payment_page_after_template_part`

Fires immediately after Payment Page renders one of its template parts.

*   **Fires in:** `app/Template.php`
*   **Arguments:** `string $template_name, string $template_path, string $located, array $args`

```php
add_action( 'payment_page_after_template_part', function ( $template_name, $template_path, $located, $args ) {
    // Append a tracking pixel after the success page renders.
}, 10, 4 );
```

<a id="payment-page-payment-received"></a>

### `payment_page_payment_received`

Fires after Payment Page accepts a one-time Stripe `payment_intent.succeeded`, an initial Stripe subscription `invoice.paid`, or a PayPal `PAYMENT.CAPTURE.COMPLETED` event and records the payment. Paid Stripe renewal invoices use the separate `payment_page_subscription_payment_received` action below.

*   **Fires in:** `app/RestAPI/Webhook.php`
*   **Arguments:** `array $request_data, array $gateway_args`
    *   `$gateway_args` is keyed by the gateway alias: `[ 'stripe' => $intent_data ]` or `[ 'paypal' => $capture_result ]`.

```php
add_action( 'payment_page_payment_received', function ( $request_data, $gateway_args ) {
    if ( isset( $gateway_args['stripe'] ) ) {
        error_log( 'Stripe payment received for form ' . ( $request_data['form_id'] ?? 'unknown' ) );
    }
}, 10, 2 );
```

<a id="payment-page-subscription-created"></a>

### `payment_page_subscription_created`

Fires after Payment Page accepts the initial Stripe subscription `invoice.paid` event and before `payment_page_payment_received` runs for that initial settlement. It does not fire for renewal invoices.

*   **Fires in:** `app/RestAPI/Webhook.php`
*   **Arguments:** `array $request_data, array $gateway_args` (with the `stripe` key)

<a id="payment-page-subscription-payment-received"></a>

### `payment_page_subscription_payment_received`

Fires once for an accepted paid renewal invoice after the initial subscription invoice has already settled.

*   **Fires in:** `app/RestAPI/Webhook.php`
*   **Arguments:** `PP_Model_Payments $payment, object $invoice`

<a id="payment-page-subscription-status-changed"></a>

### `payment_page_subscription_status_changed`

Fires for a Payment Page subscription's accepted `customer.subscription.created`, `customer.subscription.updated`, or `customer.subscription.deleted` event.

*   **Fires in:** `app/RestAPI/Webhook.php`
*   **Arguments:** `PP_Model_Payments $payment, string $event_type, object $subscription`

<a id="payment-page-subscription-payment-method-event"></a>

### `payment_page_subscription_payment_method_event`

Fires for an accepted `setup_intent.succeeded`, `setup_intent.setup_failed`, or `setup_intent.canceled` event associated with a Payment Page subscription checkout.

*   **Fires in:** `app/RestAPI/Webhook.php`
*   **Arguments:** `PP_Model_Payments $payment, string $event_type, object $setup_intent`

The 1.5.3 webhook effect ledger guards these actions against duplicate delivery of the same Stripe event. Code attached to an action must still be safe to retry if it returns control after performing an external side effect but before that completion can be recorded.

<a id="payment-page-fs-loaded"></a>

### `payment_page_fs_loaded`

Fires once the bundled Freemius SDK has finished loading. Use this if your add-on needs to run code that depends on `payment_page_fs()` being available.

*   **Fires in:** `app/ThirdPartyIntegration/Freemius.php`
*   **Arguments:** none

```php
add_action( 'payment_page_fs_loaded', function () {
    if ( payment_page_fs()->is_paying() ) {
        // Pro-only behavior.
    }
} );
```

* * *

If you need a hook that isn't in this list, [contact support](https://paymentpageplugin.com/support/) — the surface is intentionally small and we'd rather add a hook than have you patch core files.