All Superinterfaces:: IPaymentGatewayService

public interface IHostedPaymentService extends IPaymentGatewayService

This interface defines a payment service which can be used to implement hosted payment page payment scenarios. In these scenarios, the payment is performed using a web page hosted by a 3rd party. It is the responsibility of the 3rd party to make sure the payment process is secure and PCI compliant, hence SFM is relieved from the need to implement its own payment process apart from initiating it.

The process involves a set of pre-defined resources in other parts of SFM:

HostedPaymentPage (hosted-payment.htm) is displayed to the user when payment is required. The user starts the payment process by clicking the payment button
HostedPaymentResponse, HostedPaymentCallback, HostedPaymentCancel servlets handle the asynchronous responses from the 3rd-party payment gateway

These pages and servlets invoke different methods of this interface in order to implement the payment workflow:

getHostedPageURL is invoked first by HostedPaymentPage when the user clicks the payment button. It allows the service to setup payment, create initial PaymentLog, and return the URL to the page on the 3rd-party payment gateway where the user can perform the payment. The user's browser will be redirected to this URL
handlePaymentCallback is (optionally) invoked next as the result of a POST-back by the 3rd-party payment gateway to the HostedPaymentCallback servlet. Depending on the payment gateway implementation, this method may never be invoked
completePayment is invoked after that as the result of the redirect of the user's browser from the 3rd-party payment gateway to the HostedPaymentResponse servlet. The redirect URL to the servlet is usually provided by the 3rd party payment gateway during the setup process, however it's up to the payment gateway interface definition as to how this URL is specified
cancelPayment may be invoked if the payment gateway has dedicated cancel operation. In that case, it'll redirect the user to the HostedPaymentCancel servlet which will invoke the cancelPayment method

Callback servlets

The default servlets can be found at the following locations:

HostedPaymentResponse	/<context>/servlet/hostedpayment/response
HostedPaymentCallback	/<context>/servlet/hostedpayment/callback
HostedPaymentCancel	/<context>/servlet/hostedpayment/cancel

Each servlet expects to receive one mandatory parameter - submitKey.

Field Summary

Fields inherited from interface com.avoka.fc.core.service.payment.IPaymentGatewayService
PAYMENT_SERVICE_CONFIG_UI_MAPPING_PARAMETER
Method Summary

Modifier and Type

Method

Description

void

cancelPayment(PaymentLog paymentLog, jakarta.servlet.http.HttpServletRequest req)

Cancels the payment internally in SFM.

PaymentLog

cancelPayment(Submission submission, jakarta.servlet.http.HttpServletRequest req)

Cancels the payment internally in SFM.

void

completePayment(PaymentLog paymentLog, jakarta.servlet.http.HttpServletRequest req)

Confirms, validates, and finalizes the payment: Confirms with the 3rd party payment gateway that the callback request is genuine Validates the payment details (such as amount) Update the PaymentLog and Submission entities with the transaction details and status.

PaymentLog

completePayment(Submission submission, jakarta.servlet.http.HttpServletRequest req)

Confirms, validates, and finalizes the payment: Confirms with the 3rd party payment gateway that the callback request is genuine Validates the payment details (such as amount) Update the PaymentLog and Submission entities with the transaction details and status.

void

errorPayment(PaymentLog paymentLog, jakarta.servlet.http.HttpServletRequest req)

Receives a error signal from the payment gateway and record the error internally in SFM.

PaymentLog

errorPayment(Submission submission, jakarta.servlet.http.HttpServletRequest req)

Receives a error signal from the payment gateway and record the error internally in SFM.

String

getCustomPaymentForm(Submission submission, jakarta.servlet.http.HttpServletRequest request)

Returns the rendered HTML custom payment form which will be included in the payment page.

String

getHostedPageURL(Submission submission, jakarta.servlet.http.HttpServletRequest request, jakarta.servlet.http.HttpServletResponse response)

Returns the URL of the hosted payment page on the 3rd party payment gateway that the user will be redirected to in order to perform the payment.

org.apache.click.Control

getLogo()

Returns a custom logo identifying the payment service.

org.apache.click.control.Submit

getPayButton()

Returns a custom payment button which is to be displayed on the payment page to the user instead of the default payment button.

void

handlePaymentCallback(PaymentLog paymentLog, jakarta.servlet.http.HttpServletRequest req)

Depending on the payment gateway implementation, this method may be invoked prior to completePayment and may need to perform the same set of tasks.

PaymentLog

handlePaymentCallback(Submission submission, jakarta.servlet.http.HttpServletRequest req)

Depending on the payment gateway implementation, this method may be invoked prior to completePayment and may need to perform the same set of tasks.

PaymentLog

identifyTransaction(Client client, jakarta.servlet.http.HttpServletRequest request)

Attempt to lookup a payment log entry using the supplied HTTP request

boolean

isCustomPaymentFormProvided()

Indicates whether the custom payment form is provided by the payment provider.

boolean

isProvidesLogo()

Indicates whether the payment service has its own logo to display to the user.

boolean

isProvidesPayButton()

Indicates whether the payment service has its own payment button.

Methods inherited from interface com.avoka.fc.core.service.payment.IPaymentGatewayService
getPaymentServiceCode, isQuerySupported, performQuery, resolveOutstandingPayments, resolveOutstandingPayments

Method Details
- isProvidesLogo
  
  boolean isProvidesLogo()
  
  Indicates whether the payment service has its own logo to display to the user. The logo is displayed on the payment page, under the payment total. If this method returns true, the getLogo method is invoked to get the logo.
  
  Returns:
  
  true, if the getLogo method will return a logo, false otherwise
- getLogo
  
  org.apache.click.Control getLogo()
  
  Returns a custom logo identifying the payment service. Must return a non-null logo component if the isProvidesLogo method returned true. The logo is displayed on the payment page, under the payment total.
  
  Returns:
  
  the logo control
- isCustomPaymentFormProvided
  
  boolean isCustomPaymentFormProvided()
  
  Indicates whether the custom payment form is provided by the payment provider. If true, the getCustomPaymentForm method will be used to obtain the payment form while will be displayed one the hosted page. This payment form should contain a payment button and the standard payment button will not be included.
  
  Returns:
  
  true, if the custom button is returned by the getCustomPaymentForm, false otherwise
  
  Since:
  
  4.0.0
- getCustomPaymentForm
  
  String getCustomPaymentForm(Submission submission, jakarta.servlet.http.HttpServletRequest request)
  
  Returns the rendered HTML custom payment form which will be included in the payment page.
  
  Parameters:
  
  submission - the submission requiring the payment (required)
  
  request - the request context (required)
  
  Returns:
  
  the payment button
  
  Since:
  
  4.0.0
- isProvidesPayButton
  
  boolean isProvidesPayButton()
  
  Indicates whether the payment service has its own payment button. If true, the payment button provided by the getPayButton method is displayed to the user on the payment page instead of the default button. If false, the default button of the portal is displayed.
  
  Returns:
  
  true, if the custom button is returned by the getPayButton, false otherwise
- getPayButton
  
  org.apache.click.control.Submit getPayButton()
  
  Returns a custom payment button which is to be displayed on the payment page to the user instead of the default payment button.
  
  Returns:
  
  the payment button
- getHostedPageURL
  
  String getHostedPageURL(Submission submission, jakarta.servlet.http.HttpServletRequest request, jakarta.servlet.http.HttpServletResponse response)
  
  Returns the URL of the hosted payment page on the 3rd party payment gateway that the user will be redirected to in order to perform the payment.
  The service is expected to create a PaymentLog entry for the payment in progress and (if possible) initialize it with the details necessary to track the payment transaction in future in case if an error occurs (ideally - the transaction ID).
  
  Parameters:
  
  submission - the submission requiring the payment
  
  request - the request context
  
  response - the response context
  
  Returns:
  
  the payment URL, never null
- completePayment
  
  PaymentLog completePayment(Submission submission, jakarta.servlet.http.HttpServletRequest req)
  Confirms, validates, and finalizes the payment:
  
  Confirms with the 3rd party payment gateway that the callback request is genuine
  Validates the payment details (such as amount)
  Update the PaymentLog and Submission entities with the transaction details and status. Use
  
  invalid reference
  
  com.avoka.fc.core.service.SubmissionService.getPendingPaymentLog
  
  for retrieving the right payment log entry.
  
  Note: some of these tasks may have been performed by the handlePaymentCallback method, but it is important to ensure that at the end of this method all the right entities are in the final "Payment Complete" state.
  Parameters:
  
  submission - the submission being paid for
  
  req - the callback request from the 3rd party payment gateway
  
  Returns:
  
  the updated PaymentLog entry, never null
  
  Throws:
  
  ApplicationException
- completePayment
  
  void completePayment(PaymentLog paymentLog, jakarta.servlet.http.HttpServletRequest req)
  Confirms, validates, and finalizes the payment:
  
  Confirms with the 3rd party payment gateway that the callback request is genuine
  Validates the payment details (such as amount)
  Update the PaymentLog and Submission entities with the transaction details and status. Use
  
  invalid reference
  
  com.avoka.fc.core.service.SubmissionService.getPendingPaymentLog
  
  for retrieving the right payment log entry.
  
  Note: some of these tasks may have been performed by the handlePaymentCallback method, but it is important to ensure that at the end of this method all the right entities are in the final "Payment Complete" state.
  Parameters:
  
  paymentLog - the paymentLog being paid for
  
  req - the callback request from the 3rd party payment gateway
  
  Throws:
  
  ApplicationException
  
  Since:
  
  4.0.0
- handlePaymentCallback
  
  PaymentLog handlePaymentCallback(Submission submission, jakarta.servlet.http.HttpServletRequest req)
  
  Depending on the payment gateway implementation, this method may be invoked prior to completePayment and may need to perform the same set of tasks. It's up to the implementation to divide the responsibilities between these 2 methods however it is advised that at least the method performs a security check to verify that the request is genuine and comes from the 3rd party payment gateway.
  
  Parameters:
  
  submission - the submission being paid for
  
  req - the callback request from the 3rd party payment gateway
  
  Returns:
  
  the updated PaymentLog entry, can be null
  
  Throws:
  
  ApplicationException
- handlePaymentCallback
  
  void handlePaymentCallback(PaymentLog paymentLog, jakarta.servlet.http.HttpServletRequest req)
  
  Depending on the payment gateway implementation, this method may be invoked prior to completePayment and may need to perform the same set of tasks. It's up to the implementation to divide the responsibilities between these 2 methods however it is advised that at least the method performs a security check to verify that the request is genuine and comes from the 3rd party payment gateway.
  
  Parameters:
  
  paymentLog - the paymentLog being paid for
  
  req - the callback request from the 3rd party payment gateway
  
  Throws:
  
  ApplicationException
  
  Since:
  
  4.0.0
- cancelPayment
  
  PaymentLog cancelPayment(Submission submission, jakarta.servlet.http.HttpServletRequest req)
  
  Cancels the payment internally in SFM. This method is invoked in response to the 3rd party payment gateway callback request indicating that the user has manually cancelled the transaction prior to completion. The method updates the corresponding PaymentLog entry as cancelled.
  
  Parameters:
  
  submission - the submission being paid for
  
  req - the callback request from the 3rd party payment gateway
  
  Returns:
  
  the updated PaymentLog entry, can be null
  
  Throws:
  
  ApplicationException
  
  Since:
  
  4.0.0
- cancelPayment
  
  void cancelPayment(PaymentLog paymentLog, jakarta.servlet.http.HttpServletRequest req)
  
  Cancels the payment internally in SFM. This method is invoked in response to the 3rd party payment gateway callback request indicating that the user has manually cancelled the transaction prior to completion. The method updates the corresponding PaymentLog entry as cancelled.
  
  Parameters:
  
  paymentLog - the paymentLog being paid for
  
  req - the callback request from the 3rd party payment gateway
  
  Throws:
  
  ApplicationException
  
  Since:
  
  4.0.0
- errorPayment
  
  PaymentLog errorPayment(Submission submission, jakarta.servlet.http.HttpServletRequest req)
  
  Receives a error signal from the payment gateway and record the error internally in SFM. This method is invoked in response to the 3rd party payment gateway callback request indicating that the payment gateway has a error. The method updates the corresponding PaymentLog entry in error.
  
  Parameters:
  
  submission - the submission being paid for
  
  req - the callback request from the 3rd party payment gateway
  
  Returns:
  
  the updated PaymentLog entry, can be null
  
  Throws:
  
  ApplicationException
  
  Since:
  
  4.0.0
- errorPayment
  
  void errorPayment(PaymentLog paymentLog, jakarta.servlet.http.HttpServletRequest req)
  
  Receives a error signal from the payment gateway and record the error internally in SFM. This method is invoked in response to the 3rd party payment gateway callback request indicating that the payment gateway has a error. The method updates the corresponding PaymentLog entry in error.
  
  Parameters:
  
  paymentLog - the paymentLog being paid for
  
  req - the callback request from the 3rd party payment gateway
  
  Throws:
  
  ApplicationException
  
  Since:
  
  4.0.0
- identifyTransaction
  
  PaymentLog identifyTransaction(Client client, jakarta.servlet.http.HttpServletRequest request)
  
  Attempt to lookup a payment log entry using the supplied HTTP request
  
  Parameters:
  
  client - the payment log
  
  request - the HttpServletRequets
  
  Returns:
  
  the payment log
  
  Since:
  
  4.0.0

Interface IHostedPaymentService

Callback servlets

Field Summary

Fields inherited from interface com.avoka.fc.core.service.payment.IPaymentGatewayService

Method Summary

Methods inherited from interface com.avoka.fc.core.service.payment.IPaymentGatewayService

Method Details

isProvidesLogo

getLogo

isCustomPaymentFormProvided

getCustomPaymentForm

isProvidesPayButton

getPayButton

getHostedPageURL

completePayment

completePayment

handlePaymentCallback

handlePaymentCallback

cancelPayment

cancelPayment

errorPayment

errorPayment

identifyTransaction