Webhooks

Webhook Flow

Webhook trigger:
A webhook is sent when a transaction reaches one of the following statuses:

SUCCESS: The transaction completed successfully.
FAILED: The transaction failed because of an issue such as invalid card details or insufficient funds.
BLOCKED: The transaction was blocked because of security concerns or policy checks.
ABANDONED: The customer left the transaction before completing payment.

Webhook retries:
If delivery fails, for example because of server unavailability or timeout, the system retries the webhook up to 3 times at predefined intervals. After the third failed attempt, the webhook is marked as undelivered.
Security and hash validation:
Users can configure their own secret or unique key for added security. The system sends this value in the fs-webhook-hash header so you can verify the authenticity of the webhook.

Webhook Headers

The webhook request contains the following headers:

Header Name	Description
`Content-Type`	Defines the content type. Always set it to `application/json`.
`fs-webhook-hash`	Contains the secret value configured in the account settings and is used to verify incoming webhooks.

Webhook Payload

The webhook payload includes transaction details and the current status. The payload structure changes based on the transaction type (Card/APM or Crypto).

Important

Webhook payloads vary by payment method:

Card & APM transactions: Standard webhook payload with refund and chargeback details.
Crypto Payin transactions: Extended payload with additional cryptocurrency fields such as crypto_currency, crypto_network, crypto_payment_status, and payment amounts.

Card & APM Transactions

For card and alternative payment method (APM) transactions, the webhook returns the standard payment details.

{
"status": "SUCCESS",
"message": "Transaction processed successfully!.",
"data": {
  "amount": 100,
  "currency": "GBP",
  "order_id": null,
  "transaction_id": "TPC7663692011084535",
  "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",
  "is_card_WL": false
}
}

Crypto Payin Transactions

For cryptocurrency Payin transactions, the webhook includes extra crypto-specific fields. These fields provide more detail about the cryptocurrency used, the network, and the payment status.

Note

This webhook format applies only to Crypto Payin transactions. Other crypto payment types can return different response structures.

{
"status": "SUCCESS",
"message": "Transaction processed successfully!.",
"data": {
  "amount": 10,
  "currency": "USD",
  "order_id": null,
  "transaction_id": "TPC7945391549251682",
  "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	Cryptocurrency used for the payment, such as TRX, BTC, ETH, or USDT.
`crypto_network`	String	Blockchain network used for the transaction, such as TRON or Ethereum.
`crypto_payment_status`	String	Current crypto payment status. Possible values are `FULLPAID`, `UNDERPAID`, and `OVERPAID`.
`crypto_amount`	Number	Expected crypto amount for the transaction.
`crypto_paid_amount`	Number	Actual crypto amount received from the customer.

Understanding Crypto Payment Status

FULLPAID: The exact crypto amount was received, so the transaction is successful.
UNDERPAID: The received amount is lower than required, so the transaction may fail.
OVERPAID: The received amount is higher than required, and excess handling depends on your configuration.