Skip to main content

Partner Webhooks Documentation

Overview​

Partner webhooks provide real-time updates to payment statuses by sending notifications directly from the partner’s system to the FNZ backend. This asynchronous approach reduces the need for manual status checks or polling and enhances system efficiency.

How Webhooks Work​

1. Secure Delivery​

Webhooks are securely sent from the partner’s system to the FNZ backend using mechanisms such as:

  • VPNs or Secure Tunnels: (e.g., WireGuard) for encrypted communication.
  • Nonce and Signature:
    • Nonce: Ensures uniqueness to prevent replay attacks.
    • Signature: Validates the integrity and authenticity of the payload.

2. Validation Process​

Upon receiving a webhook, the FNZ backend validates:

  • Authentication and Data Integrity:
    • Verifies the nonce and signature to confirm the request's authenticity and uniqueness.
    • Ensures the payload conforms to the expected schema and references a valid payment record.
  • If validation fails, the webhook is rejected, and an appropriate error response is provided.

3. Status Update​

After successful validation:

  • The payment status is updated based on the webhook's information.
  • The system triggers any necessary internal processes to reflect the updated payment state.

Webhook Security and Customization​

Webhook security is customizable based on each partner's requirements. FNZ supports the following security measures:

  • IP Whitelisting: Webhooks are only accepted from trusted IP addresses provided by the partner.
  • VPN End-to-End Tunneling: Secure communication channels, such as VPNs, ensure data confidentiality and integrity during transmission.
  • Nonce and Signature Validation:
    • Nonce: Prevents replay attacks by ensuring each webhook request is unique.
    • Signature: Cryptographic validation (e.g., HMAC-SHA256) guarantees the integrity and authenticity of the payload.

These measures ensure secure delivery and processing of webhook data, tailored to the specific needs of each partner.

Webhook Structure​

HTTP Request Details​

  • Method: POST
  • Headers:
    • Content-Type: application/json
    • X-Partner-Nonce: Unique identifier for the request.
    • X-Partner-Signature: HMAC-SHA256 signature of the payload.
  • Body: JSON payload containing the payment status update.

JSON Payload Example​

{
  "paymentId": "12345",
  "status": "COMPLETED",
  "timestamp": "2024-11-16T10:30:00Z",
  "partnerId": "partner_abc",
  "details": {
    "reference": "INV56789",
    "amount": 100.50,
    "currency": "USD"
  }
}

Payment Methods and Partners​

Payment Methods​

Each type of payment is referred to as a payment method (e.g., bank transfer, QR code, UPI). A single payment method can be supported by one or multiple partners, such as software providers, gateways, or banks.

Routing Logic​

The selection of a partner for processing a payment is referred to as routing.

  • Routing is determined based on configurable factors such as:
    • Partner Priority: Set via the priority field in the PartnerPaymentMethod table.

This flexibility allows FNZ to dynamically route payments to the most appropriate partner based on specific business needs.

Error Handling and Responses​

Response Codes​

  • 200 OK: Webhook processed successfully.
  • 400 Bad Request: Invalid payload or schema.
  • 401 Unauthorized: Authentication or signature validation failed.
  • 409 Conflict: Duplicate webhook detected (nonce already used).
  • 500 Internal Server Error: Unexpected server error.