Webhooks
Pay3 shares webhook events with the dApp about the status of Login and Payment process along with other relevant details. This section explains different statuses and the information related to the webhook. This section also explains how a dApp can consume the events towards the end.
Pay3 shares webhook events which contains the requestId passed while initialising the modal. These events can be consumed by dApp's backend system and consecutively the dApp can update the frontend state by maintaining a server session mapped to that particular requestId.
Below diagram shows consumption method of webhooks.
The payload of webhooks is in the form of JSON Web Tokens (JWT). These tokens can be decoded using a secret to retrieve the status for a given order. This secret will be shared by Pay3 team.
Sample code to decode data :
Below is an example payload which is received in the login webhook events provided by Pay3
Payload Schema :
- data : Following keys are present in this object.
- isLoggedIn : True if user is loggedIn.
- address : Wallet address of connected user. It has value null if user is not logged in.
- error (Type Object, Optional): Following keys will be present if there is an error. Please refer to SDK Errors for reference.
- code (Type number): Error code.
- message (Type string): Error message.
- requestId : Request Id that was passed by dAppwhile initialising the modal
- type : Type of the event. For Login webhooks , it will be pay3-sdk-login-status
Below is an example payload which is received in the payment webhook events provided by Pay3
Payload Schema :
- data : Following keys are present in this object.
- orderType : Type of order which can be CRYPTO, FIAT or CHECKOUT.
- orderId : Unique Id of Order which is created by Pay3
- orderStatus : Status of the order. There can be multiple status for a given order depending upon if it’s a crypto, fiat or checkout order. Details of these statuses are in below section.
- error (Type Object, Optional): Following keys will be present if there is an error. Please refer to SDK Errors for reference.
- code (Type number): Error code.
- message (Type string): Error message.
- requestId : Request Id passed while initialising the modal
- type : Type of the event. For Login webhooks , it will be pay3-sdk-transaction-status.
As an order goes through various states during it's lifecycle. Below are different states which are send in webhooks for payment webhooks.
Below is the list of order statuses which are shared in webhooks for orders related to crypto transactions and there description.
Order Status | Order Status Description |
|---|---|
CREATED | Transaction has been created |
COMPLETED | Transaction is complete |
ERROR | Error occurred during transaction execution |
Below is the list of order statuses which are shared in webhook for orders related to fiat onramp/offramp transactions and there description.
Order Status | Order Status Description |
|---|---|
ORDER_STARTED | OnRamp / OffRamp process has been initiated |
ORDER_PAYMENT_AWAITING | Ramp Partner is waiting for user to complete the Payment |
ORDER_PAYMENT_PROCESSING | Ramp partner has acknowledged receiving the payment |
COMPLETED | Asset has been transferred to the user |
ERROR | Error occurred during the process |
Some of our downstream partners don't provide with all the statuses , in those cases some events might be skipped. But COMPLETED / ERROR will always be the terminal events.
