Webhooks

Webhooks allow you to receive real-time notifications about the status of transactions processed through the payment gateway. Whenever a transaction reaches a final status (e.g., `SUCCESS`, `FAILED`, or `BLOCKED`), the system sends a webhook to the URL configured by the user.

Webhook Workflow

Triggering the Webhook:
A webhook is triggered when a transaction reaches one of the following statuses:
- SUCCESS: The transaction is successfully processed.
- FAILED: The transaction failed due to an issue (e.g., invalid card details or insufficient funds).
- BLOCKED: The transaction is blocked due to security concerns or policy violations.
Resending Webhooks:
If the webhook fails (e.g., due to server unavailability or timeout), the system retries the webhook up to 3 times at predefined intervals. After the third failure, the webhook is marked as undelivered.
Security and Hash Validation:
Users can set their own secret or unique key for enhanced security.The system will sent in the header fs-webhook-hash. This allows users to verify the authenticity of the webhook.

Webhook Headers

The webhook request includes the following headers:

Header Name	Description
`Content-Type`	Specifies the content type. Always set to `application/json`.
`fs-webhook-hash`	A hash generated using the user's encryption key to verify webhook authenticity.

Webhook Payload

The webhook payload contains details about the transaction and its status. The structure of the webhook payload varies depending on the transaction type (Card/APM or Crypto).

Important

The webhook response format differs based on the payment method:

Card & APM Transactions: Standard webhook payload with refund and chargeback information.
Crypto Payin Transactions: Enhanced payload with additional cryptocurrency-specific fields like crypto_currency, crypto_network, crypto_payment_status, and payment amounts.

Card & APM Transactions

For card and alternative payment method (APM) transactions, the webhook includes standard payment information.

{
    "status": "SUCCESS",
    "message": "Transaction processed successfully!.",
    "data": {
        "amount": 100,
        "currency": "GBP",
        "order_id": null,
        "transaction_id": "PA7663692011084535",
        "customer": {
            "first_name": "James",
            "last_name": "dean",
            "email": "james@gmail.com"
        },
        "refund": {
            "status": false,
            "refund_date": null
        },
        "chargeback": {
            "status": false,
            "chargeback_date": null
        },
        "descriptor": "xbank"
    }
}

Crypto Payin Transactions

For cryptocurrency Payin transactions, the webhook includes additional fields specific to crypto payments. These fields provide detailed information about the cryptocurrency used, network, and payment status.

Note

This webhook format is specifically for Crypto Payin transactions only. Other crypto payment types may have different response structures.

{
    "status": "SUCCESS",
    "message": "Transaction processed successfully!.",
    "data": {
        "amount": 10,
        "currency": "USD",
        "order_id": null,
        "transaction_id": "PA7945391549251682",
        "customer": {
            "first_name": "James",
            "last_name": "doe",
            "email": "james@gmail.com"
        },
        "refund": {
            "status": false,
            "refund_date": null
        },
        "crypto_currency": "TRX",
        "crypto_network": "TRON",
        "crypto_payment_status": "FULLPAID",
        "crypto_amount": 10,
        "crypto_paid_amount": 10
    }
}

Additional Crypto Fields:

Field	Type	Description
`crypto_currency`	String	The cryptocurrency used for the payment (e.g., TRX, BTC, ETH, USDT).
`crypto_network`	String	The blockchain network used for the transaction (e.g., TRON, Ethereum).
`crypto_payment_status`	String	The status of the crypto payment. Possible values: `FULLPAID`, `UNDERPAID`, `OVERPAID`.
`crypto_amount`	Number	The expected cryptocurrency amount for the transaction.
`crypto_paid_amount`	Number	The actual cryptocurrency amount paid by the customer.

Crypto Payment Status

FULLPAID: The exact crypto amount was received. Transaction is successful.
UNDERPAID: Less than the required amount was received. Transaction may fail.
OVERPAID: More than the required amount was received. Excess amount handling depends on your configuration.