⚡JS Events

In CryptoPay, there are manageable processes hooks on the PHP side and events on the JS side. Events are accessible as windowCryptoPayApp.events and allow you to run extra code.

You can access all events and their examples below. Events do not need to have a return value.

Events always take parameters as context (ctx) objects.

If the option is on, all running events will always appear in the console. Parameter 3 is used to specify which file the event is in or where it is located. It is shown in the Init example.

In order to understand the structure of events in general, the init event will be illustrated in detail. The following events will be explained only in terms of the process in which they are executed and the parameters.

Also many events are awaited with await. So you can use promises for processes such as API requests etc. in events.

Init

The Init event is the first process that runs after a network or currency is selected. In this process, the relevant MultipleChain provider is selected according to the user's choice, a request is sent to the API and the necessary data for the payment process is created.

The ctx parameter in the Init event is as follows:

• network => The network selected by the user.

• currency => The currency selected by the user.

• init => Init value is the initial data in CryptoPay'js. In other words, the currency, payment amount, recipient address and similar values to be used in the payment process constitute the init object. The structure of the init object is given in the example.

$events.call('init', {network, currency, init});

type Currency = {
    symbol: string;
    address?: string;
    imageUrl?: string;
    decimals?: number;
}

type Order = {
    id?: number;
    amount: number;
    currency: string;
    paymentAmount: number;
    paymentCurrency: Currency;
}

type Init = {
    order: Order;
    receiver: string;
    providerConfig: object; // dynamic object
    qrCodeWaitingTime: number;
    blockConfirmationCount: number;
}

And you can define the following two values:

Disable auto qr

You can define disableAutoQr to ctx in init event. It is true by default. This value controls the following. If there is only one network and one currency, and also if only QR payments are enabled as a payment option, CryptoPay will open the QR payment screen directly. However, in some specific cases you don't want this to happen. You can therefore control this with the disableAutoQr value.

ctx.disableAutoQr = true|false;

Initial data value

What does this do? For example, when a network is selected in CryptoPay, it will always make a request to the init endpoint. But on the WooCommerce checkout page, we do a form check first. For this, we are already sending a request to an endpoint. It would be an unnecessary waste of time to send a request to the init endpoint right after that. For this reason, when doing form control, if there is no problem, we also return the init value. Then we add the value to ctx as specified below. If CryptoPay sees that the init value is correct, it will stop requesting the init endpoint.

ctx.init = InitialObjectType;

Example:

To give an example of what we said in the above, the checkFormProcess value returns an object. If it contains the init value. The whole process works properly. But if you want to output an error message, this time you need to return a value with the error value. An example is given about this.

CryptoPayApp.events.add('init', async (ctx) => {
    ctx = Object.assign(ctx, (await checkFormProcess(ctx.network, ctx.currency)));
}, 'wc_checkout' /* this event works on wc_checkout process */);

// if form process have a problem you need return a like that object
let result = {
    error: true,
    message: '' // optional, if you enter a value this will show error popup
}

Selected network

Event triggered when the user selects a network. It gives you the selected network and the previous network value in the context object.

$events.call('selectedNetwork', {newNetwork, oldNetwork});

Currency converter

It is the event that runs after a currency is selected or automatically updates the payment amount, i.e. immediately after the currency conversion request is sent. It gives you the current selected currency and payment amount as context.

$events.call('currencyConverter', {paymentCurrency, paymentAmount})

Pay now

It is the event that runs when the pay now button is clicked in the currency selection section after selecting the network in Network mode. It gives you the order object and the selected network as context.

$events.call('payNow', {order, network})

Selected currency

Again like pay now, it is the event triggered when selecting currencies in network mode. It gives you the value of the previous and selected currency as context.

$events.call('selectedCurrency', {newCurrency, oldCurrency});

NOTE:

selectedNetwork, payNow and selectedCurrency are not triggered in currency list mode. When you select a currency in currency list mode, init is triggered directly and there is already the necessary data there. This is because in network mode they are all independent processes and the init event runs after payNow. When you select a currency in Currency mode, selectedNetwork, payNow, selectedCurrency processes are completed. For this reason, only the init event is sufficient.

Qr payment started

This event is triggered when qr payment option is selected. It gives you order and network values as objects.

$events.call('qrPaymentStarted', {order, network});

Qr payment new transaction

This event is the event that is triggered if the user makes the payment and a transaction is detected while waiting for the payment to be made on the qr payment page. In addition to the order and network values, it also gives you the hash id of the current transaction.

$events.call('qrPaymentNewTransaction', { order, network, transactionHash });

Wallet list opened

It is the event that runs when the wallet list is opened. You get order and network values as context.

$events.call('walletListOpened', {network, order});

Wallet list closed

It is the event that runs when the wallet list is closed. You get order and network values as context.

$events.call('walletListClosed', {network, order});

Wallet connection request

It is the event that runs when a connection request to a wallet is created and provides you with the order, network and the object of the wallet selected by the user in context.

$events.call('walletConnectionRequest', {network, order, wallet});

Wallet connection approved

It works when the wallet connection request is approved.

$events.call('walletConnectionApproved', {network, order, wallet});

Wallet connection declined

It works when the wallet connection request is declined.

$events.call('walletConnectionDeclined', {network, order, wallet});

Wallet payment request

The event that runs before the transfer (payment) request sent to the user after the wallet connection is confirmed.

$events.call('walletPaymentRequest', {network, order, wallet});

Wallet payment approved

It works when the wallet payment request is approved.

$events.call('walletPaymentApproved', {network, order, wallet});

Wallet payment declined

It works when the wallet payment request is declined.

$events.call('walletPaymentDeclined', {network, order, wallet});

Transaction received

It is triggered when a transaction is received after a QR or wallet payment.

$events.call('transactionReceived', { order, network, transaction });

Transaction create fail

It is triggered if the createTransaction setting is true in the config and there is a problem creating a transaction record in the API.

$events.call('transactionCreateFail', { order, network, transaction });

Transaction created

If the createTransaction setting is true in the config and the transaction record creation process completed successfully.

$events.call('transactionCreated', { order, network, transaction });

Confirmation started

It is triggered when the user accepts the payment request or when the confirmation process starts after the transaction is captured in the qr payment process (if confirmation is true in the config).

$events.call('confirmationStarted', { order, network, transaction });

Confirmation completed

Works when the verification step is complete.

$events.call('confirmationCompleted', { order, network, transaction });

Payment reset

It is an event that is triggered when the user clicks on the change button (option to go back to the beginning to change the network), if there is an error in the process, in short, when it is desired to go back to the beginning and the existing data is reset.

For example, we use it to disconnect the socket connection in QR payments.

$events.call('paymentReset');