Webhooks

Webhooks make the integration with Fizen Pay easier by allowing you to subscribe to a set of charge events.

You can subscribe to the events by going to your Settings page and adding a new webhook subscription. When you create a new subscription, you can specify what events you would like to receive updates for. Below is the list of all available webhook events:

EVENT	DESCRIPTION	CHARGE STATUS
charge.created	A new charge is created	NEW
charge.canceled	A new charge is canceled	CANCELED
charge.completed	A payment is made for the charge and the conditions are met.	COMPLETED
charge.unresolved	A payment is made for the charge and the conditions are NOT met.	UNRESOLVED
charge.resolved	The UNRESOLVED charge is marked as resolved by the owner	RESOLVED
charge.refunded	The charge is marked as refunded by the owner	REFUNDED

Webhook details

The event topic, signature, and id are included in the headers of the response to the webhook endpoint. The headers are: x-fp-webhook-topic, x-fp-webhook-signature, and x-fp-webhook-id corresponding

Header:

x-fp-webhook-topic: "charge.completed"
x-fp-webhook-signature: "2acb37d82dd72e76ebfe08294c5e71a38918b49f76a9fd393b7aeb3d842fb895"
x-fp-webhook-id: "624c247239eba8000801eee3"

The charge details are included in the body of the response.

Event Payload example

{
  "charge": {
    "addresses": {
      "bnb-bsc": {
        "address": "0x0000000000000000000000000000000000000000",
        "cmcId": 1839,
        "contract": "0x237B15c5ddA7809fC1Cb0d1a8bD31F5eA232Cc24",
        "network": "binance-smart-chain-testnet"
      },
      "busd-bsc": {
        "address": "0x718f381412b0ec0B9a6f69a77E3c7128C75E77B5",
        "cmcId": 4687,
        "contract": "0x237B15c5ddA7809fC1Cb0d1a8bD31F5eA232Cc24",
        "network": "binance-smart-chain-testnet"
      },
      "doge-bsc": {
        "address": "0x6aed42281c7bE19fa5f7a6ee5d873B85A5306bFe",
        "cmcId": 74,
        "contract": "0x237B15c5ddA7809fC1Cb0d1a8bD31F5eA232Cc24",
        "network": "binance-smart-chain-testnet"
      },
      "eth-bsc": {
        "address": "0x17fA95F49e69F82766C7930D4035b2973fbe95b8",
        "cmcId": 2396,
        "contract": "0x237B15c5ddA7809fC1Cb0d1a8bD31F5eA232Cc24",
        "network": "binance-smart-chain-testnet"
      },
      "luna-bsc": {
        "address": "0xc4E4FE5FcB38fE9D3BC327e384A57105955C9F9d",
        "cmcId": 4172,
        "contract": "0x237B15c5ddA7809fC1Cb0d1a8bD31F5eA232Cc24",
        "network": "binance-smart-chain-testnet"
      },
      "shib-bsc": {
        "address": "0x00A7D83B69C8c9223438F0Aca93453c89e0E66Ac",
        "cmcId": 5994,
        "contract": "0x237B15c5ddA7809fC1Cb0d1a8bD31F5eA232Cc24",
        "network": "binance-smart-chain-testnet"
      },
      "usdc-bsc": {
        "address": "0x3a943EFa37979952DE37168aE7D9B2E8723D9316",
        "cmcId": 3408,
        "contract": "0x237B15c5ddA7809fC1Cb0d1a8bD31F5eA232Cc24",
        "network": "binance-smart-chain-testnet"
      },
      "usdt-bsc": {
        "address": "0x53653887c75d611A8EfbdA2c1FB97CFD17Bfff71",
        "cmcId": 825,
        "contract": "0x237B15c5ddA7809fC1Cb0d1a8bD31F5eA232Cc24",
        "network": "binance-smart-chain-testnet"
      }
    },
    "amountReceived": [
      {
        "crypto": "BNB",
        "cryptoAmount": "0.000614952066849013",
        "localAmount": "0.2",
        "localCurrency": "USD",
        "transactionHash": "0x08c60c38a600e63905b19a2775b1d662a846c06f726bfeb5c0f419a2c58422bc"
      },
      {
        "crypto": "BNB",
        "cryptoAmount": "0.000614952066849113",
        "localAmount": "0.2",
        "localCurrency": "USD",
        "transactionHash": "0x1ef2640f920c46ee02b82d079e9a83a1cc602063325609c7b66f9c0a920faaea"
      }
    ],
    "code": "ML1A7PJ3F3PY",
    "context": "MULTIPLE",
    "createdAt": "2022-05-23T06:58:49.557Z",
    "currencyType": "LOCAL_CURRENCY",
    "customerEmail": "[e-mail]",
    "customerName": "",
    "exchangeRateByUSD": "1",
    "exchangeRates": {
      "bnb-bsc-usd": "325.2286003765969",
      "busd-bsc-usd": "1.0005404341502755",
      "doge-bsc-usd": "0.08652585187256893",
      "eth-bsc-usd": "2050.8523351464096",
      "luna-bsc-usd": "0.00019356603824367347",
      "shib-bsc-usd": "0.000012191971099821102",
      "usdc-bsc-usd": "1.0003980008414488",
      "usdt-bsc-usd": "0.9991066318536912"
    },
    "expiredAt": "2022-05-24T06:58:49.544Z",
    "fizenpayFeePerc": "33",
    "flexiblePaymentSettings": {
      "overPaymentCurrency": "USD",
      "overPaymentThresholdValue": "2000",
      "type": "RELATIVE",
      "underPaymentCurrency": "USD",
      "underPaymentThresholdValue": "50"
    },
    "hostedUrl": "https://payment.fizen.io/commerce/charges/ML1A7PJ3F3PY",
    "id": "628b30a923ed950008b950a9",
    "localCurrency": "USD",
    "localExchangeRates": {
      "bnb-bsc-usd": "325.2286003765969",
      "busd-bsc-usd": "1.0005404341502755",
      "doge-bsc-usd": "0.08652585187256893",
      "eth-bsc-usd": "2050.8523351464096",
      "luna-bsc-usd": "0.00019356603824367347",
      "shib-bsc-usd": "0.000012191971099821102",
      "usdc-bsc-usd": "1.0003980008414488",
      "usdt-bsc-usd": "0.9991066318536912"
    },
    "localPrice": {
      "amount": "0.2",
      "currency": "USD"
    },
    "merchant": {
      "email": "[e-mail]",
      "name": null
    },
    "merchantId": "628603dd75ebdf00083568dc",
    "name": "INVOICE - ML1A7PJ3F3PY",
    "payment": {
      
    },
    "pricing": {
      "bnb-bsc": {
        "amount": "0.000614952066849013",
        "cmcId": 1839,
        "currency": "BNB",
        "decimal": 18,
        "network": "binance-smart-chain-testnet",
        "networkId": "97",
        "transferAmount": "614952066849013"
      },
      "busd-bsc": {
        "amount": "0.199891971552207288",
        "cmcId": 4687,
        "currency": "BUSD",
        "decimal": 18,
        "network": "binance-smart-chain-testnet",
        "networkId": "97",
        "transferAmount": "199891971552207288"
      },
      "doge-bsc": {
        "amount": "2.311447916104313901",
        "cmcId": 74,
        "currency": "DOGE",
        "decimal": 18,
        "network": "binance-smart-chain-testnet",
        "networkId": "97",
        "transferAmount": "2311447916104313901"
      },
      "eth-bsc": {
        "amount": "0.000097520429224721",
        "cmcId": 2396,
        "currency": "WETH",
        "decimal": 18,
        "network": "binance-smart-chain-testnet",
        "networkId": "97",
        "transferAmount": "97520429224721"
      },
      "luna-bsc": {
        "amount": "1033.239104414727143858",
        "cmcId": 4172,
        "currency": "LUNA",
        "decimal": 18,
        "network": "binance-smart-chain-testnet",
        "networkId": "97",
        "transferAmount": "1033239104414727143858"
      },
      "shib-bsc": {
        "amount": "16404.238360024876160848",
        "cmcId": 5994,
        "currency": "SHIB",
        "decimal": 18,
        "network": "binance-smart-chain-testnet",
        "networkId": "97",
        "transferAmount": "16404238360024876160848"
      },
      "usdc-bsc": {
        "amount": "0.199920431500040177",
        "cmcId": 3408,
        "currency": "USDC",
        "decimal": 18,
        "network": "binance-smart-chain-testnet",
        "networkId": "97",
        "transferAmount": "199920431500040177"
      },
      "usdt-bsc": {
        "amount": "0.200178833393318847",
        "cmcId": 825,
        "currency": "USDT",
        "decimal": 18,
        "network": "binance-smart-chain-testnet",
        "networkId": "97",
        "transferAmount": "200178833393318847"
      }
    },
    "pricingType": "fixed_price",
    "showLogo": true,
    "status": "UNRESOLVED",
    "supportEmail": "[e-mail]",
    "timeline": [
      {
        "context": null,
        "status": "NEW",
        "time": "2022-05-23T06:58:49.557Z",
        "transactionDetail": null
      },
      {
        "context": null,
        "status": "PENDING",
        "time": "2022-05-23T07:01:41.758Z",
        "transactionDetail": null
      },
      {
        "context": null,
        "status": "COMPLETED",
        "time": "2022-05-23T07:01:51.660Z",
        "transactionDetail": "https://testnet.bscscan.com/tx/0x08c60c38a600e63905b19a2775b1d662a846c06f726bfeb5c0f419a2c58422bc"
      },
      {
        "context": null,
        "status": "PENDING",
        "time": "2022-05-23T07:02:18.664Z",
        "transactionDetail": null
      },
      {
        "context": "MULTIPLE",
        "status": "UNRESOLVED",
        "time": "2022-05-23T07:02:24.639Z",
        "transactionDetail": "https://testnet.bscscan.com/tx/0x1ef2640f920c46ee02b82d079e9a83a1cc602063325609c7b66f9c0a920faaea"
      }
    ],
    "transactionType": "INVOICE",
    "updatedAt": "2022-05-26T09:04:10.037Z"
  }
}

Edit webhook

You can specify the topics that you want to receive and test the topics for the integration by clicking on Edit button beside the Webhook endpoint in the Setting page.

Securing webhooks

Every webhook request includes an x-fp-webhook-signature header. This header contains the SHA256 HMAC signature of the raw request payload, computed using your webhook shared secret as the key. You can obtain your shared webhook secret from your Settings Page . Always make sure that you verify the webhook signature before acting on it inside your system.