​

Event Management

​

Transaction Lifecycle

1. Transaction Creation : Once the customer is created, you can assign a transaction to them. This triggers the transaction.created event.
2. Tracking Transactions: A transaction can evolve in several ways:
   • transaction.approved : The transaction has been approved, meaning the payment has been validated.
   • customer.created : When a new customer is added to your account, this generates the event
   • transaction.declined: The payment failed or was rejected.
   • transaction.canceled: The transaction was canceled before it was finalized.
   • transaction.transferred: The funds from the transaction have been transferred to the designated account (e.g., bank account or mobile money).
3. À chaque changement de statut, un nouvel événement est généré pour vous tenir informé. Par exemple, dès qu’une transaction est mise à jour, l’événement transaction.updated est déclenché.

​

Customer Lifecycle

• customer.updated : The customer’s profile has been modified (e.g., their name or email address).
• customer.deleted : The customer has been deleted from your account.

​

How to Use Events ?

​

Why is it Important ?

• Track Payments: You are informed in real-time of the status of each transaction.
• Manage Customers: You can track changes made to customer profiles.
• Automate Processes: With event notifications, you can automate certain tasks on your site, like sending a confirmation email after a successful payment.

​

Introduction to Webhooks

​

Why Use Webhooks ?

• Successful or failed payments.
• Refunds.
• Disputed transactions.

​

How Do Webhooks Work?

​

Configuring Webhooks

1

Creating a Webhook

To receive Webhooks, you need to configure a URL on your site that can receive these notifications. Follow these steps:

• Log in to your FedaPay account.
• Go to the Webhooks section from the dashboard menu.
• Click on Create a Webhook or New Webhook.
• A form opens with several fields to fill in:

Enter the destination URL

• Enter the URL of your site where you want to receive notifications.
• Ensure that this URL is ready to handle Webhooks sent by FedaPay.

Optional settings:

• Disable SSL verification on HTTP requests (optional).
• Disable the Webhook when the application generates errors (optional).

Add HTTP headers

• You can specify custom headers by adding key-value pairs.
• Click the ”+” button to add multiple headers if needed.

Select event types

• Receive all events (by default, you will receive all notifications).
• Select specific events (you can choose only those of interest from the available event list).

Finalization and activation

• Verify that all information is correct.
• Click Create to save and activate the Webhook.

2

Managing Your Webhooks

Once your Webhooks are created, you can:

• Modify: Change the URL or the events you want to track.
• Delete: If you no longer need this Webhook, you can remove it.
• View details: You can see all information about the Webhook (URL, tracked events, etc.).

​

Webhook Event Delivery Strategy

• FedaPay sends an HTTP POST request with the event data.
• FedaPay expects a 2xx status response.
• Any response other than 2xx is considered a failure.

​

Automatic Retry Mechanism

• If execution fails, FedaPay will retry up to 9 times at exponential intervals.
• The retry waiting time does not exceed 2 minutes.
• After 10 unsuccessful attempts, the Webhook is automatically disabled to prevent queue overload.
• You can prevent automatic deactivation by unchecking the option Disable the webhook when the application generates errors in your dashboard.

​

Manual Redelivery

• Go to the Logs page of your webhook.
• Click the Redeliver button.

​

Best Practices for Using Webhooks

​

Handle Duplicate Events

• Store the event IDs of already processed events to avoid reprocessing them.
• Use the object identifier in object and name to detect duplicates.

​

Listen Only to Required Event Types

• Configure your endpoints to receive only necessary events.
• Avoid listening to all events to prevent server overload.
• Modify received events through the dashboard.

​

Handle Events Asynchronously

• Use an asynchronous queue to process webhook events without blocking your system.
• Avoid synchronous processing, which may slow down your infrastructure and cause failures under heavy load.
• Anticipate traffic spikes, especially during mass subscription renewals, to prevent server overload.
• Control processing rates by adjusting event consumption based on your system’s capacity.

​

Receiving Events with an HTTPS Server

• Use an HTTPS URL: FedaPay verifies the security of the connection before sending webhooks.
• Valid SSL certificate: Your server must be properly configured with a valid certificate to prevent connection rejection.
• TLS compatibility: Only TLS v1.2 and v1.3 versions are supported by FedaPay.

​

Verifying That Events Are Sent by FedaPay

const { Webhook } = require('fedapay')

// You can find your endpoint's secret key in your webhook settings
const endpointSecret = 'wh_sandbox...';

// This example uses Express to receive webhooks
const app = require('express')();

// Use body-parser to retrieve the raw body as a buffer
const bodyParser = require('body-parser');

// Match the raw body to content type application/json
app.post('/webhook', bodyParser.raw({type: 'application/json'}), (request, response) => {
  const sig = request.headers['x-fedapay-signature'];

  let event;

  try {
    event = Webhook.constructEvent(request.body, sig, endpointSecret);
  } catch (err) {
    response.status(400).send(`Webhook Error: ${err.message}`);
  }

  // Handle the event
  switch (event.name) {
    case 'transaction.created':
      // Transaction créée
      break;
    case 'transaction.approved'':
      // Transaction approuvée
      break;
    case 'transaction.canceled'':
      // Transaction annulée
      break;
    default:
      console.log(`Unhandled event type ${event.type}`);
  }

  // Return a response to acknowledge receipt of the event
  response.json({received: true});
});

app.listen(4242, () => console.log('Running on port 4242'));