👮Filters

Actions are generally used to execute extra code in processes. However, filters allow you to update the data in the relevant process while running extra code. Below are listed all the filters you can use in CryptoPay integration processes.

With hooks, you should always return the 1st parameter and the same type, except in exceptional cases. CryptoPay performs strict type checking.

Below are examples of filters in codebase. However, if you want to run code in an actions process. There will be a usage as in the example. Return is a required for filters.

Hook::addAction('edit_networks', function (NetworksType $networks) {
    // your code here
    return $networks;
});

Payment

Payment process is a class that starts the whole payment process and loads CryptoPay's html output and JS files. This class has hooks where you can make some changes until CryptoPay is loaded.

Edit networks

With this hook, you can make specific adjustments to the networks that will be listed on CryptoPay according to your wishes.

Hook::callFilter('edit_networks', NetworksType $networks);
Hook::callFilter('edit_networks_{addon}', NetworksType $networks);

Edit config data

The Config data hook actually contains the ConfigDataType and the ConfigDataType is the equivalent of the configuration object that will be sent to the CryptoPay JS side according to the settings and various processes on the backend side of CryptoPay. Here again, you can access the existing ConfigDataType and edit the values that can be set later.

Hook::callFilter('edit_config_data', ConfigDataType $config);
Hook::callFilter('edit_config_data_{addon}', ConfigDataType $config);

JS variables

If you have data that you want to use on the JavaScript side during the CryptoPay integration process, you can specify it here and use this data with the window.CryptoPayVars object on the JavaScript side.

Hook::callFilter('js_variables', array $vars);

Before & after HTML

There are hooks here that you can use to insert HTML code before and after the HTML output, which is the final output. Again, the ConfigDataType is passed as a parameter in case there is data you need.

$html = Hook::callFilter('before_html', '', ConfigDataType $config);
$html .= Helpers::view('cryptopay', ['loading' => $loading]);
$html = Hook::callFilter('after_html', $html, ConfigDataType $config);

Edit payment data

Edit payment data is a filter that you can also see in RestAPI and Verifier and there are 3 in total. CryptoPay's general payment process consists of 3 steps and they are init, start, finish.

The variable data in the init section are the order, recipient address and provider config values to be used in the selected network. It is created with the initType.

The start part is the step we use to create the necessary records after the user makes the payment.

The Finish section is the last section that can work both in RestAPI during the active payment process and in Verifier in the background, verifying the payment and processing accordingly.

With the Edit payment data hook, you can make changes to the payment data before all these processes. For example, if you want to increase the price by % in addition to the built-in discount feature to create a special price policy for yourself. You need to use this hook.

Also, this hook has a "getProcess()" method that shows which step you are in and contains the "PaymentDataProcess" enum.

Edit payment data works globally in 3 fields as we mentioned. and as you can see in the next hook "init" there are hooks that work with addon code for each step.

Hook::callFilter('edit_payment_data', PaymentDataType $data);

Initialize

Unlike initial edit payment data, it is specific to the addon code and only works within the init method.

Hook::callFilter('init_{}', PaymentDataType $data)

Provider config

CryptoPay uses the MultipleChain library developed by our team in blockchain interaction processes. When running providers in this library, it may be necessary to send special parameters to some of them. This hook is used for this. The {networkCode} specifies which provider, for example bitcoin, solana, tron, evmchains, will be added when it runs.

Hook::callFilter('provider_config_{networkCode}', [])

RestAPI & Verifier

Edit payment data

This field is already described under Payment. Edit payment data

Before payment started

As we mentioned in the edit payment data hook in the Payment step, this is a hook that is only available in the start step and works according to the addon code.

Hook::callFilter('before_payment_started_{addon}', PaymentDataType $data);

Before payment finished

As we mentioned in the edit payment data hook in the Payment step, this is a hook that is only available in the finished step and works according to the addon code.

Hook::callFilter('before_payment_finished_{addon}', PaymentDataType $data);

Payment success message

The message the user will see when the checkout process is successfully completed.

Hook::callFilter('payment_success_message_{addon}', string $successMessage)

Payment failed message

The message the user will see if an error occurs during the checkout process.

Hook::callFilter('payment_failed_message_{addon}', string $failedMessage)

General (configuration)

Mode

Mode represents the modes used by CryptoPay JS, for example network, currency. This can be changed in the settings, but for specific cases, this hook has been added so that you can update it with code. There are both general and by addon code only.

Hook::callFilter('mode', string $mode);
Hook::callFilter('mode_{addon}', string $mode);

Theme

This again represents the theme on the visual side of CryptoPay and has two values: light and dark.

Hook::callFilter('theme', string $theme);
Hook::callFilter('theme_{addon}', string $theme);

Wallet address

Wallet address is a hook that works just before the receiver. The receiver hook provides control for many different situations, whereas the wallet address hook can only be operated on according to the network code.

Hook::callFilter('wallet_address_{networkCode}', string $walletAddress);

Wallet images

The wallet images hook is generally only used in network support integrations to provide the wallet image based on the wallet code to the CryptoPay JS side.

Hook::callFilter('wallet_images', array $walletImages);

Receiver

Receiver is ultimately the address where the payment will be made. This value comes from the settings and preceded by the wallet address hook. It then provides 3 different hook types and also the PaymentDataType value, allowing you to change the recipient address for many different situations.

Hook::callFilter('receiver', string $receiver, PaymentDataType $data);
Hook::callFilter('receiver_{addon}', string $receiver, PaymentDataType $data);
Hook::callFilter('receiver_{networkCode}', string $receiver, PaymentDataType $data);

Models

Models is the hook to use if you want to register a transaction when integrating CryptoPay as a payment option for another plugin and includes classes derived from the AbstractTransaction model.

In the following figure, first the addon code is added and then the object is derived from the related model class.

Hook::callFilter('models', array [
    'woocommerce' => new OrderTransaction() // Extends from AbstractTransaction
]);

Networks

The Networks hook is used to develop network support for CryptoPay. You can add the network data you created with NetworkType to the list with the "addNetwork()" method.

Hook::callFilter('networks', NetworksType $networks);

PHP providers

PHP Providers also takes the same approach as models, but here no objects are derived from classes because for each provider

Hook::callFilter('php_providers', [
    'evmchains' => Provider::class // MultipleChain provider class
]);

JS providers

JS Providers are libraries that carry out processes such as payment and connection to the wallet on the CryptoPay JS side. These also have the MultipleChain standard. The definition should be made as follows and addScript, CryptoPay's asset adding method, should be used.

While developing network support, you can access the addon you registered with the registerAddon method with the Helpers::getAddon() method and use the addScript method, which is specific to the addon, to retrieve the assets in the addon folder. You can see it clearly in the examples section.

The "EvmChains" part here is very important. This must definitely be the accessible name of the MultipleChain provider in the window object. For example, EvmChains, Bitcoin, Solana, Tron, if the equivalent of the MultipleChain provider you use in the window object is ExampleChain. This should also be ExampleChain.

The value returned from the addScript method is a string and is the id value defined in WordPress' enqueue method.

Hook::callFilter('js_providers', [
    'EvmChains' => Helpers::addScript('evm-chains-provider.js'),
]);

Payment redirect urls

"Success" and "failed" values should always be defined for pages to be redirected based on payment status. Additionally, if the success page does not appear before the payment is completed and the user will use the reminder email feature, a link with the "reminderEmail" value should be defined according to the addon. When the user sets a reminder email, they are directed to this page.

Hook::callFilter('payment_redirect_urls_{addon}', PaymentDataType $data),

Example:

Hook::addFilter('payment_redirect_urls_woocommerce', function (PaymentDataType $data): array {
    return [
        'success' => '' // required,
        'failed' => '' // required,
        'reminderEmail' => '' // optional, but if success not working, this is required too
    ];
});

Extra features (discounts, currency converter)

Converters

It is the first hook to be used in the process of developing a custom currency converter for CryptoPay. First of all, an option is added that the user can control from the settings.

Hook::callFilter("converters", array [
    'CryptoCompare' => 'Default (CryptoCompare)',
]);

API Options

If your converter has options that can be set, such as an API key. This is the hook you will use to define relevant settings.

Hook::callFilter("api_options", array $options);

Custom prices

Again, during the currency converter process, if there are currencies that are not included in any API. Special values can be assigned for these by the user in the settings. You can assign a special value here as its code equivalent.

Hook::callFilter('custom_prices', array $currencies);

Currency converter

The "key" value here should be the value we defined with the first hook, converters. An example will be given below.

The $paymentAmount value starts as null. This value indicates that a value could not be reached in the relevant converter process. For example, it first checks stable coins and then checks custom prices. If these are present, your method will come with a value, not a null. PaymentDataType is the data class that contains all the data you can use in the currency converter process.

Hook::callFilter("currency_converter_{key}", float|null $paymentAmount, PaymentDataType $data);

Example:

Hook::callFilter("currency_converter_CryptoCompare", function (float|null $paymentAmount, PaymentDataType $data): float|null {
// Your custom converter process for CryptoCompare option
});

Payment amount

This hook is the process where the currency converter process is completed and the final result is given.

Hook::callFilter('payment_amount', float|null $paymentAmount, PaymentDataType $data);

Apply discount

It is the hook that indicates whether the discount process will be applied in the relevant addon or not. For example, we have prepared a crypto withdrawal plugin for Dokan that works with CryptoPay. It would be ridiculous to pay them at a discount when users request a withdrawal from you, right? That's why this hook is used to deactivate the discount process in such plugins. An example is given.

Hook::callFilter('apply_discount_{addon}', true);

Example:

Hook::addFilter('apply_discount_dokan', '__return_false');

Discount rates

Again, they are hooks for a global addon where you can see and manage the discount rates defined by the user according to the currency symbol in the settings.

Hook::callFilter('discount_rates', array $discountRates, PaymentDataType $data);
Hook::callFilter('discount_rates_{addon}', array $discountRates, PaymentDataType $data);

Discounted amount

It is the final payable amount at the end of the discount process.

Hook::callFilter('discounted_amount', float $discountedAmount, PaymentDataType $data);
Hook::callFilter('discounted_amount_{addon}', float $discountedAmount, PaymentDataType $data);

Sanctions

This hook also manages a process similar to apply discount. Sanctions check whether the wallets used in payments received from users are recorded in various databases to see if they are used for bad purposes. Accordingly, you can restrict receiving payments from the relevant wallet or only show it as a note in transaction records.

For example, in the WooCommerce Refund process, you use your own wallet and you do not need any sanctions here, right? In such cases, a use as in the example is necessary to passivate.

Hook::callFilter('sanctions_{addon}', bool $status, string $api, string $mode,  array $supports);

Example:

Hook::addFilter('sanctions_woocommerce_refund', '__return_false');

Reminder email content

If you want to customize the template used for reminder emails, you can use the hook below.

Hook::callFilter('reminder_email_content_{addon}', string $mailContent, PaymentDataType $paymentData);