Webhook Operation Types

Overview

EdfaPay webhooks are used to notify the merchant system about transaction updates. These notifications are triggered asynchronously based on the transaction lifecycle and include key fields such as type and status to describe the operation and its result.

Important: Webhooks are the source of truth for transaction status. Do not rely only on API responses or redirect results.

Operation Types

The type field defines the nature of the transaction event. It reflects the operation performed on the payment.

• Purchase Represents a direct payment where the transaction is processed (authorization and capture together).
• Authorization Indicates that the amount has been reserved on the customer’s account but not yet captured.
• Capture Confirms that a previously authorized transaction has been completed and funds are transferred.
• Refund Indicates that funds have been returned to the customer, either partially or fully.
• Void Cancels a previously authorized transaction before it is captured.

📘

Tip: Use Authorization and Capture flows when your business requires delayed confirmation (e.g., shipment or service validation).

Transaction Status

The status field represents the current state of the transaction at the time of the webhook notification.

• Approved The transaction has been successfully completed.
• Declined The transaction was rejected by the issuing bank or gateway.
• Pending The transaction is still being processed and not been finalized yet.
• Redirect Additional customer action is required, such as completing 3D Secure authentication.

❗️

Alert: Pending and Redirect are intermediate states. Do not treat them as final outcomes.

Webhook Behavior

Webhook delivery is asynchronous and may not occur immediately after the transaction request. Multiple notifications can be sent for the same transaction as it progresses through different states.

• Notifications may arrive with delay depending on processing time
• The same transaction may trigger multiple webhook events
• Final status is only confirmed when the transaction reaches a terminal state (e.g., Approved or Declined)

👍

Important: Your system must be designed to handle out-of-order and repeated webhook events.

Handling Redirect and Pending States

When a transaction is marked as Redirect, the customer must complete an external step such as 3D Secure authentication. During this phase, the transaction remains incomplete until a final status is received.

Similarly, a Pending status indicates that the transaction is still being processed and should not be finalized on the merchant side.

Tip: Always wait for a final webhook (Approved or Declined) before updating order status.

Idempotency and Reliability

Webhook notifications may be sent more than once to ensure delivery. The merchant system must handle duplicate events safely without causing repeated processing.

• Store transaction identifiers (transactionId, orderId)
• Ignore already processed events
• Ensure operations such as order updates are idempotent

🚧

Alert: Failure to handle duplicate webhooks may result in duplicated orders or incorrect transaction states.

Security Considerations

Webhook endpoints must be secured to prevent unauthorized or malicious requests.

• Validate webhook authenticity using signature or hash verification
• Accept requests only over HTTPS
• Avoid logging sensitive payment data such as card details
• Implement proper error handling and monitoring

Important: Reject any webhook that fails validation to protect your system from spoofed requests.

Summary

EdfaPay webhooks provide real-time updates on transaction lifecycle events. Proper handling of operation types, statuses, and asynchronous behavior is essential to ensure accurate payment processing and system reliability.