API Reference

Webhooks

Overview

Centiiv's webhook system allows developers to receive real-time notifications about payment and escrow events. Webhooks provide an automated way to integrate Centiiv's API with your platform, enabling you to take actions based on transaction events.

Webhook Event Types

Centiiv supports the following webhook events:

1. payment.successful

Triggered when a payment is successfully processed.

Payload Structure

{
  "transactionId": "string",
  "amount": 10000,
  "currency": "NGN",
  "status": "successful",
  "paymentMethod": "bank_transfer",
  "customer": {
    "id": "string",
    "email": "string",
    "name": "string"
  },
  "metadata": {
    "resourceId": "string",
    "resourceType": "string" // invoice or escrow or payment-link
  }
}

2. escrow.deposit_successful

Triggered when an escrow deposit is successfully made.

Payload Structure

{
  "transactionId": "string",
  "amount": 10000,
  "currency": "NGN",
  "status": "successful",
  "depositor": {
    "id": "string",
    "email": "string",
    "name": "string"
  },
  "metadata": {
    "resourceId": "string",
    "trackingId": "string",
    "resourceType": "string" // invoice or escrow or payment-link
  }
}

3. escrow.transaction_fulfilled

Triggered when an escrow transaction is fulfilled.

Payload Structure

{
  "transactionId": "string",
  "amountToBeReleased": 10000,
  "currency": "NGN",
  "status": "successful",
  "buyer": {
    "id": "string",
    "email": "string",
    "name": "string"
  },
  "verifiedAt": "string", // ISO date string
  "metadata": {
    "resourceId": "string",
    "trackingId": "string",
    "resourceType": "string" // invoice or escrow or payment-link
  }
}

Setting Up Webhooks

To receive webhook events from Centiiv:

  1. Register your webhook URL from your Centiiv dashboard.
  2. Ensure your endpoint is accessible and capable of handling HTTP POST requests.
  3. Validate incoming requests by verifying the payload structure.
  4. Implement necessary business logic to process webhook events.

Verifying Webhook Calls

To ensure the request is from us, verify the X-Centiiv-Signature header using HMAC with your webhook secret.

TypeScript Example

function verifyWebhook(payload: string, signature: string): boolean {
  const hmac = crypto.createHmac('sha256', WEBHOOK_SECRET);
  hmac.update(payload);
  const calculatedSignature = hmac.digest('hex');
  return calculatedSignature === signature;
}

Retry Policy

If your server does not respond with a 200 HTTP status, we will retry delivery with exponential backoff:

  • 1st retry: 5 minutes
  • 2nd retry: 10 minutes
  • 3rd retry: 30 minutes

After three failed attempts, the webhook delivery will be dropped.

Handling Webhook Requests

Ensure your server:

  • Responds with 200 OK upon successful processing.
  • Processes requests asynchronously to avoid timeouts.
  • Logs webhook events for debugging purposes.

For additional support, contact our support team.