Webhooks

​

Overview

Webhooks enable real-time notifications for your Monieswitch integration, allowing your system to receive automatic updates about important events and transaction statuses.

​

Why Use Webhooks?

Instead of repeatedly checking for updates (polling), webhooks provide instant notifications when events occur in your Monieswitch account. This approach is:

• More efficient than polling
• Not subject to rate limits
• Highly scalable
• Real-time and reliable

​

Webhook Approach

1. One-time webhook URL registration
2. Automatic notifications when events occur
3. Immediate updates
4. More efficient communication

​

Traditional Polling

1. Your server repeatedly requests updates
2. Each request requires a response
3. High number of API calls
4. Potential delays in getting updates

​

Implementation Guide

​

1. Creating Your Webhook Endpoint

Set up a POST endpoint on your server to receive webhook notifications. Your endpoint should:

• Accept JSON payloads
• Return a 200 OK response
• Process events asynchronously

Example implementation:

app.post("/webhooks", function (req, res) {
  res.status(200).send();

  // Process the event asynchronously
  const event = req.body;
  processWebhookEvent(event);
});

​

2. Update Webhook URL in Dashboard

In your Monieswitch account settings, add your webhook URL to receive notifications. This URL should be publicly accessible and secure.

​

Webhook Events

• Payment success
• Payment pending
• Payout success
• Payout pending
• Payout failed

  {
    "event": "virtual.account.payment.success",
    "status": "success",
    "amount": 1000,
    "paidAt": "2024-10-29T11:05:52.847Z",
    "reference": "g99ldgQNyhKWW4M1cXyN2WQqwOBBKqou6dZq",
    "narration": "Sandbox Account funding.",
    "transactionId": "83c6e3d6-3fa6-4695-ae9c-c9989ea20b0a",
    "amountPaid": 1015,
    "merchantId": "0e692b20-8491-4b96-b421-f2548bfce868",
    "settledAmount": 1000,
    "settlementCharge": 15,
    "customerMetadata": {
      "reference": "3v1yqBx4EfdgfP2pkfkeNmq7jYYFfXtcZfCd",
      "isPaymentLink": true,
      "paymentLinkId": "935de945-b2f9-43b3-92b0-0464d39cc6bd"
    },
    "customerReference": "3W42jI6M6vS5BD0lZxS0RNLS1647Vzq8ffJZ",
    "hasActiveSubaccount": false,
    "originatorBankCode": "999270",
    "originatorBankName": "Monieswitch Test Bank",
    "originatorAccountName": "Emmanuel",
    "sessionId": "999270241029110552939605335250",
    "originatorAccountNumber": "0167421242",
    "beneficiaryBankCode": "999270",
    "beneficiaryBankName": "Xpresswallet",
    "beneficiaryAccountName": "TEC-Test Oluwa",
    "beneficiaryAccountNumber": "4486245320"
  }

​

Event Types Reference

​

Payments Account Events

​

virtual.account.payment.success

• Description: Triggered when a virtual account successfully receives a payment
• Status: success
• Key Information:
  • Payment has been confirmed
  • Funds have been credited
  • Settlement process has been completed
  • All fees have been calculated
• When to Use:
  • Update transaction records
  • Confirm payment completion
  • Trigger success notifications
  • Release goods/services

​

virtual.account.payment.pending

• Description: Triggered when a payment to a virtual account is initiated but not yet completed
• Status: pending
• Key Information:
  • Payment has been initiated
  • Funds are being processed
  • Final settlement pending
  • Charges are calculated but not final
• When to Use:
  • Track incoming payments
  • Update transaction status
  • Monitor for completion
  • Hold goods/services until success

​

virtual.account.payment.failed

• Description: Triggered when a virtual account payment fails to process
• Status: failed
• Key Information:
  • Payment attempt unsuccessful
  • Specific failure reason provided
  • No funds transferred
  • May include retry information
• When to Use:
  • Log failed attempts
  • Notify users of failure
  • Trigger retry logic if applicable
  • Update transaction status

​

Payout Events

​

payout.success

• Description: Triggered when a payout (fund transfer) is successfully completed
• Status: SUCCESS
• Key Information:
  • Transfer has been completed
  • Funds have been debited
  • Beneficiary has been credited
  • All fees have been processed
• When to Use:
  • Confirm transfer completion
  • Update transfer records
  • Send confirmation notifications
  • Complete reconciliation

​

payout.failed

• Description: Triggered when a payout attempt fails
• Status: FAILED
• Key Information:
  • Transfer was unsuccessful
  • Error details included
  • Funds not debited or reversed
  • May include retry eligibility
• When to Use:
  • Log failed transfer
  • Notify sender
  • Initiate refund if needed
  • Update transfer status

​

Status Code Reference

​

Common Failure Reasons

​

Virtual Account Payment Failures

• Insufficient funds
• Account restrictions
• Transaction limits exceeded
• Invalid account status
• Network/system errors
• Duplicate transaction
• Fraud detection triggers

​

Payout Failures

• Invalid account details
• Beneficiary bank offline
• Insufficient wallet balance
• Transaction limits exceeded
• Regulatory restrictions
• Network/system errors
• Bank rejection

​

Best Practices

1. Event Handling

   • Always verify event type before processing
   • Implement idempotency checks using reference/transaction IDs
   • Handle each event type independently
   • Log all received events for audit purposes

2. Status Verification

   • Confirm both event type and status match
   • Check failure reasons for failed events
   • Implement appropriate error handling

3. Processing Order

   • Process pending events before success or failed
   • Store pending state for reconciliation
   • Update records for both success and failure events
   • Maintain event sequence for audit trails

4. Failure Handling

   • Implement retry logic where appropriate
   • Store failure reasons for analysis
   • Send appropriate notifications
   • Consider automated recovery flows

​

Event Flow Example

​

Error Recovery Strategies

1. For Failed Payments

   • Log detailed error information
   • Notify user immediately
   • Provide clear next steps
   • Offer retry options if applicable
   • Consider automatic retry for specific error types

2. For Failed Payouts

   • Verify wallet balance status
   • Check beneficiary details
   • Implement automatic retries
   • Provide manual retry option
   • Consider alternative payout methods

Need technical support? Contact the integration team at [email protected]