Webhooks

7min

As an order progresses through it's lifecycle, Pay3 shares webhook events with the App's backend about the status of order and other relevant details. This page explains different status and the information related to the webhook. This page also explains how a App can consume the events towards the end of this page.

API Signature

The application needs to share an API endpoint to which Pay3 service will be sending a webhook as a POST request with a payload which contains webhook data. Below is an example curl of how Pay3 service will be calling the provided webhook endpoint with the data. The API needs to respond back with http status code 200 on receiving the data.

Curl


Sample Payload

Below is an example payload which is received in the webhook events provided by Pay3

JS


Payload Schema

  1. data : Following keys are present in this object.
    1. orderType : Indicates the type of order for which the event is sent for. If the given order contains a crypto transaction as well as fiat transaction, two events of different order types will be sent for the same orderId.
      1. CHECKOUT - Payment done by user using Fiat currency
      2. PAYOUT - Withdraw Fiat request done by user
      3. CRYPTO - Payment done by user using Crypto currency
    2. orderId : It provides a unique identification of the order which is managed by Pay3.
    3. orderStatus : It indicates the various status in which an order can be. Details about different kind of statuses can be find below.
  2. error (Type Object, Optional): Following keys will be present if there is an error. Please refer to SDK Errors for reference
    1. code (Type number): Error code.
    2. message (Type string): Error message.
  3. requestId : Request Id that was passed by App while initialising the modal.
  4. type : Type of the event. For Fiat checkout the app will receive pay3-sdk-transaction-status.

Order Status

Below is the list of status which are shared in webhook for orders related to fiat checkout and payout transactions.

Order Status

Order Status Description

CREATED

Order initiated

ORDER_STARTED

Payment partner has started the order

ORDER_PAYMENT_AWAITING

Payment partner is waiting for user to complete the Payment

ORDER_PAYMENT_PROCESSING

Payment partner checking for payment record.

User will be shown processing screen

ORDER_PAYMENT_INITIATED

Payment partner is checking for payment record and will make the payment.

User can close the Pay3 payment screen

COMPLETED

Payment is successfully completed

FAILED

Error occurred during the process

ABANDONED

Transaction timeout

Payment Status

Some of the Order Status can have payment status

Payment Status

Parent Order Status

Payment Status Description

SUCCESS

COMPLETED

Payment completed successfully

DECLINED

FAILED

Declined by Payment Partner

CANCELED

FAILED

User cancelled the transaction

MAX_RETRIES_REACHED

ABANDONED

Transaction timeout

UNDER_PAID

FAILED

Crypto amount received is less than expected order amount

OVER_PAID

COMPLETED

Crypto amount received is more than order amount

REFUNDED

FAILED

Refund has been completed.

REFUND_INITIATED

FAILED

Refund has been initiated by Pay3

REFUND_FAILED

FAILED

There was in issue with Refund transaction.



Usage of Webhooks functionality

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 :

JS




Some of our downstream partners don't provide with all the statuses , in those cases some events might be skipped. But COMPLETED / FAILED will always be the terminal events.