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`

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.
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;`
`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?: any) => 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)`

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;`