WC_Payment_Gateway
extends WC_Settings_API
in package
WooCommerce Payment Gateway class.
Extended by individual payment gateways to handle payments.
Tags
Table of Contents
- $availability : string
- Available for all counties or specific.
- $chosen : bool
- Chosen payment method id.
- $countries : array<string|int, mixed>
- Countries this gateway is allowed for.
- $description : string
- Payment method description for the frontend.
- $enabled : string
- Yes or no based on whether the method is enabled.
- $errors : array<string|int, mixed>
- Validation errors.
- $form_fields : array<string|int, mixed>
- Form option fields.
- $has_fields : bool
- True if the gateway shows fields on the checkout.
- $icon : string
- Icon for the gateway.
- $id : string
- ID of the class extending the settings API. Used in option names.
- $max_amount : int
- Maximum transaction amount, zero does not define a maximum.
- $method_description : string
- Gateway description.
- $method_title : string
- Gateway title.
- $new_method_label : string
- Optional label to show for "new payment method" in the payment method/token selection radio selection.
- $order_button_text : string
- Set if the place order button should be renamed on selection.
- $pay_button_id : string
- Pay button ID if supported.
- $plugin_id : string
- The plugin ID. Used for option names.
- $settings : array<string|int, mixed>
- Setting values.
- $supports : array<string|int, mixed>
- Supported features such as 'default_credit_card_form', 'refunds'.
- $title : string
- Payment method title for the frontend.
- $view_transaction_url : string
- Optional URL to view a transaction.
- $data : array<string|int, mixed>
- The posted settings data. When empty, $_POST data will be used.
- $tokens : array<string|int, mixed>
- Contains a users saved tokens for this gateway.
- add_error() : mixed
- Add an error message for display in admin on save.
- add_payment_method() : array<string|int, mixed>
- Add payment method via account screen. This should be extended by gateway plugins.
- admin_options() : mixed
- Output the gateway settings screen.
- can_refund_order() : bool
- Can the order be refunded via this gateway?
- credit_card_form() : mixed
- Core credit card form which gateways can use if needed. Deprecated - inherit WC_Payment_Gateway_CC instead.
- display_errors() : mixed
- Display admin error messages.
- format_settings() : array<string|int, mixed>
- Format settings if needed.
- generate_checkbox_html() : string
- Generate Checkbox HTML.
- generate_color_html() : string
- Generate Color Picker Input HTML.
- generate_decimal_html() : string
- Generate Decimal Input HTML.
- generate_multiselect_html() : string
- Generate Multiselect HTML.
- generate_password_html() : string
- Generate Password Input HTML.
- generate_price_html() : string
- Generate Price Input HTML.
- generate_safe_text_html() : string
- Generates HTML for the 'safe_text' input type (mostly used for gateway-related settings).
- generate_select_html() : string
- Generate Select HTML.
- generate_settings_html() : string
- Generate Settings HTML.
- generate_text_html() : string
- Generate Text Input HTML.
- generate_textarea_html() : string
- Generate Textarea HTML.
- generate_title_html() : string
- Generate Title HTML.
- get_custom_attribute_html() : string
- Get custom attributes.
- get_description() : string
- Return the gateway's description.
- get_description_html() : string
- Get HTML for descriptions.
- get_errors() : mixed
- Get admin error messages.
- get_field_default() : string
- Get a fields default value. Defaults to "" if not set.
- get_field_key() : string
- Prefix key for settings.
- get_field_type() : string
- Get a fields type. Defaults to "text" if not set.
- get_field_value() : string
- Get a field's posted and validated value.
- get_form_fields() : array<string|int, mixed>
- Get the form fields after they are initialized.
- get_icon() : string
- Return the gateway's icon.
- get_method_description() : string
- Return the description for admin screens.
- get_method_title() : string
- Return the title for admin screens.
- get_new_payment_method_option_html() : mixed
- Displays a radio button for entering a new payment method (new CC details) instead of using a saved method.
- get_option() : string
- Get option from DB.
- get_option_key() : string
- Return the name of the option in the WP DB.
- get_pay_button_id() : string
- Return the gateway's pay button ID.
- get_post_data() : array<string|int, mixed>
- Returns the POSTed data, to be used to save the settings.
- get_return_url() : string
- Get the return url (thank you page).
- get_saved_payment_method_option_html() : string
- Gets saved payment method HTML from a token.
- get_title() : string
- Return the gateway's title.
- get_tokens() : array<string|int, mixed>
- Returns a users saved tokens for this gateway.
- get_tooltip_html() : string
- Get HTML for tooltips.
- get_transaction_url() : string
- Get a link to the transaction on the 3rd party gateway site (if applicable).
- has_fields() : bool
- Check if the gateway has fields on the checkout.
- init_form_fields() : mixed
- Initialise settings form fields.
- init_settings() : mixed
- Init settings for gateways.
- is_available() : bool
- Check if the gateway is available for use.
- needs_setup() : bool
- Return whether or not this gateway still requires setup to function.
- payment_fields() : mixed
- Default payment fields display. Override this in your gateway to customize displayed fields.
- process_admin_options() : bool
- Processes and saves options.
- process_payment() : array<string|int, mixed>
- Process Payment.
- process_refund() : bool|WP_Error
- Process refund.
- save_payment_method_checkbox() : mixed
- Outputs a checkbox for saving a new payment method to the database.
- saved_payment_methods() : mixed
- Grab and display our saved payment methods.
- set_current() : mixed
- Set as current gateway.
- set_post_data() : mixed
- Sets the POSTed data. This method can be used to set specific data, instead of taking it from the $_POST array.
- supports() : bool
- Check if a gateway supports a given feature.
- tokenization_script() : mixed
- Enqueues our tokenization script to handle some of the new form options.
- update_option() : bool
- Update a single option.
- validate_checkbox_field() : string
- Validate Checkbox Field.
- validate_decimal_field() : string
- Validate Decimal Field.
- validate_fields() : bool
- Validate frontend fields.
- validate_multiselect_field() : string|array<string|int, mixed>
- Validate Multiselect Field.
- validate_password_field() : string
- Validate Password Field. No input sanitization is used to avoid corrupting passwords.
- validate_price_field() : string
- Validate Price Field.
- validate_safe_text_field() : string
- Sanitize 'Safe Text' fields.
- validate_select_field() : string
- Validate Select Field.
- validate_settings_fields() : mixed
- Validate the data on the "Settings" form.
- validate_text_field() : string
- Validate Text Field.
- validate_textarea_field() : string
- Validate Textarea Field.
- get_order_total() : float
- Get the order total in checkout and pay_for_order.
- set_defaults() : array<string|int, mixed>
- Set default required properties for each field.
Properties
$availability
Available for all counties or specific.
public
string
$availability
$chosen
Chosen payment method id.
public
bool
$chosen
$countries
Countries this gateway is allowed for.
public
array<string|int, mixed>
$countries
$description
Payment method description for the frontend.
public
string
$description
$enabled
Yes or no based on whether the method is enabled.
public
string
$enabled
= 'yes'
$errors
Validation errors.
public
array<string|int, mixed>
$errors
= array()
$form_fields
Form option fields.
public
array<string|int, mixed>
$form_fields
= array()
$has_fields
True if the gateway shows fields on the checkout.
public
bool
$has_fields
$icon
Icon for the gateway.
public
string
$icon
$id
ID of the class extending the settings API. Used in option names.
public
string
$id
= ''
$max_amount
Maximum transaction amount, zero does not define a maximum.
public
int
$max_amount
= 0
$method_description
Gateway description.
public
string
$method_description
= ''
$method_title
Gateway title.
public
string
$method_title
= ''
$new_method_label
Optional label to show for "new payment method" in the payment method/token selection radio selection.
public
string
$new_method_label
= ''
$order_button_text
Set if the place order button should be renamed on selection.
public
string
$order_button_text
$pay_button_id
Pay button ID if supported.
public
string
$pay_button_id
= ''
$plugin_id
The plugin ID. Used for option names.
public
string
$plugin_id
= 'woocommerce_'
$settings
Setting values.
public
array<string|int, mixed>
$settings
= array()
$supports
Supported features such as 'default_credit_card_form', 'refunds'.
public
array<string|int, mixed>
$supports
= array('products')
$title
Payment method title for the frontend.
public
string
$title
$view_transaction_url
Optional URL to view a transaction.
public
string
$view_transaction_url
= ''
$data
The posted settings data. When empty, $_POST data will be used.
protected
array<string|int, mixed>
$data
= array()
$tokens
Contains a users saved tokens for this gateway.
protected
array<string|int, mixed>
$tokens
= array()
Methods
add_error()
Add an error message for display in admin on save.
public
add_error(string $error) : mixed
Parameters
- $error : string
-
Error message.
Return values
mixed —add_payment_method()
Add payment method via account screen. This should be extended by gateway plugins.
public
add_payment_method() : array<string|int, mixed>
Tags
Return values
array<string|int, mixed> —admin_options()
Output the gateway settings screen.
public
admin_options() : mixed
Return values
mixed —can_refund_order()
Can the order be refunded via this gateway?
public
can_refund_order(WC_Order $order) : bool
Should be extended by gateways to do their own checks.
Parameters
- $order : WC_Order
-
Order object.
Return values
bool — If false, the automatic refund button is hidden in the UI.credit_card_form()
Core credit card form which gateways can use if needed. Deprecated - inherit WC_Payment_Gateway_CC instead.
public
credit_card_form([array<string|int, mixed> $args = array() ][, array<string|int, mixed> $fields = array() ]) : mixed
Parameters
- $args : array<string|int, mixed> = array()
-
Arguments.
- $fields : array<string|int, mixed> = array()
-
Fields.
Return values
mixed —display_errors()
Display admin error messages.
public
display_errors() : mixed
Return values
mixed —format_settings()
Format settings if needed.
public
format_settings(array<string|int, mixed> $value) : array<string|int, mixed>
Parameters
- $value : array<string|int, mixed>
-
Value to format.
Tags
Return values
array<string|int, mixed> —generate_checkbox_html()
Generate Checkbox HTML.
public
generate_checkbox_html(string $key, array<string|int, mixed> $data) : string
Parameters
- $key : string
-
Field key.
- $data : array<string|int, mixed>
-
Field data.
Tags
Return values
string —generate_color_html()
Generate Color Picker Input HTML.
public
generate_color_html(string $key, array<string|int, mixed> $data) : string
Parameters
- $key : string
-
Field key.
- $data : array<string|int, mixed>
-
Field data.
Tags
Return values
string —generate_decimal_html()
Generate Decimal Input HTML.
public
generate_decimal_html(string $key, array<string|int, mixed> $data) : string
Parameters
- $key : string
-
Field key.
- $data : array<string|int, mixed>
-
Field data.
Tags
Return values
string —generate_multiselect_html()
Generate Multiselect HTML.
public
generate_multiselect_html(string $key, array<string|int, mixed> $data) : string
Parameters
- $key : string
-
Field key.
- $data : array<string|int, mixed>
-
Field data.
Tags
Return values
string —generate_password_html()
Generate Password Input HTML.
public
generate_password_html(string $key, array<string|int, mixed> $data) : string
Parameters
- $key : string
-
Field key.
- $data : array<string|int, mixed>
-
Field data.
Tags
Return values
string —generate_price_html()
Generate Price Input HTML.
public
generate_price_html(string $key, array<string|int, mixed> $data) : string
Parameters
- $key : string
-
Field key.
- $data : array<string|int, mixed>
-
Field data.
Tags
Return values
string —generate_safe_text_html()
Generates HTML for the 'safe_text' input type (mostly used for gateway-related settings).
public
generate_safe_text_html(string $key, array<string|int, mixed> $data) : string
Parameters
- $key : string
-
Field key.
- $data : array<string|int, mixed>
-
Field data.
Tags
Return values
string —generate_select_html()
Generate Select HTML.
public
generate_select_html(string $key, array<string|int, mixed> $data) : string
Parameters
- $key : string
-
Field key.
- $data : array<string|int, mixed>
-
Field data.
Tags
Return values
string —generate_settings_html()
Generate Settings HTML.
public
generate_settings_html([array<string|int, mixed> $form_fields = array() ][, bool $echo = true ]) : string
Generate the HTML for the fields on the "settings" screen.
Parameters
- $form_fields : array<string|int, mixed> = array()
-
(default: array()) Array of form fields.
- $echo : bool = true
-
Echo or return.
Tags
Return values
string — the html for the settingsgenerate_text_html()
Generate Text Input HTML.
public
generate_text_html(string $key, array<string|int, mixed> $data) : string
Parameters
- $key : string
-
Field key.
- $data : array<string|int, mixed>
-
Field data.
Tags
Return values
string —generate_textarea_html()
Generate Textarea HTML.
public
generate_textarea_html(string $key, array<string|int, mixed> $data) : string
Parameters
- $key : string
-
Field key.
- $data : array<string|int, mixed>
-
Field data.
Tags
Return values
string —generate_title_html()
Generate Title HTML.
public
generate_title_html(string $key, array<string|int, mixed> $data) : string
Parameters
- $key : string
-
Field key.
- $data : array<string|int, mixed>
-
Field data.
Tags
Return values
string —get_custom_attribute_html()
Get custom attributes.
public
get_custom_attribute_html(array<string|int, mixed> $data) : string
Parameters
- $data : array<string|int, mixed>
-
Field data.
Return values
string —get_description()
Return the gateway's description.
public
get_description() : string
Return values
string —get_description_html()
Get HTML for descriptions.
public
get_description_html(array<string|int, mixed> $data) : string
Parameters
- $data : array<string|int, mixed>
-
Data for the description.
Return values
string —get_errors()
Get admin error messages.
public
get_errors() : mixed
Return values
mixed —get_field_default()
Get a fields default value. Defaults to "" if not set.
public
get_field_default(array<string|int, mixed> $field) : string
Parameters
- $field : array<string|int, mixed>
-
Field key.
Return values
string —get_field_key()
Prefix key for settings.
public
get_field_key(string $key) : string
Parameters
- $key : string
-
Field key.
Return values
string —get_field_type()
Get a fields type. Defaults to "text" if not set.
public
get_field_type(array<string|int, mixed> $field) : string
Parameters
- $field : array<string|int, mixed>
-
Field key.
Return values
string —get_field_value()
Get a field's posted and validated value.
public
get_field_value(string $key, array<string|int, mixed> $field[, array<string|int, mixed> $post_data = array() ]) : string
Parameters
- $key : string
-
Field key.
- $field : array<string|int, mixed>
-
Field array.
- $post_data : array<string|int, mixed> = array()
-
Posted data.
Return values
string —get_form_fields()
Get the form fields after they are initialized.
public
get_form_fields() : array<string|int, mixed>
Return values
array<string|int, mixed> — of optionsget_icon()
Return the gateway's icon.
public
get_icon() : string
Return values
string —get_method_description()
Return the description for admin screens.
public
get_method_description() : string
Return values
string —get_method_title()
Return the title for admin screens.
public
get_method_title() : string
Return values
string —get_new_payment_method_option_html()
Displays a radio button for entering a new payment method (new CC details) instead of using a saved method.
public
get_new_payment_method_option_html() : mixed
Only displayed when a gateway supports tokenization.
Tags
Return values
mixed —get_option()
Get option from DB.
public
get_option(string $key[, mixed $empty_value = null ]) : string
Gets an option from the settings API, using defaults if necessary to prevent undefined notices.
Parameters
- $key : string
-
Option key.
- $empty_value : mixed = null
-
Value when empty.
Return values
string — The value specified for the option or a default value for the option.get_option_key()
Return the name of the option in the WP DB.
public
get_option_key() : string
Tags
Return values
string —get_pay_button_id()
Return the gateway's pay button ID.
public
get_pay_button_id() : string
Tags
Return values
string —get_post_data()
Returns the POSTed data, to be used to save the settings.
public
get_post_data() : array<string|int, mixed>
Return values
array<string|int, mixed> —get_return_url()
Get the return url (thank you page).
public
get_return_url([WC_Order|null $order = null ]) : string
Parameters
- $order : WC_Order|null = null
-
Order object.
Return values
string —get_saved_payment_method_option_html()
Gets saved payment method HTML from a token.
public
get_saved_payment_method_option_html(WC_Payment_Token $token) : string
Parameters
- $token : WC_Payment_Token
-
Payment Token.
Tags
Return values
string — Generated payment method HTMLget_title()
Return the gateway's title.
public
get_title() : string
Return values
string —get_tokens()
Returns a users saved tokens for this gateway.
public
get_tokens() : array<string|int, mixed>
Tags
Return values
array<string|int, mixed> —get_tooltip_html()
Get HTML for tooltips.
public
get_tooltip_html(array<string|int, mixed> $data) : string
Parameters
- $data : array<string|int, mixed>
-
Data for the tooltip.
Return values
string —get_transaction_url()
Get a link to the transaction on the 3rd party gateway site (if applicable).
public
get_transaction_url(WC_Order $order) : string
Parameters
- $order : WC_Order
-
the order object.
Return values
string — transaction URL, or empty string.has_fields()
Check if the gateway has fields on the checkout.
public
has_fields() : bool
Return values
bool —init_form_fields()
Initialise settings form fields.
public
init_form_fields() : mixed
Add an array of fields to be displayed on the gateway's settings screen.
Tags
Return values
mixed —init_settings()
Init settings for gateways.
public
init_settings() : mixed
Return values
mixed —is_available()
Check if the gateway is available for use.
public
is_available() : bool
Return values
bool —needs_setup()
Return whether or not this gateway still requires setup to function.
public
needs_setup() : bool
When this gateway is toggled on via AJAX, if this returns true a redirect will occur to the settings page instead.
Tags
Return values
bool —payment_fields()
Default payment fields display. Override this in your gateway to customize displayed fields.
public
payment_fields() : mixed
By default this renders the payment gateway description.
Tags
Return values
mixed —process_admin_options()
Processes and saves options.
public
process_admin_options() : bool
If there is an error thrown, will continue to save and validate fields, but will leave the erroring field out.
Return values
bool — was anything saved?process_payment()
Process Payment.
public
process_payment(int $order_id) : array<string|int, mixed>
Process the payment. Override this in your gateway. When implemented, this should. return the success and redirect in an array. e.g:
return array(
'result' => 'success',
'redirect' => $this->get_return_url( $order )
);
Parameters
- $order_id : int
-
Order ID.
Return values
array<string|int, mixed> —process_refund()
Process refund.
public
process_refund(int $order_id[, float|null $amount = null ][, string $reason = '' ]) : bool|WP_Error
If the gateway declares 'refunds' support, this will allow it to refund. a passed in amount.
Parameters
- $order_id : int
-
Order ID.
- $amount : float|null = null
-
Refund amount.
- $reason : string = ''
-
Refund reason.
Return values
bool|WP_Error — True or false based on success, or a WP_Error object.save_payment_method_checkbox()
Outputs a checkbox for saving a new payment method to the database.
public
save_payment_method_checkbox() : mixed
Tags
Return values
mixed —saved_payment_methods()
Grab and display our saved payment methods.
public
saved_payment_methods() : mixed
Tags
Return values
mixed —set_current()
Set as current gateway.
public
set_current() : mixed
Set this as the current gateway.
Return values
mixed —set_post_data()
Sets the POSTed data. This method can be used to set specific data, instead of taking it from the $_POST array.
public
set_post_data([array<string|int, mixed> $data = array() ]) : mixed
Parameters
- $data : array<string|int, mixed> = array()
-
Posted data.
Return values
mixed —supports()
Check if a gateway supports a given feature.
public
supports(string $feature) : bool
Gateways should override this to declare support (or lack of support) for a feature. For backward compatibility, gateways support 'products' by default, but nothing else.
Parameters
- $feature : string
-
string The name of a feature to test support for.
Tags
Return values
bool — True if the gateway supports the feature, false otherwise.tokenization_script()
Enqueues our tokenization script to handle some of the new form options.
public
tokenization_script() : mixed
Tags
Return values
mixed —update_option()
Update a single option.
public
update_option(string $key[, mixed $value = '' ]) : bool
Parameters
- $key : string
-
Option key.
- $value : mixed = ''
-
Value to set.
Tags
Return values
bool — was anything saved?validate_checkbox_field()
Validate Checkbox Field.
public
validate_checkbox_field(string $key, string $value) : string
If not set, return "no", otherwise return "yes".
Parameters
- $key : string
-
Field key.
- $value : string
-
Posted Value.
Return values
string —validate_decimal_field()
Validate Decimal Field.
public
validate_decimal_field(string $key, string $value) : string
Make sure the data is escaped correctly, etc.
Parameters
- $key : string
-
Field key.
- $value : string
-
Posted Value.
Return values
string —validate_fields()
Validate frontend fields.
public
validate_fields() : bool
Validate payment fields on the frontend.
Return values
bool —validate_multiselect_field()
Validate Multiselect Field.
public
validate_multiselect_field(string $key, string $value) : string|array<string|int, mixed>
Parameters
- $key : string
-
Field key.
- $value : string
-
Posted Value.
Return values
string|array<string|int, mixed> —validate_password_field()
Validate Password Field. No input sanitization is used to avoid corrupting passwords.
public
validate_password_field(string $key, string $value) : string
Parameters
- $key : string
-
Field key.
- $value : string
-
Posted Value.
Return values
string —validate_price_field()
Validate Price Field.
public
validate_price_field(string $key, string $value) : string
Make sure the data is escaped correctly, etc.
Parameters
- $key : string
-
Field key.
- $value : string
-
Posted Value.
Return values
string —validate_safe_text_field()
Sanitize 'Safe Text' fields.
public
validate_safe_text_field(string $key, string $value) : string
These fields are similar to regular text fields, but a much smaller set of HTML tags are allowed. By default,
this means <br>, <img>, <p> and <span> tags.
Note: this is a sanitization method, rather than a validation method (the name is due to some historic naming choices).
Parameters
- $key : string
-
Field key (currently unused).
- $value : string
-
Posted Value.
Return values
string —validate_select_field()
Validate Select Field.
public
validate_select_field(string $key, string $value) : string
Parameters
- $key : string
-
Field key.
- $value : string
-
Posted Value.
Return values
string —validate_settings_fields()
Validate the data on the "Settings" form.
public
validate_settings_fields([array<string|int, mixed> $form_fields = array() ]) : mixed
Parameters
- $form_fields : array<string|int, mixed> = array()
-
Array of fields.
Tags
Return values
mixed —validate_text_field()
Validate Text Field.
public
validate_text_field(string $key, string $value) : string
Make sure the data is escaped correctly, etc.
Parameters
- $key : string
-
Field key.
- $value : string
-
Posted Value.
Return values
string —validate_textarea_field()
Validate Textarea Field.
public
validate_textarea_field(string $key, string $value) : string
Parameters
- $key : string
-
Field key.
- $value : string
-
Posted Value.
Tags
Return values
string —get_order_total()
Get the order total in checkout and pay_for_order.
protected
get_order_total() : float
Return values
float —set_defaults()
Set default required properties for each field.
protected
set_defaults(array<string|int, mixed> $field) : array<string|int, mixed>
Parameters
- $field : array<string|int, mixed>
-
Setting field array.