WooCommerce Code Reference

WC_Gateway_COD extends WC_Payment_Gateway

Cash on Delivery Gateway.

Provides a Cash on Delivery Payment Gateway.

Tags
class

WC_Gateway_COD

extends

WC_Payment_Gateway

version
2.1.0

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.
$enable_for_methods  : array<string|int, mixed>
Enable for shipping methods.
$enable_for_virtual  : bool
Enable for virtual products.
$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.
$instructions  : string
Gateway instructions that will be added to the thank you page and emails.
$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.
__construct()  : mixed
Constructor for the 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 admin options table.
can_refund_order()  : bool
Can the order be refunded via this gateway?
change_payment_complete_order_status()  : string
Change payment complete order status to completed for COD orders.
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.
email_instructions()  : mixed
Add content to the WC emails.
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 Gateway Settings Form Fields.
init_settings()  : mixed
Initialise Settings.
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 the payment and return the result.
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.
thankyou_page()  : mixed
Output for the order received page.
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.
setup_properties()  : mixed
Setup general properties for the gateway.
get_canonical_order_shipping_item_rate_ids()  : array<string|int, mixed>
Converts the chosen rate IDs generated by Shipping Methods to a canonical 'method_id:instance_id' format.
get_canonical_package_rate_ids()  : array<string|int, mixed>
Converts the chosen rate IDs generated by Shipping Methods to a canonical 'method_id:instance_id' format.
get_matching_rates()  : array<string|int, mixed>
Indicates whether a rate exists in an array of canonically-formatted rate IDs that activates this gateway.
is_accessing_settings()  : bool
Checks to see whether or not the admin settings are being accessed by the current request.
load_shipping_method_options()  : array<string|int, mixed>
Loads all of the shipping method options for the enable_for_methods field.

Properties

Methods

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
since
3.2.0

Included here from 3.2.0, but supported from 3.0.0.

Return values
array<string|int, 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
boolIf false, the automatic refund button is hidden in the UI.

change_payment_complete_order_status()

Change payment complete order status to completed for COD orders.

public change_payment_complete_order_status(string $status, int $order_id[, WC_Order|false $order = false ]) : string
Parameters
$status : string

Current order status.

$order_id : int

Order ID.

$order : WC_Order|false = false

Order object.

Tags
since
3.1.0
Return values
string

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

email_instructions()

Add content to the WC emails.

public email_instructions(WC_Order $order, bool $sent_to_admin[, bool $plain_text = false ]) : mixed
Parameters
$order : WC_Order

Order object.

$sent_to_admin : bool

Sent to admin.

$plain_text : bool = false

Email format: plain text or HTML.

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
deprecated
2.6.0

Unused.

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
since
1.0.0
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
since
1.0.0
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
since
1.0.0
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
since
1.0.0
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
since
1.0.0
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
since
1.0.0
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
since
7.6.0
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
since
1.0.0
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
since
1.0.0
uses
method_exists()
Return values
stringthe html for the settings

generate_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
since
1.0.0
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
since
1.0.0
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
since
1.0.0
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_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_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_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_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
since
2.6.0
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
stringThe value specified for the option or a default value for the option.

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

init_settings()

Initialise Settings.

public init_settings() : mixed

Store all settings in a single database entry and make sure the $settings array is either the default or the settings stored in the database.

Tags
since
1.0.0
uses

get_option(), add_option()

Return values
mixed

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
since
3.4.0
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
since
1.5.7
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
boolwas anything saved?

process_payment()

Process the payment and return the result.

public process_payment(int $order_id) : array<string|int, mixed>
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_ErrorTrue or false based on success, or a WP_Error object.

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
since
1.5.7
Return values
boolTrue if the gateway supports the feature, false otherwise.

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
since
3.4.0
Return values
boolwas 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_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
deprecated
2.6.0

No longer used.

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
since
9.0.0

No longer allows storing IFRAME, which was allowed for "ShareThis" integration no longer found in core.

Return values
string

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.

Return values
array<string|int, mixed>

get_canonical_order_shipping_item_rate_ids()

Converts the chosen rate IDs generated by Shipping Methods to a canonical 'method_id:instance_id' format.

private get_canonical_order_shipping_item_rate_ids(array<string|int, mixed> $order_shipping_items) : array<string|int, mixed>
Parameters
$order_shipping_items : array<string|int, mixed>

Array of WC_Order_Item_Shipping objects.

Tags
since
3.4.0
Return values
array<string|int, mixed>$canonical_rate_ids Rate IDs in a canonical format.

get_canonical_package_rate_ids()

Converts the chosen rate IDs generated by Shipping Methods to a canonical 'method_id:instance_id' format.

private get_canonical_package_rate_ids(array<string|int, mixed> $chosen_package_rate_ids) : array<string|int, mixed>
Parameters
$chosen_package_rate_ids : array<string|int, mixed>

Rate IDs as generated by shipping methods. Can be anything if a shipping method doesn't honor WC conventions.

Tags
since
3.4.0
Return values
array<string|int, mixed>$canonical_rate_ids Rate IDs in a canonical format.

get_matching_rates()

Indicates whether a rate exists in an array of canonically-formatted rate IDs that activates this gateway.

private get_matching_rates(array<string|int, mixed> $rate_ids) : array<string|int, mixed>
Parameters
$rate_ids : array<string|int, mixed>

Rate ids to check.

Tags
since
3.4.0
Return values
array<string|int, mixed>

is_accessing_settings()

Checks to see whether or not the admin settings are being accessed by the current request.

private is_accessing_settings() : bool
Return values
bool

load_shipping_method_options()

Loads all of the shipping method options for the enable_for_methods field.

private load_shipping_method_options() : array<string|int, mixed>
Return values
array<string|int, mixed>