Integrating Webhook

The API payment webhook is a powerful tool that keeps your system updated about the status of transactions processed through the API. This guide will walk you through the steps to integrate the API payment webhook with your system.

Step 1: Set up a webhook URL

The first step is to create an endpoint in your application that will receive and handle incoming webhook POST requests. This URL must be publicly accessible and should use HTTPS to ensure the security of the data being transmitted.

Step 2: Set up a webhook URL

After setting up your endpoint and configurate it on the system. The API will send webhook notifications to your specified endpoint.

Step 3: Handle the Webhook Payload

The payload sent via the webhook POST request contains information about the event that triggered the webhook and the related data. You need to parse this payload and update your system accordingly.

---

Payin (Collection) Payload

The webhook payload for a payment collection may contain the following fields:

Fields

• event: The type of event that triggered the webhook
  e.g., payment.success.webhook, payment.failed.webhook
• data: An object containing details of the transaction:
  • payment_token: A unique identifier for the payment intent.
  • merchant_transaction_id: Your internal reference for the transaction.
  • amount: The payment amount.
  • currency: The payment currency.
  • payee: The recipient of the payment.
  • payment_method: The method used for the payment.
  • payment_processing_reference: Reference from the payment processor.
  • payment_status: The current status of the payment
    e.g., success, failed
  • payment_status_code: Status code from the payment processor.
  • payment_status_message: A message from the processor about the status.

---

Example Payload

{
  "event": "payment.success.webhook",
  "data": {
    "payment_token": "abc12345-payment-token",
    "merchant_transaction_id": "TXN10001",
    "amount": "1500",
    "currency": "XOF",
    "payee": "+2250700000000",
    "payment_method": "mobile_money",
    "payment_processing_reference": "MOOV123456789",
    "payment_status": "success",
    "payment_status_code": 200,
    "payment_status_message": "Transaction completed successfully"
  }
}

Payout (Transfer) Payload

The webhook payload for a transfer (payout) may contain the following fields:

Fields

• event: The type of event that triggered the webhook
  e.g., payout.success.webhook, payout.failed.webhook
• data: An object containing details of the transfer:
  • transfer_token: A unique identifier for the payout.
  • merchant_transaction_id: Your internal reference for the transaction.
  • amount: The transfer amount.
  • currency: The transfer currency.
  • payee: The recipient of the transfer (e.g., phone number).
  • channel: The transfer channel (e.g., mobile_money).
  • transfer_method: The method used for the transfer (e.g., ORANGE_ML).
  • transfer_status: The current status of the transfer
    e.g., success, failed
  • transfer_status_code: Status code from the transfer partner or processor.
  • transfer_status_message: A short code/message from the partner.
  • transfer_status_description: A more detailed message explaining the status or failure reason.

Example Payload

{
  "event": "payout.failed.webhook",
  "data": {
    "transfer_token": "abc12345-transfer-token",
    "merchant_transaction_id": "TXN10001",
    "amount": "200",
    "currency": "XOF",
    "payee": "+22370811011",
    "channel": "mobile_money",
    "transfer_method": "ORANGE_ML",
    "transfer_status": "failed",
    "transfer_status_code": 303,
    "transfer_status_message": "TRANSFER_FAILED",
    "transfer_status_description": "An error occurred while processing the transfer"
  }
}

Step 4: Verify the signature

To ensure the incoming request genuinely originated from the API, you'll need to validate the 'X-SIGNATURE' header. Use your webhook secret key and the HMAC SHA-256 algorithm to calculate a signature and compare it with the received signature. Discard any requests where the calculated signature doesn't match the received signature.

Here's an example in PHP:

$payload = json_encode($data); // Assume $data is the 'data' array from the webhook payload
$receivedSignature = $_SERVER['HTTP_X_SIGNATURE']; // Assume this is the received 'X-OrizonPay-SIGNATURE' header
$privateKey = 'your_private_key';
$calculatedSignature = hash_hmac('sha256', $payload, $privateKey);
if (hash_equals($calculatedSignature, $receivedSignature)) {
    echo "Signature is valid!";
   // Process the webhook information here
} else {
    echo "Signature is invalid!";
}

And here's an equivalent example in JavaScript:

import * as crypto from 'crypto';
const payload = JSON.stringify(data); // Assume data is the 'data' array from the webhook payload
const receivedSignature = 'received_signature'; // Assume this is the received 'X-SIGNATURE' header
const privateKey = 'your_private_key';
const hmac = crypto.createHmac('sha256', privateKey);
hmac.update(payload);
const calculatedSignature = hmac.digest('hex');
if (calculatedSignature === receivedSignature) {
    console.log('Signature is valid!');
    // Process the webhook information here
} else {
    console.log('Signature is invalid!');
}

Step 5: Send a response

After you have processed the webhook, return an HTTP status code 200 response to acknowledge receipt. This tells the OrizonPay API's system that you've successfully received the webhook, so it doesn't need to send it again.