SDK Events Glossary
This page describes events sent by Payrails SDKs
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 , 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
and onAuthorizeFailed
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 callsonAuthorizeFailed
as terminal event.onThreeDSecureChallenge
- triggered when the user sees the 3D Secure popup.onPaymentSessionExpired
- in case of unauthorized request. Also callsonAuthorizeFailed
as terminal event.onAuthorizeFailed
- when payment authorization fails.onAuthorizeSuccess
- when payment authorization is successful
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 |
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; |
Updated 4 days ago