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:
1. 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
2. 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
3. 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
4. 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

All Methods Instance Methods Abstract Methods
Modifier and Type	Method	Description
`void`	`cancelPayment(PaymentLog paymentLog, HttpServletRequest req)`	Cancels the payment internally in SFM.
`PaymentLog`	`cancelPayment(Submission submission, HttpServletRequest req)`	Cancels the payment internally in SFM.
`void`	`completePayment(PaymentLog paymentLog, 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, 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, HttpServletRequest req)`	Receives a error signal from the payment gateway and record the error internally in SFM.
`PaymentLog`	`errorPayment(Submission submission, HttpServletRequest req)`	Receives a error signal from the payment gateway and record the error internally in SFM.
`String`	`getCustomPaymentForm(Submission submission, HttpServletRequest request)`	Returns the rendered HTML custom payment form which will be included in the payment page.
`String`	`getHostedPageURL(Submission submission, HttpServletRequest request, 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, 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, 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, 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 Detail
  - 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,
                            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,
                        HttpServletRequest request,
                        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,
                           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 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,
                     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 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,
                                 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,
                           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,
                         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,
                   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,
                        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,
                  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,
                               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

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

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 Detail

isProvidesLogo

getLogo

isCustomPaymentFormProvided

getCustomPaymentForm

isProvidesPayButton

getPayButton

getHostedPageURL

completePayment

completePayment

handlePaymentCallback

handlePaymentCallback

cancelPayment

cancelPayment

errorPayment

errorPayment

identifyTransaction