Interface PaymentGatewayWebhookHandler

All Superinterfaces:
PaymentGatewayTypeAware

public interface PaymentGatewayWebhookHandler extends PaymentGatewayTypeAware
A gateway-specific interface to assist with the interpretation & processing of payment gateway webhook requests. Typically, we expect this interface to be used to assist with the recording of payment transaction results. In most cases, webhooks are used as a secondary means of communicating transaction results.
Author:
Chris Kittrell (ckittrell)
  • Method Details

    • validate

      @Deprecated(forRemoval=true) default void validate(org.springframework.http.HttpHeaders headers, String requestBody)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Validates that the webhook request came from the gateway & that it wasn't tampered with.
      Parameters:
      headers - The webhook request headers
      requestBody - The webhook raw request body in the form of a String
      Throws:
      WebhookValidationException - if the webhook request is invalid.
    • validate

      default void validate(org.springframework.http.HttpHeaders headers, String requestBody, Map<String,String> parameters)
      Validates that the webhook request came from the gateway & that it wasn't tampered with.
      Parameters:
      headers - The webhook request headers
      requestBody - The webhook raw request body in the form of a String
      parameters - The request parameters passed into the webhook
      Throws:
      WebhookValidationException - if the webhook request is invalid.
    • shouldHandleRequest

      @Deprecated(forRemoval=true) default boolean shouldHandleRequest(org.springframework.http.HttpHeaders headers, String requestBody)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Determines if the webhook request should be handled.
      Returns:
      true if the webhook request should be handled, otherwise false
    • shouldHandleRequest

      default boolean shouldHandleRequest(org.springframework.http.HttpHeaders headers, String requestBody, Map<String,String> parameters)
      Determines if the webhook request should be handled.
      Parameters:
      headers - The webhook request headers
      requestBody - The webhook raw request body in the form of a String
      parameters - The request parameters passed into the webhook
      Returns:
      true if the webhook request should be handled, otherwise false
    • convertToPaymentResponse

      @Deprecated(forRemoval=true) default org.apache.commons.lang3.tuple.Pair<TransactionIdentifier,PaymentResponse> convertToPaymentResponse(org.springframework.http.HttpHeaders headers, String requestBody)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Builds & returns a pair of TransactionIdentifier & PaymentResponse based on the contents of the webhook request.
      Parameters:
      headers - The webhook request headers
      requestBody - The webhook raw request body in the form of a String
      Returns:
      a pair of TransactionIdentifier & PaymentResponse based on the contents of the webhook request.
    • convertToPaymentResponse

      default org.apache.commons.lang3.tuple.Pair<TransactionIdentifier,PaymentResponse> convertToPaymentResponse(org.springframework.http.HttpHeaders headers, String requestBody, Map<String,String> parameters)
      Builds & returns a pair of TransactionIdentifier & PaymentResponse based on the contents of the webhook request.
      Parameters:
      headers - The webhook request headers
      requestBody - The webhook raw request body in the form of a String
      parameters - The request parameters passed into the webhook
      Returns:
      a pair of TransactionIdentifier & PaymentResponse based on the contents of the webhook request.
    • getEventId

      default String getEventId(@NonNull @NonNull org.springframework.http.HttpHeaders headers, @NonNull @NonNull String requestBody, @NonNull @NonNull Map<String,String> parameters)
      Returns the event id for this request. By default, it generates the MD5 digest from request body using DigestUtils.md5Hex(String). It's preferred that you identify & provide the gateway's webhook event id via this method, if one is present. If this is done, then you can easily correlate any stored or logged event ids to those in the gateway's dashboard or APIs.
      Parameters:
      headers - The webhook request headers
      requestBody - The webhook raw request body in the form of a String
      parameters - The request parameters passed into the webhook
      Returns:
      the idempotency key for this request
    • getSupportedWebhookNotificationTypes

      List<String> getSupportedWebhookNotificationTypes()
      Declares the list of supported webhook notification types for the implementation.
      Returns:
      The list of supported webhook notification types for the implementation.
    • buildSuccessfulWebhookResponse

      default org.springframework.http.ResponseEntity<?> buildSuccessfulWebhookResponse()
      Builds & returns a ResponseEntity meant to communicate to the gateway that the webhook request was successfully processed.
      Returns:
      a ResponseEntity meant to communicate to the gateway that the webhook request was successfully processed.
    • buildFailedWebhookResponse

      default org.springframework.http.ResponseEntity<?> buildFailedWebhookResponse(Exception e)
      Builds & returns a ResponseEntity meant to communicate to the gateway that the webhook request was unsuccessfully processed.
      Returns:
      a ResponseEntity meant to communicate to the gateway that the webhook request was unsuccessfully processed.