Event types

Payrails Web SDK has two categories of events:

Category	Description	Event Names
UI Events	Events which are triggered on user interaction with an SDK element or when the payment methods gets shown/ removed from the screen.	`onChange`, `onFocus`, `onCardChange`, `onSaveInstrumentCheckboxChanged`, `onPaymentButtonClicked`, `onReady`, `onGooglePayAvailable`, `onApplePayAvailable`, `onPaypalAvailable`,`onAvailable`, `onPaymentOptionSelected`
Payment Events	Events which are related to the payment authorization lifecycle.	`onAuthorizeSuccess`, `onAuthorizeFailed`, `onAuthorizePending`, `onThreeDSecureChallenge`, `onPaymentSessionExpired`
Generic Events	Events which handles the context depending on which action the SDK element has taken.	`onSuccess`, `onFailed`, `onPending`, `onButtonClicked`, `onRequestStart`

❗️
Important Update:
As of @payrails/[email protected], Payrails Elements’ payment authorization related events are now marked deprecated. For more information, please checkout this page.
Please refer to these generic events as replacements.

Old New
onAuthorizeSuccess onSuccess
onAuthorizeFailed onFailed
onAuthorizePending onPending
onAuthorizeRequestStart onRequestStart
onPaymentButtonClicked onButtonClicked

Old	New
onAuthorizeSuccess	onSuccess
onAuthorizeFailed	onFailed
onAuthorizePending	onPending
onAuthorizeRequestStart	onRequestStart
onPaymentButtonClicked	onButtonClicked

Rules for Event Execution

While UI events are async and trigger on user interaction (such as onChange, onFocus), payment events have some rules and order of execution around them.

onAuthorizeSuccess , onAuthorizeFailed and onAuthorizePending are terminal events. This means each request will result in at least a success or failed state and corresponding event will be fired. Rules for event execution are defined below:

onPaymentButtonClicked (UI Event) - if this returns false, this also calls onAuthorizeFailed as terminal event.
onThreeDSecureChallenge - triggered when the user sees the 3D Secure popup.
onPaymentSessionExpired - in case of unauthorized request. Also calls onAuthorizeFailed as terminal event.
onAuthorizeFailed - when payment authorization fails. With this event you would also get the reason why the execution failed. This is based on the operations codes.
onAuthorizeSuccess - when payment authorization is successful
onAuthorizePending - triggered when the execution is in pending state with no further action required from the user. (Please reach out to your account manager on what could be the potential use cases for this event)

Web SDK Event Glossary

Name	Type	Description	Function Signature
`onPaymentOptionSelected`	UI	triggered each time the payment option is selected for saved instrument both instrument details and payment method config are returned for payment method only payment method config is returned	`(e: onPaymentMethodSelectedParams) => void`
`onSaveInstrumentCheckboxChanged`	UI	triggered each time save instrument checkbox changes state	`({ checked }: { checked: boolean }) => void;`
`onPaymentButtonClicked`	UI	triggered each time, user clicks on the payment button. This event is called just before the SDK makes a call to authorize. callback passed to this event should return a Promise which resolves to a boolean If this callback returns false, SDK does not make the authorize call and the user sees a payment not successful screen and also triggers onAuthorizeFailed event.	`(event?: { bin?: string }) => Promise<boolean>;`
`onStateChanged`	UI	triggered when payment button state changes	`(state: 'enabled' \| 'disabled') => void;`
`onThreeDSecureChallenge`	Payment	triggered just before the user sees the 3ds popup	`() => void;`
`onPaymentSessionExpired`	Payment	triggered when authorization fails due to payment session expiration	`() => void;`
onAuthorizeRequestStart	Payment	triggered only for Apple Pay and Google Pay. triggered after the user actually approves the payment on AP and GP modals and before the authorize request is initiated from the SDK.	`() => void;`
`onAuthorizeSuccess`	Payment	triggered when payment authorization is successful callback passed to this event can pass a param to get more information regarding the authorization	`(event?: any) => void;`
`onAuthorizeFailed`	Payment	generic authorization failure event triggered for all the authorization failure reasons. callback passed to this event can pass a param to get more information regarding the reason of failure	`(event?: { code: 'AUTHORIZATION_ERROR', message: string }) => void`
`onChange`	UI	triggered when changes are made to the card form	`(event: OnChange) => void;`
`onFocus`	UI	triggered when any input field inside the card form triggers focus event	`() => void;`
`onReady`	UI	triggered when the card form is rendered and ready to pay	`() => void;`
`onCardChange`	UI	triggered when user selects a different saved instrument in the saved instrument list	`(selectedCard: StoredPaymentInstrument<CardMetadata>) => void`
`onBillingAddressChanged`	UI	triggered when billing address changes	`((e: { isValid: boolean; billingAddress?: IAddress; }) => void)`
`onDeliveryAddressChanged`	UI	triggers when shipping address changed for express flow	`(((data?: onDeliveryAddressChangedResponse) => Promise<boolean>))`
onSuccess	Generic	triggers when Payrails Elements successfully done a payment or tokenization	`(action: 'AUTHORIZE' \| 'TOKENIZE', response?: any) => void;`
onFailed	Generic	triggers when Payrails Elements failed a payment or tokenization	`(action: 'AUTHORIZE' \| 'TOKENIZE', e?: any) => void;`
onPending	Generic	triggers when Payrails Elements payment or tokenization is in pending or review	`(action: 'AUTHORIZE' \| 'TOKENIZE', e?: any) => void;`
onButtonClicked	Generic	• triggered each time, user clicks on the element button. • This event is called just before the SDK makes a call to either authorize or tokenize. • callback passed to this event should return a Promise which resolves to a boolean • If this callback returns false, SDK does not make the authorize / tokenize call and the user sees a payment / tokenize not successful screen and also triggers onFailed event.	`(e?: { bin?: string }) => Promise<boolean>;`
onRequestStart	Generic	• only for AP and GP. • triggered after the user actually approves the payment on AP and GP modals and before the authorize / tokenize request is initiated from the SDK.	`() => Promise<boolean>;`

React Native Event Glossary

Name	Description	Function Signature
`onAuthorizeSuccess`	Triggered when payment authorization is successful	`() => void;`
`onAuthorizeFailure`	Triggered when payment authorization fails	`() => void;`
`onAuthorizeError`	Triggered in case of when BE returns 5xx or the client throws. For unsuccessful authorizations onAuthorizeFailure is fired	`(error: any) => void;`
`onAuthenticationError`	Triggered when the access token is expired	`() => void;`
`onAuthorizeStart`	Triggered when the payment button is clicked. If the resolved value is false, then the payment is canceled. It fires after a user clicks the payment button. It allows a merchant to perform additional checks and block the payment if needed	`() => Promise<boolean>;`
`onRequestProgressChange`	Triggered when authorization request changes state. It can be used to show a loading state	`(isInProgress: boolean) => void;`
`onAuthorizeCancel`	Triggered when user closed a popup (for paypal) or a webview (for 3DS) without completing the challenge. This is only available for APM hooks: `useExecuteGooglePayPayment` `useExecuteApplePayPayment` `useExecutePayPalPayment`	`() => void;`
`onAuthorizeRequestStart`	triggered after the user actually approves the payment on APM modals (Apple Pay, Google Pay or Paypal) and before the authorize request is initiated from the SDK.	`() => void;`
`onSessionExpired`	triggered when the client session is expired. merchants can pass the function which contains their implementation of client init as part of the `onSessionExpired` event. This then can be used to automatically reinitialize the client when the client session is expired instead of merchants having to do this themselves.	`() => Promise<InitOptions>`