GuidesAPI ReferenceHelp CenterStatus PageBlogGet API Keys

Webhook events

Webhook events fired on various Issuing events

Suggest Edits

Overview

Issuing webhook events are fired based on the following triggers:

  1. Wallet funding webhook events.
  2. Virtual account webhook events.
  3. Bank account webhook events.
  4. Fund transfer webhook events.
  5. Virtual cards webhook events.

📘

NOTE

  • Please note that a single webhook URL receives webhooks for both test and live environments.
  • To identify a test webhook from a live webhook event, a live boolean field is passed to the data object of your webhook event to identify between the two; false indicating test and true indicating live.

1. Wallet Funding Webhooks

a. Issuing USD Wallet Funding

This webhook event is fired when the USD issuing wallet is credited, on the following scenarios:
a. When a USD issuing wallet have been successfuly funded via our Fund wallet API.
b. When virtual USD card liquidation runs successfully.

{
      "event": "issuing.wallet_credit_successful",
      "data": {
        "amount": 20000,
        "balance": 119816460,
        "currency": "USD",
        "status": "successful",
        "narration": "Mono Issuing USD Wallet Funding",
        "meta": {
          "reference": "UEFA2022"
        }
      }
}

b. Issuing NGN Wallet Funding

This webhook event is fired when the NGN issuing wallet is credited, on the following scenarios:
a. When a NGN issuing wallet have been successfuly funded via our Fund wallet API.
b. When virtual NGN card liquidation runs successfully.

{
      "event": "issuing.wallet_credit_successful",
      "data": {
        "amount": 80000,
        "balance": 780060,
        "currency": "NGN",
        "status": "successful",
        "narration": "Mono Issuing NGN Wallet Funding",
        "meta": {
          "reference": "UEFA2024"
        }
      }
}

2. Virtual Account Webhooks

a. Virtual Account Created (issuing.virtual_account_created)

This webhook event gets sent when a virtual account is created successfully.

{
    "event": "issuing.virtual_account_created",
    "data": {
      "id": "62feb98914ea1234567890",
      "status": "active",
      "account_name": "MONO - King Kenway",
      "account_number": "1234567890",
      "bank_name": "Fidelity Bank",
      "bank_code": "070",
      "live": true
    }
}

b. Virtual Account Freezed (issuing.virtual_account_freezed)

When an account exceeds the KYC Level Limit for credits into the account, the account is placed on freeze and this webhook event is sent

{
   "event":"issuing.virtual_account_freezed",
   "data":{
      "id": "62617e7dc7c34e763692ae03",
      "amount": 5000000,
      "message": "Transfer amount into account exceeded KYC limit",
      "live": false
   }
}

c. Virtual Account Upgraded (issuing.virtual_account_upgraded)

When a virtual account gets upgraded this webhook event is sent.

{
  "event": "issuing.virtual_account_upgraded",
  "data": {
    "id": "61a8f60ecfb84076108ebd53",
    "kyc_level": "2",
    "live": false
  }
}

d. Virtual Account Liquidation Success (issuing.virtual_account_liquidated)

When a virtual account gets liquidated successfully, the webhook event below is sent.

{
    "event": "issuing.virtual_account_liquidated",
    "data": {
      "id": "6353c11c8514c1da7d5daf6d",
      "currency": "NGN",
      "liquidatedAmount": 20000,
      "exchangeRate": 1,
      "wallet": "NGN",
      "creditAmount": 20000,
      "live": true,
      "status": "successful",
    }
}

e. Virtual Account Liquidation Failure (issuing.virtual_account_liquidation_failed)

When a virtual account liquidation operation fails, the webhook event below is sent.

{
    "event": "issuing.virtual_account_liquidation_failed",
    "data": {
      "id": "6353c11c8514c1da7d5daf6d",
      "currency": "NGN",
      "liquidatedAmount": 20000,
      "exchangeRate": 1,
      "wallet": "NGN",
      "creditAmount": 20000,
      "live": true,
      "status": "failed",
    }
}

3. Bank Account Webhooks

a. Bank Account Created (issuing.bank_account_created)

This webhook event is sent when a bank account is created.

{
  event: "issuing.bank_account_created",
  data: {
    _id: "62f051f7c7a5e74293f2bae6",
    status: "active",
    accountName: "Femi Alayesanmi",
    accountNumber: "09028600982",
    bankName: "Safe Haven MFB",
    bankCode: "090286",
    live: false
  } 
}

b. Bank Account Creation Failed (issuing.bank_account_failed)

This event gets fired when a bank account fails to be created.

{
  event: "issuing.bank_account_failed",
  data: {
    accountHolder: "62f051f7c7a5e74293f2bae6",
    message: "Could not be created, please try again",
    live: false
  } 
}

4. Fund Transfer Webhooks

a. Transfer Successful (issuing.transfer_successful)

This event is sent for when a fund transfer process is successful from either a bank account or a virtual account.

{
  "event": "issuing.transfer_successful",
  "data": {
    "amount": 10000,
    "balance": 60000,
    "narration": "test",
    "currency": "NGN",
    "account": "61c4797874f68e012cd027cd",
    "type": "debit",
    "date": "2021-12-23T13:32:38.030Z",
    "fee": 0,
    "beneficiary": {
      "name": "OLANIPEKUN OLAYINKA",
      "account_number": "0029873434",
      "bank_code": "044"
    },
    "meta": {
      "cus": "9023023 OLAYINKA",
      "charge_transfer_fee": true,
      "transaction_id": "05840643605"
    },
    "message": "Approved by Financial Institution",
    "live": true,
    "id": "61c47a7a006a37404b9fcee4"
  }
}

b. Transfer Failed (issuing.transfer_failed)

This event is sent when a fund transfer process fails from either a bank account or a virtual account.

{
  "event": "issuing.transfer_failed",
  "data": {
    "amount": 300000,
    "balance": 30000,
    "narration": "chizoba",
    "currency": "NGN",
    "account": "61c4797874f68e012cd027cd",
    "type": "debit",
    "date": "2021-12-23T13:36:18.433Z",
    "fee": 0,
    "beneficiary": {
      "name": "OLANIPEKUN OLAYINKA",
      "account_number": "0029873434",
      "bank_code": "044"
    },
    "message": "Insufficient Funds",
    "live": true,
    "id": "61c47b56006a37404b9fcf12"
  }
}

c. Transfer received (issuing.transfer_received)

This webhook event gets sent when a transaction has been received into either a bank or virtual account.

{
    "event": "issuing.transfer_received",
    "data": {
      "id": "61b1c645c27eb862e7ad5cd3",
      "amount": 10000,
      "balance": 10000,
      "narration": "App  To TANGERINE MONEY KING AHMED",
      "currency": "NGN",
      "account": "61b1c54887902462b5f2890d",
      "type": "credit",
      "date": "2021-12-09T09:02:31.989Z",
      "live": true,
      "fee": 0,
      "source": {
        "name": "OLANIPEKUN IFEOLUWA OLAYINKA",
        "account_number": "7470605015"
      }
    }
  }

5. Virtual Cards Webhooks

a. Virtual Card Created for USD (issuing.virtual_card_created)

This webhook event is sent when a USD virtual card gets created.

{
    "event": "issuing.virtual_card_created",
    "data": {
      "id": "61b354e233b1ba7122226907",
      "status": "active",
      "expiry_year": "e745a26ba5b8bbe94f51eecf1208c17c2f27476d7a1533a6dc1eb7dcaa6ad70c",
      "expiry_month": "e745a26ba5b8bbe94f51eecf1208c17c2f27476d7a1533a6dc1eb7dcaa6ad70c",
      "disposable": false,
      "card_masked": "536898**9887",
      "card_number": "e745a26ba5b8bbe94f51eecf1208c17c2f27476d7a1533a6dc1eb7dcaa6ad70c",
      "currency": "USD",
      "last4": "e745a26ba5b8bbe94f51eecf1208c17c2f27476d7a1533a6dc1eb7dcaa6ad70c",
      "cvv": "e745a26ba5b8bbe94f51eecf1208c17c2f27476d7a1533a6dc1eb7dcaa6ad70c",
      "live": false
    }
}

b. Virtual Card Created for NGN (issuing.virtual_card_created)

This webhook event is sent when a NGN virtual card gets created.

{
    "event": "issuing.virtual_card_created",
    "data": {
      "id": "61b354e233b1ba7122226907",
      "status": "active",
      "expiry_year": "e745a26ba5b8bbe94f51eecf1208c17c2f27476d7a1533a6dc1eb7dcaa6ad70c",
      "expiry_month": "e745a26ba5b8bbe94f51eecf1208c17c2f27476d7a1533a6dc1eb7dcaa6ad70c",
      "disposable": false,
      "card_masked": "536898**9887",
      "card_number": "e745a26ba5b8bbe94f51eecf1208c17c2f27476d7a1533a6dc1eb7dcaa6ad70c",
      "currency": "NGN",
      "last4": "e745a26ba5b8bbe94f51eecf1208c17c2f27476d7a1533a6dc1eb7dcaa6ad70c",
      "cvv": "e745a26ba5b8bbe94f51eecf1208c17c2f27476d7a1533a6dc1eb7dcaa6ad70c",
      "live": false,
      "pin": "a545a26ba5b8bbe94f51eecf1208c17c2f27476d7a1533a6dc1eb7dcaa6a90bc",
    }
}

c. Card Transaction USD (issuing.card_transaction)

This webhook event is sent when a USD card transaction gets initiated.

{
    "event": "issuing.card_transaction",
    "data": {
      "id": "61b355d35fe5d3715e9a4196",
      "amount": 10000,
      "balance": 10000,
      "type": "credit",
      "currency": "USD",
      "card": "61b354e233b1ba7122226907",
      "date": "2021-12-10T13:27:41.288Z",
      "narration": "20200823t06:13:45/idigic internet nor",
      "live": false
    }
  }
}

d. Card Transaction NGN (issuing.card_transaction)

This webhook event is sent when a NGN card transaction gets initiated.

{
    "event": "issuing.card_transaction",
    "data": {
     "id": "630e0a06008350676a4e0d9c",
      "amount": 5000,
      "balance": 3500,
      "type": "debit",
      "currency": "NGN",
      "card": "62f2bc968c3c1945b078ae2b",
      "date": "2022-08-30T13:00:54.619Z",
      "narration": "RELENTLESSLABS/YHFG1450",
      "live": true,
      "fee": 0
    }
  }
}

e. Card Liquidation Success (issuing.virtual_card_liquidated)

This webhook event is sent when a virtual card is liquidated.

{
    "event": "issuing.virtual_card_liquidated",
    "data": {
      "id": "630500aea104963ecc5152eb",
      "currency": "USD",
      "liquidated_amount": 100,
      "exchange_rate": 550,
      "wallet": "NGN",
      "credit_amount": 55000,
      "live": true,
      "transaction": "622984238948239ae12c"
    }
  }

f. Card Liquidation Failure (issuing.virtual_card_liquidation_failed)

This webhook event is sent when a virtual card fails to get liquidated.

{
    "event": "issuing.virtual_card_liquidation_failed",
    "data": {
      "id": "6353c11c8514c1da7d5daf3d",
      "currency": "NGN",
      "liquidatedAmount": 20000,
      "exchangeRate": 1,
      "wallet": "NGN",
      "creditAmount": 20000,
      "live": true,
      "status": "failed",
    }
}

g. Card transaction failed (issuing.card_transaction_failed)

This webhook event is sent when a USD or NGN card could not be charged or card funding fails.

{
    "event": "issuing.card_transaction_failed",
    "data": {
      "amount": 999,
      "date": "2022-09-27T17:11:53.776Z",
      "type": "debit",
      "card": "6307b1b667c5a1de1e2f159f",
      "currency": "USD",
      "balance": 0,
      "id": "63332ed979d1d23ee987cd9b",
      "narration": "APPLE.COM/BILL",
      "live": true
    }
}

Updated 5 months ago