WPSmartPay

https://github.com/wpsmartpay/wp-smartpay
Admin
WPSmartPay is a WordPress payment plugin that simplifies accepting payments, sending professional...
Tokens:14,077
Snippets:187
Trust Score:5.9
Update:3 months ago
Show doc for...
Tokens:
Raw
### Add a custom settings tab

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/docs/admin-settings.md

A complete example demonstrating how to register a new tab, define sections, add settings fields, and implement custom sanitization.

```php
// 1. Add the tab
add_filter('smartpay_settings_tabs', function( $tabs ) {
    $tabs['my_plugin'] = __('My Plugin', 'smartpay');
    return $tabs;
});

// 2. Add sections to the tab
add_filter('smartpay_settings_sections_my_plugin', function( $sections ) {
    $sections['main'] = __('Main Settings', 'smartpay');
    $sections['advanced'] = __('Advanced Settings', 'smartpay');
    return $sections;
});

// 3. Add settings to the tab
add_filter('smartpay_settings_my_plugin', function( $settings ) {
    $settings['main'] = array(
        'my_text_field' => array(
            'id'   => 'my_text_field',
            'name' => __('Text Field', 'smartpay'),
            'desc' => __('Enter some text', 'smartpay'),
            'type' => 'text',
        ),
        'my_checkbox' => array(
            'id'   => 'my_checkbox',
            'name' => __('Enable Feature', 'smartpay'),
            'desc' => __('Check to enable this feature', 'smartpay'),
            'type' => 'checkbox',
        ),
    );

    $settings['advanced'] = array(
        'my_select' => array(
            'id'      => 'my_select',
            'name'    => __('Select Option', 'smartpay'),
            'desc'    => __('Choose an option', 'smartpay'),
            'type'    => 'select',
            'options' => array(
                'option1' => __('Option 1', 'smartpay'),
                'option2' => __('Option 2', 'smartpay'),
            ),
        ),
    );

    return $settings;
});

// 4. Add custom sanitization
add_filter('smartpay_settings_my_plugin-main_sanitize', function( $input ) {
    if (isset($input['my_text_field'])) {
        $input['my_text_field'] = sanitize_text_field($input['my_text_field']);
    }
    return $input;
});
```

--------------------------------

### Check for Smartpay installation

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/docs/initialize-plugin.md

Verify if the Smartpay plugin is active by checking for the existence of the SMARTPAY_VERSION constant.

```php
if (!defined('SMARTPAY_VERSION')) {
	// Admin notice that Smartpay is not installed
}
```

--------------------------------

### SMARTPAY_VERSION Constant

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/docs/initialize-plugin.md

A constant used to verify if the Smartpay plugin is installed and active.

```APIDOC
## Constant: SMARTPAY_VERSION

### Description
Check if the `SMARTPAY_VERSION` constant is defined to determine if Smartpay is currently installed.

### Usage Example
```php
if (!defined('SMARTPAY_VERSION')) {
	// Admin notice that Smartpay is not installed
}
```
```

--------------------------------

### Render Gateway-Specific Receipt Content

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/docs/payment.md

Triggered during receipt rendering for specific gateways. This example demonstrates outputting a PayPal transaction ID.

```php
add_action('smartpay_payment_paypal_receipt', function( $payment ) {
    echo '<p>PayPal Transaction: ' . esc_html($payment->transaction_id) . '</p>';
});
```

--------------------------------

### PHP File Security Header

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/CLAUDE.md

Mandatory security check included at the start of every PHP file to prevent direct access.

```php
defined('ABSPATH') || exit;
```

--------------------------------

### smartpay_loaded / smartpay_init

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/docs/initialize-plugin.md

WordPress actions fired during the plugin boot process to allow developers to hook into Smartpay initialization.

```APIDOC
## Action: smartpay_loaded / smartpay_init

### Description
These actions are fired during the WordPress boot process. `smartpay_loaded` fires on `plugins_loaded`, and `smartpay_init` fires on `init`.

### Usage Example
```php
add_action('smartpay_loaded', function() {
    // Early bootstrap hooks.
});
```
```

--------------------------------

### Hook into specific integration load

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/docs/integrations.md

Executes logic after a specific integration namespace has finished booting.

```php
add_action('smartpay_integration_mailchimp_loaded', function() {
    // Initialize mapping, etc.
});
```

--------------------------------

### Hook into all integrations load

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/docs/integrations.md

Executes logic after all available integrations have been processed.

```php
add_action('smartpay_integrations_loaded', function() {
    // Post-load tasks.
});
```

--------------------------------

### Handle product lifecycle events

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/docs/products.md

Hooks into product creation, updates, or deletions to perform secondary tasks like indexing.

```php
add_action('smartpay_product_created', function( $product ) {
    // Index product in search service.
});
```

--------------------------------

### Execute logic before download delivery

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/docs/downloads.md

Triggered immediately before the file is sent to the browser, suitable for logging or watermarking.

```php
add_action('smartpay_before_download_delivery', function( $args, $validation, $payment, $product, $file ) {
    // Add logging, watermarking, or counter updates.
}, 10, 5);
```

--------------------------------

### smartpay_integration_{namespace}_loaded

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/docs/integrations.md

An action hook that fires after a specific integration namespace has been successfully booted.

```APIDOC
## Action: smartpay_integration_{namespace}_loaded

### Description
Fires after an active integration namespace is booted.

### Usage
```php
add_action('smartpay_integration_mailchimp_loaded', function() {
    // Initialize mapping, etc.
});
```
```

--------------------------------

### Handle invalid product for download

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/docs/downloads.md

Triggered when the requested product is invalid or the user lacks permission to download it.

```php
add_action('smartpay_download_product_invalid', function( $args, $validation, $payment, $product ) {
    // Handle invalid product download attempt.
}, 10, 4);
```

--------------------------------

### smartpay_integrations_loaded

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/docs/integrations.md

An action hook that fires once all system integrations have been processed.

```APIDOC
## Action: smartpay_integrations_loaded

### Description
Fires after all integrations have been processed.

### Usage
```php
add_action('smartpay_integrations_loaded', function() {
    // Post-load tasks.
});
```
```

--------------------------------

### Hook into Smartpay loading

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/docs/initialize-plugin.md

Use the smartpay_loaded action to execute code during the early bootstrap phase of the plugin.

```php
add_action('smartpay_loaded', function() {
    // Early bootstrap hooks.
});
```

--------------------------------

### Handle download access denial

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/docs/downloads.md

Triggered when download link validation fails due to invalid tokens or permissions.

```php
add_action('smartpay_download_access_denied', function( $args, $validation ) {
    // Log abuse attempts.
}, 10, 2);
```

--------------------------------

### Handle User Creation

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/docs/customers.md

Triggered after a WordPress user is programmatically created for a payer. Use this to assign roles or trigger welcome sequences.

```php
add_action('smartpay_customer_user_created', function( $user, $payment ) {
    // Assign role, send welcome sequence, etc.
}, 10, 2);
```

--------------------------------

### Internationalization String Formatting

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/CLAUDE.md

Demonstrates the correct way to handle translated strings with variables using sprintf to avoid concatenation.

```php
// ❌ Wrong
echo __('Hello', 'smartpay') . ' ' . $name;
// ✅ Correct
printf( esc_html__( 'Hello %s', 'smartpay' ), esc_html( $name ) );
```

--------------------------------

### GoalProgress Block File Structure

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/resources/form-builder/blocks/GoalProgress/PLAN.md

Lists the required file structure for the new GoalProgress block within the form builder.

```text
resources/form-builder/blocks/GoalProgress/
├── index.js        registerBlockType('smartpay-form/goal-progress') + supports + attrs
├── edit.js         mock progress preview + InspectorControls (bar/track color, height, labels)
├── save.js         RETURN null-ish placeholder wrapper with data-attrs (dynamic block)
└── editor.scss / style.scss   (bar, track, fill animation, count typography)

resources/form-builder/blocks/index.js   ← import GoalProgress, add to smartPayBlocks[]
```

--------------------------------

### Required System Edits

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/resources/form-builder/blocks/GoalProgress/PLAN.md

Outlines the necessary modifications to existing PHP and JS files to integrate the GoalProgress block.

```php
app/Modules/NativeForm/NativeForm.php  (or a new GoalProgress render class)
  - add_filter('render_block_smartpay-form/goal-progress', renderGoalProgress, 10, 2)
    → server-renders live progress into the block's saved wrapper using
      smartpay_calculate_goal_progress( current form id ) + the block's style attrs.
  - Resolve form id: the block renders inside the form CPT content; use
    get_the_ID() / the $post_id already in template scope (pass via filter closure).
resources/views/native-form-embed.php
  - Remove the auto-rendered static goal block (37-72) — now author-placed.
  - Fallback: if goal.enabled && form has NO goal-progress block, keep rendering
    the legacy bar at the top (back-compat).
resources/form-builder/blocks/index.js
  - Optionally register a "Minimal" / "Card" block style.
```

--------------------------------

### Read Goal Configuration in Editor

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/resources/form-builder/blocks/GoalProgress/PLAN.md

Retrieves goal settings from form meta data within the block editor.

```javascript
const [ meta ] = useEntityProp('postType','smartpay_form','meta')
const goal = JSON.parse(JSON.parse(meta._smartpay_settings||'{}').goal||'{}')...
```

--------------------------------

### Apply global settings sanitization

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/docs/admin-settings.md

Implement a general sanitization filter that runs for all settings fields.

```php
add_filter('smartpay_settings_sanitize', function( $value, $key ) {
    // Apply custom sanitization to all settings
    if ($key === 'special_field') {
        return wp_kses_post($value);
    }
    return $value;
}, 10, 2);
```

--------------------------------

### Hook into payment creation

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/docs/payment.md

Use this action to perform post-creation tasks like sending emails or tracking analytics after a payment record is saved.

```php
add_action('smartpay_payment_created', function( $payment ) {
    // Notify services, Queue receipt email, analytics tracking, etc.
});
```

--------------------------------

### Hook into PayPal subscription payment processing

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/docs/not-included.md

Use this action to add custom trial periods or metadata during the PayPal subscription payment preparation.

```php
add_action('smartpay_paypal_subscription_process_payment', function( $payment, $paymentData ) {
    // Add custom trial or meta.
}, 10, 2);
```

--------------------------------

### Add a section to a settings tab

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/docs/admin-settings.md

Define a new section within an existing tab, such as the general settings tab.

```php
add_filter('smartpay_settings_sections_general', function( $sections ) {
    $sections['advanced'] = __('Advanced Options', 'smartpay');
    return $sections;
});
```

--------------------------------

### Hook into settings save action

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/docs/admin-settings.md

Use this action to execute custom logic after settings are saved. It provides access to the sanitized output, raw input, and the current tab and section context.

```php
add_action('smartpay_settings_saved', function( $output, $input, $tab, $section ) {
    // React to settings changes.
}, 10, 4);
```

--------------------------------

### Sync Pricing Blocks to Post Meta

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/resources/form-builder/blocks/PricingField/PLAN.md

Collects pricing block attributes during post save and stores them as a JSON-encoded string in the _smartpay_amounts meta key.

```php
$blocks = parse_blocks( $post->post_content );
$amounts = []; // walk blocks, collect smartpay/pricing + inner smartpay/pricing-option attrs
// each → ['key','label','amount','billing_type','billing_period','setup_fee','billing_cycle', ...]
update_post_meta( $post_id, '_smartpay_amounts', wp_json_encode( $amounts ) );
```

--------------------------------

### Add a custom settings tab

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/docs/admin-settings.md

Register a new tab in the Smartpay settings interface by filtering the tabs array.

```php
add_filter('smartpay_settings_tabs', function( $tabs ) {
    $tabs['my_custom_tab'] = __('My Custom Tab', 'smartpay');
    return $tabs;
});
```

--------------------------------

### Register custom settings fields

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/docs/admin-settings.md

Add new fields to a specific settings tab by defining the field structure in the settings array.

```php
add_filter('smartpay_settings_general', function( $settings ) {
    $settings['main']['my_custom_setting'] = array(
        'id'   => 'my_custom_setting',
        'name' => __('My Custom Setting', 'smartpay'),
        'desc' => __('Description of my setting', 'smartpay'),
        'type' => 'text',
    );
    return $settings;
});
```

--------------------------------

### Filter product purchasability

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/docs/products.md

Determines if a product can be purchased based on its status or other criteria.

```php
add_filter('smartpay_product_is_purchasable', function( $is_purchasable, $product ) {
    return $product->status === 'publish' ? $is_purchasable : false;
}, 10, 2);
```

--------------------------------

### Display WordPress Admin Notices

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/UI_GUIDELINES.md

PHP snippets for rendering standard WordPress admin notices for success, error, warning, and information messages.

```php
// Success
echo '<div class="notice notice-success is-dismissible"><p>' .
     esc_html__( 'Settings saved.', 'smartpay' ) . '</p></div>';

// Error
echo '<div class="notice notice-error"><p>' .
     esc_html__( 'Something went wrong.', 'smartpay' ) . '</p></div>';

// Warning
echo '<div class="notice notice-warning"><p>' .
     esc_html__( 'Please review.', 'smartpay' ) . '</p></div>';

// Info
echo '<div class="notice notice-info"><p>' .
     esc_html__( 'Tip: ...', 'smartpay' ) . '</p></div>';
```

--------------------------------

### Add custom submenu page via smartpay_admin_add_menu_items

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/docs/admin-settings.md

Use this action to register custom submenu pages under the SmartPay admin menu after default menus are initialized.

```php
add_action('smartpay_admin_add_menu_items', function() {
    add_submenu_page('smartpay', 'Reports', 'Reports', 'manage_options', 'smartpay-reports', function() {
        echo '<div class="wrap"><h1>Reports</h1></div>';
    });
}, 20);
```

--------------------------------

### smartpay_after_setting_output

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/docs/admin-settings.md

Filter to modify the generated HTML of a setting field before it is rendered.

```APIDOC
## Filter: smartpay_after_setting_output

### Description
Allows modification of the generated field HTML before output.

### Parameters
- **$html** (string) - Required - The generated HTML for the field.
- **$args** (array) - Required - Field arguments.

### Example
```php
add_filter('smartpay_after_setting_output', function( $html, $args ) {
    if ($args['id'] === 'special_field') {
        $html .= '<div class="custom-help">Additional help text</div>';
    }
    return $html;
}, 10, 2);
```
```

--------------------------------

### Hook into payment processing

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/docs/payment.md

Use this action to inspect or modify payment data before the processing logic begins.

```php
add_action('smartpay_before_payment_processing', function( $payment_data ) {
    // Inspect or modify pending payment data, log, etc.
});
```

--------------------------------

### Implement WordPress Admin Buttons

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/UI_GUIDELINES.md

Standard button classes for primary, secondary, destructive, and disabled states in the WordPress admin area.

```html
<!-- Primary action -->
<button class="button button-primary">Save Changes</button>

<!-- Secondary action -->
<button class="button">Cancel</button>

<!-- Destructive action -->
<button class="button button-link-delete">Delete</button>

<!-- Disabled state -->
<button class="button button-primary" disabled>Processing...</button>
```

--------------------------------

### Inject content into product modal

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/docs/products.md

Adds custom HTML content within the modal checkout UI.

```php
add_action('smartpay_product_modal_popup_content', function( $product ) {
    echo '<p class="text-muted">Secure checkout</p>';
});
```

--------------------------------

### Check Pro Status Helper

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/resources/form-builder/blocks/PricingField/PLAN.md

Use this helper function to determine if the Pro version is active. It relies on the 'smartpay_is_pro_active' filter.

```php
function smartpay_is_pro_active(): bool {
  return (bool) apply_filters( 'smartpay_is_pro_active', false );
}
```

--------------------------------

### Handle Form Lifecycle Actions

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/docs/forms.md

Use these hooks to trigger custom logic when a form is created, updated, or deleted in the admin panel.

```php
add_action('smartpay_form_updated', function( $form ) {
    // Sync form fields to CRM.
});
```

--------------------------------

### Extend Customer Dashboard

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/docs/customers.md

Hooks for adding custom navigation links and corresponding content panes to the customer dashboard.

```php
add_action('smartpay_customer_dashboard_tab_link', function() {
    echo '<a class="nav-link mx-2 px-4" data-toggle="pill" href="#mytab" role="tab">My Tab</a>';
});

add_action('smartpay_customer_dashboard_tab_content', function( $customer, $payments ) {
    echo '<div class="tab-pane fade" id="mytab" role="tabpanel">Hello!</div>';
}, 10, 2);
```

--------------------------------

### Settings Page Template Structure

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/UI_GUIDELINES.md

Use this structure for admin settings pages to maintain consistency with the WordPress dashboard. Ensure the nav-tab-wrapper is used for tabbed navigation and the card class for form containers.

```php
<div class="wrap">
    <h1><?php echo esc_html( get_admin_page_title() ); ?></h1>

    <nav class="nav-tab-wrapper">
        <a href="?page=smartpay&tab=general"
           class="nav-tab <?php echo $active === 'general' ? 'nav-tab-active' : ''; ?>">
            <?php esc_html_e( 'General', 'smartpay' ); ?>
        </a>
        <a href="?page=smartpay&tab=gateways"
           class="nav-tab <?php echo $active === 'gateways' ? 'nav-tab-active' : ''; ?>">
            <?php esc_html_e( 'Gateways', 'smartpay' ); ?>
        </a>
    </nav>

    <div class="card">
        <form method="post" action="options.php">
            <?php
            settings_fields( 'smartpay_settings' );
            do_settings_sections( 'smartpay_settings' );
            submit_button();
            ?>
        </form>
    </div>
</div>
```

--------------------------------

### Enable Pro Features via Filter

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/resources/form-builder/blocks/PricingField/PLAN.md

Used in the Pro service provider to override the Pro status check.

```php
add_filter( 'smartpay_is_pro_active', '__return_true' );
```

--------------------------------

### Server-Side Block Rendering

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/resources/form-builder/blocks/GoalProgress/PLAN.md

Filters the block output to inject dynamic progress data into the saved wrapper.

```php
function ( string $content, array $block ): string {
    $form_id = get_the_ID();                 // form CPT being rendered
    if ( ! $form_id || ! function_exists('smartpay_calculate_goal_progress') ) return $content;
    $p = smartpay_calculate_goal_progress( (int) $form_id );   // current/target/percentage/goal_reached/type
    // Build bar + counts + message inner HTML honoring the data-* flags + template,
    // injecting into the saved wrapper. ESCAPE every value (esc_html / esc_attr).
    return $rendered;     // wrapper kept, inner filled
}
```

--------------------------------

### Pro License Activation Filter

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/resources/form-builder/blocks/PricingField/PLAN.md

Registers the Pro version as active within the SmartPay Pro service provider.

```php
SmartPayProServiceProvider::boot() (inside valid-licence block)
  add_filter('smartpay_is_pro_active', '__return_true');
```

--------------------------------

### Filter currency list

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/docs/payment.md

Add or modify currencies available within the system.

```php
add_filter('smartpay_currencies', function( $currencies ) {
    $currencies['XYZ'] = ['name' => 'Example', 'symbol' => '¤'];
    return $currencies;
});
```

--------------------------------

### Register Goal Progress Block

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/resources/form-builder/blocks/GoalProgress/PLAN.md

Registers the 'smartpay-form/goal-progress' block with custom attributes for fundraising goal tracking and visual styling.

```javascript
registerBlockType('smartpay-form/goal-progress', {
  title: 'Goal Progress',
  description: 'Shows fundraising / sales goal progress. Configure the goal in Form Settings → Goal.',
  icon: 'chart-bar',
  category: 'smartpay',
  keywords: ['goal', 'progress', 'fundraising', 'target', 'thermometer'],
  supports: {
    anchor: true,
    html: false,
    multiple: false,
    reusable: false,
    align: ['wide', 'full'],
    color: { background: true, text: true, gradients: true,
             __experimentalDefaultControls: { text: true } },
    typography: { fontSize: true, lineHeight: true, fontWeight: true,
                  __experimentalDefaultControls: { fontSize: true } },
    spacing: { padding: true, margin: ['top','bottom'], blockGap: true,
               __experimentalDefaultControls: { padding: true } },
    __experimentalBorder: { color: true, radius: true, style: true, width: true },
  },
  attributes: {
    // display toggles
    showBar:        { type: 'boolean', default: true },
    showCounts:     { type: 'boolean', default: true },   // "12 of 100 sold"
    showPercentage: { type: 'boolean', default: true },
    showMessage:    { type: 'boolean', default: true },   // goalMetMessage when reached
    // labels (config target/type still come from GoalPanel)
    progressTemplate: { type: 'string', default: '{current} of {target} {unit}' },
    // bar styling (not covered by native supports)
    barColor:       { type: 'string', default: '' },      // fill
    trackColor:     { type: 'string', default: '' },      // background of track
    barHeight:      { type: 'string', default: '12px' },
    barRadius:      { type: 'string', default: '999px' },
    // editor-only mock
    previewPercent: { type: 'number', default: 35 },
    style:          { type: 'object' },
  },
  edit, save,
})
```

--------------------------------

### Define Custom CSS Variables and Status Colors

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/UI_GUIDELINES.md

CSS definitions for WordPress admin theme variables and specific status color classes for SmartPay components.

```css
/* Use WordPress admin color scheme CSS variables */
--wp-admin-theme-color: #2271b1;
--wp-admin-theme-color-darker-10: #135e96;
--wp-admin-theme-color-darker-20: #043959;

/* Standard status colors */
.smartpay-status-active   { color: #00a32a; }
.smartpay-status-paused   { color: #dba617; }
.smartpay-status-expired  { color: #d63638; }
.smartpay-status-pending  { color: #2271b1; }
```

--------------------------------

### Handle Cancelled Payments

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/docs/payment.md

Triggered when a payment transitions to a cancelled state. Use this to revoke access or restore inventory.

```php
add_action('smartpay_payment_cancelled', function( $payment ) {
    // Revoke access, notify user, restore inventory.
});
```

--------------------------------

### Handle invalid payment for download

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/docs/downloads.md

Triggered when the payment associated with a download request is invalid or incomplete.

```php
add_action('smartpay_download_payment_invalid', function( $args, $validation, $payment ) {
    // Notify customer or support.
}, 10, 3);
```

--------------------------------

### Customize IP Resolution with smartpay_get_ip

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/docs/payment.md

Use this filter to override the default IP address resolution logic. Ensure the server environment provides the expected headers like HTTP_X_REAL_IP.

```php
add_filter('smartpay_get_ip', function( $ip ) {
    return $ip === '127.0.0.1' ? ($_SERVER['HTTP_X_REAL_IP'] ?? $ip) : $ip;
});
```

--------------------------------

### Save Block Shell

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/resources/form-builder/blocks/GoalProgress/PLAN.md

Generates the static wrapper for the block in save.js, passing configuration via data attributes and CSS variables.

```jsx
const blockProps = useBlockProps.save({
  className: 'smartpay-goal-progress',
  style: { '--sp-bar': barColor, '--sp-track': trackColor,
           '--sp-bar-h': barHeight, '--sp-bar-r': barRadius },
  'data-show-bar': showBar ? '1' : '0',
  'data-show-counts': showCounts ? '1' : '0',
  'data-show-percentage': showPercentage ? '1' : '0',
  'data-show-message': showMessage ? '1' : '0',
  'data-template': progressTemplate,
})
return <div {...blockProps} />   // server fills inner markup
```

--------------------------------

### Pricing Option Save Markup

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/resources/form-builder/blocks/PricingField/PLAN.md

HTML structure for the pricing option radio card used in the save function.

```html
<label class="smartpay-pricing-option">
  <input type="radio" name="smartpay_amount_key" value="{key}" class="sr-only"
         data-amount="{amount}" data-billing-type="{billing_type}">
  <span class="smartpay-pricing-option__label">{label}</span>
  <span class="smartpay-pricing-option__amount">{formatted amount}</span>
  <span class="smartpay-pricing-option__check" aria-hidden="true"></span>
</label>
```

--------------------------------

### Define Pricing Block Structure

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/resources/form-builder/blocks/PricingField/PLAN.md

The pricing block follows a parent-child relationship where the parent container holds multiple pricing options.

```text
smartpay/pricing            (PARENT — container, custom-amount toggle)
└── smartpay/pricing-option (CHILD  — one selectable price card)   × N
```

--------------------------------

### Modify Available Gateways with smartpay_get_available_payment_gateways

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/docs/payment.md

Use this filter to add or remove payment gateways from the settings UI. The array keys should correspond to the gateway identifier.

```php
add_filter('smartpay_get_available_payment_gateways', function( $available ) {
    $available['newpay'] = ['label' => 'NewPay'];
    return $available;
});
```

--------------------------------

### Inject Content into Checkout Form

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/docs/forms.md

Use these hooks to inject custom HTML or logic before or after the payment form and its submit button.

```php
add_action('before_smartpay_payment_form', function( $form ) {
    echo '<div class="notice">Special promo available today!</div>';
});
```

--------------------------------

### Filter the complete settings structure

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/docs/admin-settings.md

Modify the entire settings array before it is rendered or processed.

```php
add_filter('smartpay_settings', function( $settings ) {
    // Modify the entire settings structure
    return $settings;
});
```

--------------------------------

### Filter available integrations

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/docs/integrations.md

Modifies the list of registered integrations by adding or removing entries.

```php
add_filter('smartpay_integrations', function( $integrations ) {
    $integrations['mygateway'] = [ 'name' => 'My Gateway', 'manager' => My\Gateway::class, 'type' => 'pro', 'categories' => ['Payment Gateway'] ];
    return $integrations;
});
```

--------------------------------

### Handle AJAX gateway payments

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/docs/payment.md

Triggered when an AJAX-based gateway initiates a charge.

```php
add_action('smartpay_stripe_ajax_process_payment', function( $paymentData ) {
    // Handle Stripe AJAX payment initiation.
});
```

--------------------------------

### Handle Completed Payments

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/docs/payment.md

Triggered when a payment status transitions to completed. Use this to fulfill orders or grant access.

```php
add_action('smartpay_payment_completed', function( $payment ) {
    // Fulfill order, grant access, license activation, etc.
});
```

--------------------------------

### Localize Pro Status to Editor

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/resources/form-builder/blocks/PricingField/PLAN.md

Passes the Pro status and upgrade URL to the form builder script via wp_localize_script.

```php
wp_localize_script( <form-builder handle>, 'smartpayFormBuilder', [ 'isPro' => smartpay_is_pro_active(), 'upgradeUrl' => 'https://wpsmartpay.com/pricing' ] );
```

--------------------------------

### Handle non-AJAX gateway payments

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/docs/payment.md

Triggered when a non-AJAX gateway initiates a charge, useful for immediate payment status updates.

```php
add_action('smartpay_free_process_payment', function( $paymentData ) {
    // Mark free orders as paid immediately.
});
```

--------------------------------

### Filter payment gateways

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/docs/payment.md

Register custom payment gateways by adding them to the gateways array.

```php
add_filter('smartpay_gateways', function( $gateways ) {
    $gateways['mygateway'] = [ 'admin_label' => 'My Gateway', 'checkout_label' => 'My Gateway', 'gateway_icon' => 'https://...' ];
    return $gateways;
});
```

--------------------------------

### Pricing Block InnerBlocks Configuration

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/resources/form-builder/blocks/PricingField/PLAN.md

Configures the inner blocks for the pricing component, restricting children to pricing-option blocks.

```javascript
const inner = useInnerBlocksProps(blockProps, {
  allowedBlocks: ['smartpay/pricing-option'],
  template: [['smartpay/pricing-option', { label: 'Basic', amount: 100 }]],
  defaultBlock: {
    name: 'smartpay/pricing-option',
    attributesToCopy: ['billing_type','billing_period','className','style'],
  },
  directInsert: true,              // "+" appender adds option directly
  orientation: 'horizontal',
})
```

--------------------------------

### Register Pricing Parent Block

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/resources/form-builder/blocks/PricingField/PLAN.md

Defines the parent pricing block with custom attributes for amount handling and column layout.

```javascript
registerBlockType('smartpay/pricing', {
  title: 'Pricing', category: 'smartpay', icon: 'money-alt',
  apiVersion: 3,
  attributes: {
    enableCustomAmount: { type: 'boolean', default: false },
    customAmountLabel:  { type: 'string',  default: 'Enter custom amount' },
    columns:            { type: 'number',  default: 2 },
  },
  // allowedBlocks via InnerBlocks prop
})
```

--------------------------------

### SubmitButton Save Implementation

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/resources/form-builder/blocks/SubmitButton/PLAN.md

Defines the frontend markup for the SubmitButton, ensuring the mandatory smartpay-form-pay-now class is applied and button type is set to button to prevent native form submission.

```jsx
const blockProps = useBlockProps.save({
  className: classnames('btn smartpay-form-pay-now', {
    'is-full-width': fullWidth,
    [`has-text-align-${textAlign}`]: textAlign,
    [`has-icon-${iconPosition}`]: !!icon,
  }),
  style: width ? { width: `${width}%` } : undefined,
})
return (
  <button type="button" {...blockProps}>
    {icon && iconPosition === 'left'  && <Icon … className="sp-btn-icon" />}
    <RichText.Content tagName="span" value={label} />
    {icon && iconPosition === 'right' && <Icon … className="sp-btn-icon" />}
  </button>
)
```

--------------------------------

### Handle Customer Updates

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/docs/customers.md

Triggered after a customer profile is updated via the REST API. Useful for syncing data to external CRM systems.

```php
add_action('smartpay_customer_updated', function( $customer, $requestData ) {
    // Sync to external CRM.
}, 10, 2);
```

--------------------------------

### Define Goal Progress Block Name

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/resources/form-builder/blocks/GoalProgress/PLAN.md

The unique identifier for the block, restricted to a single instance per form.

```text
smartpay-form/goal-progress   (single block, multiple:false)
```

--------------------------------

### Modify settings array via smartpay_get_settings

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/docs/admin-settings.md

Use this filter to inject or modify values within the SmartPay settings array during the loading process.

```php
add_filter('smartpay_get_settings', function( $settings ) {
    $settings['feature_flag'] = true;
    return $settings;
});
```

--------------------------------

### Handle Failed Payments

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/docs/payment.md

Triggered when a payment fails. Use this to alert support teams.

```php
add_action('smartpay_payment_failed', function( $payment ) {
    // Alert support team.
});
```

--------------------------------

### Register Pricing Option Child Block

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/resources/form-builder/blocks/PricingField/PLAN.md

Defines the child pricing option block with attributes for billing and pricing details.

```javascript
registerBlockType('smartpay/pricing-option', {
  title: 'Pricing Option', parent: ['smartpay/pricing'],
  apiVersion: 3,
  supports: { splitting: true, reusable: false },
  attributes: {
    key:            { type: 'string' },          // generated, stable
    label:          { type: 'string', default: '' },
    amount:         { type: 'number', default: 0 },
    billing_type:   { type: 'string', default: 'One Time' },
    billing_period: { type: 'string', default: 'month' },  // pro
    setup_fee:      { type: 'number', default: 0 },        // pro
    billing_cycle:  { type: 'number' },                    // pro
  },
})
```

--------------------------------

### Handle PayPal IPN notifications

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/docs/not-included.md

Use this action to verify and reconcile payments when receiving IPN notifications for specific transaction types.

```php
add_action('smartpay_paypal_web_accept', function( $ipn, $payment_id ) {
    // Verify and reconcile payment.
}, 10, 2);
```

--------------------------------

### Legacy Submit Button Fallback

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/resources/form-builder/blocks/SubmitButton/PLAN.md

Checks for the existence of the submit button block and provides a fallback for legacy forms.

```php
$has_submit_block = has_block( 'smartpay-form/submit-button', $form_post );
// echo do_blocks( $body );  ← renders the block button when present
if ( ! $has_submit_block ) {
    // legacy fallback: emit the old static button using settings.pay_button_label
}
```

--------------------------------

### Integration Filter Hooks

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/docs/integrations.md

Filter hooks used to customize available integrations, override manager resolution, and alter the not-installed message.

```APIDOC
## Filters: smartpay_integrations, smartpay_integration_manager, smartpay_integration_get_not_installed_message

### Description
Customize available integrations, override manager resolution, and alter the not-installed message.

### Usage
```php
add_filter('smartpay_integrations', function( $integrations ) {
    $integrations['mygateway'] = [ 'name' => 'My Gateway', 'manager' => My\Gateway::class, 'type' => 'pro', 'categories' => ['Payment Gateway'] ];
    return $integrations;
});
```
```

--------------------------------

### Override PayPal endpoint URI

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/docs/not-included.md

Use this filter to resolve or override the PayPal sandbox or live endpoint URL.

```php
add_filter('smartpay_paypal_uri', function( $uri, $ssl, $ipn ) {
    return $uri; // Override if needed.
}, 10, 3);
```

--------------------------------

### Sanitize values by field type

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/docs/admin-settings.md

Apply specific sanitization rules based on the field type, such as text fields.

```php
add_filter('smartpay_settings_sanitize_text', function( $value, $key ) {
    // Custom sanitization for text fields
    return sanitize_text_field($value);
}, 10, 2);
```

--------------------------------

### Define Submit Button Block Name

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/resources/form-builder/blocks/SubmitButton/PLAN.md

The block identifier for the submit button, configured to allow only one instance per form.

```text
smartpay-form/submit-button   (single block, multiple:false, one per form)
```

--------------------------------

### Sanitize input for a specific tab and section

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/docs/admin-settings.md

Apply custom sanitization logic to inputs submitted within a specific tab and section combination.

```php
add_filter('smartpay_settings_general-main_sanitize', function( $input ) {
    // Custom sanitization for general tab, main section
    if (isset($input['my_field'])) {
        $input['my_field'] = sanitize_text_field($input['my_field']);
    }
    return $input;
});
```

--------------------------------

### smartpay_non_setting_types

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/docs/admin-settings.md

Filter to declare field types that should not be treated as persistent settings.

```APIDOC
## Filter: smartpay_non_setting_types

### Description
Allows developers to register field types that are not saved as persistent settings.

### Parameters
- **$types** (array) - Required - Array of non-setting field types.

### Example
```php
add_filter('smartpay_non_setting_types', function( $types ) {
    $types[] = 'custom_display_only';
    return $types;
});
```
```

--------------------------------

### SubmitButton Block Registration

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/resources/form-builder/blocks/SubmitButton/PLAN.md

Registers the 'smartpay-form/submit-button' block with specific support for alignment, color, typography, and spacing controls.

```javascript
registerBlockType('smartpay-form/submit-button', {
  title: 'Pay Button',
  description: 'The form's pay / submit button. One per form.',
  icon: 'button',           // @wordpress/icons
  category: 'smartpay',
  keywords: ['pay', 'submit', 'button', 'checkout', 'buy'],
  supports: {
    anchor: true,
    html: false,
    multiple: false,        // one per form — replaces static button
    reusable: false,
    align: ['left', 'center', 'right', 'wide', 'full'],  // block alignment
    color: { background: true, text: true, gradients: true,
             __experimentalDefaultControls: { background: true, text: true } },
    typography: { fontSize: true, lineHeight: true, fontWeight: true, textTransform: true,
                  __experimentalDefaultControls: { fontSize: true } },
    spacing: { padding: true, margin: ['top','bottom'],
               __experimentalDefaultControls: { padding: true } },
    __experimentalBorder: { color: true, radius: true, style: true, width: true,
                            __experimentalDefaultControls: { radius: true } },
  },
  attributes: {
    label:         { type: 'string', default: 'Pay Now' },     // was pay_button_label
    width:         { type: 'number' },                          // 25/50/75/100 % preset, like core/button
    fullWidth:     { type: 'boolean', default: false },
    textAlign:     { type: 'string', default: 'center' },       // content alignment inside button
    icon:          { type: 'string', default: '' },             // dashicon/svg slug from a small picker
    iconPosition:  { type: 'string', default: 'left' },         // left | right
    style:         { type: 'object' },                          // native supports serialize here
  },
  edit, save,
})
```

--------------------------------

### Modify PayPal redirect arguments

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/docs/not-included.md

Use this filter to inject custom query parameters into the PayPal redirect URL before the user is sent to the gateway.

```php
add_filter('smartpay_paypal_redirect_args', function( $args, $paymentData ) {
    $args['custom_param'] = 'value';
    return $args;
}, 10, 2);
```

--------------------------------

### Filter extra payment data

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/docs/payment.md

Modify the extra payload before it is saved to the payment model.

```php
add_filter('smartpay_payment_extra_data', function( $extra ) {
    $extra['utm'] = $_COOKIE['utm'] ?? [];
    return $extra;
});
```

--------------------------------

### Declare non-setting field types

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/docs/admin-settings.md

Use this filter to register field types that should not be saved as persistent settings.

```php
add_filter('smartpay_non_setting_types', function( $types ) {
    $types[] = 'custom_display_only';
    return $types;
});
```

--------------------------------

### smartpay_email_headers

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/docs/email.md

This filter allows developers to modify the email headers when SmartPay notifications are being generated.

```APIDOC
## Filter: smartpay_email_headers

### Description
Fires when building email headers for SmartPay notifications. This filter allows for the injection of custom headers such as Bcc or Reply-To.

### Parameters
- **$headers** (string) - The current email headers string.

### Example
```php
add_filter('smartpay_email_headers', function( $headers ) {
    return $headers . "\r\nBcc: accounting@example.com";
});
```
```

--------------------------------

### Modify field HTML output

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/docs/admin-settings.md

Use this filter to inject custom HTML or modify the output of a specific field before it is rendered.

```php
add_filter('smartpay_after_setting_output', function( $html, $args ) {
    if ($args['id'] === 'special_field') {
        $html .= '<div class="custom-help">Additional help text</div>';
    }
    return $html;
}, 10, 2);
```

--------------------------------

### Filter payment payload data

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/docs/payment.md

Use this filter to inject custom data into the normalized payment payload during the request building process.

```php
add_filter('smartpay_prepare_payment_data', function( $prepared, $_data ) {
    $prepared['extra']['source'] = 'landing-page-7';
    return $prepared;
}, 10, 2);
```

--------------------------------

### Modify email headers with smartpay_email_headers

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/docs/email.md

Use this filter to append custom headers, such as Bcc addresses, to outgoing SmartPay emails.

```php
add_filter('smartpay_email_headers', function( $headers ) {
    return $headers . "\r\nBcc: accounting@example.com";
});
```

--------------------------------

### Alter Payment Data with smartpay_get_additional_payment_data

Source: https://github.com/wpsmartpay/wp-smartpay/blob/master/docs/payment.md

Use this filter to inject or modify custom data fields into the payment object. This is useful for adding metadata like order notes or custom billing information.

```php
add_filter('smartpay_get_additional_payment_data', function( $paymentData ) {
    $paymentData['note'] = 'VIP order';
    return $paymentData;
});
```
Tokens:
Raw