Accessing an external payment gateway to add an up-front payment

You start a submission, change, renewal, or rewrite job.

You quote the policy and navigate to the Payment screen before binding the policy.

PolicyCenter displays billing methods, payment methods, and associated installment or reporting plans retrieved from the billing system.

You select a billing method and payment schedule, and then preview payment plans retrieved from the billing system. This part of the wizard is similar for all lines of business. The PCF file UpFrontPaymentDV.Editable.pcf provides the user interface for the up-front payments. This PCF file lists up-front payments and provides options for adding one or more up-front payments. You select Electronic Payment to initiate an up-front payment that uses a payment gateway. The down-payment amount appears. You can change this value.

PolicyCenter uses the registered billing system plugin (IBillingSystemPlugin) implementation to request the known payment instruments from the billing system. PolicyCenter calls its plugin method getExistingPaymentInstruments.

To add a payment on a new payment instrument, in UpFrontPaymentDV.Editable, in Choose Card, you click Other.
To add a payment on a known payment instrument, in UpFrontPaymentDV.Editable, in Choose Card, you click the value that corresponds to the card to use. Typically, the value does not show the whole credit card number.

To process the card and payment, click the Take Payment button.

The action that the Take Payment button takes is to call a method called createElectronicPayment on the gw.billing.PolicyPeriodBillingInstructionsManager object that the page uses. The PolicyPeriodBillingInstructionsManager class delegates the implementation of this method to the gw.billing.UpFrontPaymentStaterContainerImpl class.

If you select Save for Future Use, PolicyCenter retains the information about the new payment instrument and sends that information to the billing system. PolicyCenter uses the registered billing system plugin (IBillingSystemPlugin) implementation to notify the billing system of the new payment instrument. PolicyCenter calls the plugin method addPaymentInstrumentTo. On successful completion of a payment, the Payment screen displays information about the card in the list of known payment instruments. This information typically includes the last four digits of the credit card number.

The createElectronicPayment method creates a PaymentInformation Gosu object, which holds information about the payment. This object is suitable for use as an argument to web service methods. Next, the createElectronicPayment method calls the takeElectronicPayment method. The takeElectronicPayment method tests the value of the RedirectToPaymentGateway property on the PaymentGatewayConfig plugin. If the value of the RedirectToPaymentGateway property is false, electronic payment is not available.

The takeElectronicPayment method uses the registered payment gateway plugin (PaymentGatewayPlugin) methods to access the payment gateway. Typically, the payment gateway is on a separate physical computer across the Internet. The takeElectronicPayment method uses different plugin methods for a new payment instrument and a known payment instrument:

For a new payment instrument, takeElectronicPayment calls the requestSecureToken plugin method to receive a token that identifies the payment. After saving a PaymentGatewayTransaction entity to the database, takeElectronicPayment calls the redirectToPaymentGateway plugin method, which navigates to the payment gateway user interface. The payment gateway plugin processes the response from the payment gateway. If you select Save for Future Use, you must retrieve tokenized information to identify the credit card from the payment gateway.
For a known payment instrument, PolicyCenter already has tokenized information that identifies the payment instrument to the payment gateway. The takeElectronicPayment method calls the takePaymentUsingPaymentInstrument plugin method, which uses the tokenized information. After saving a PaymentGatewayTransaction entity to the database, takeElectronicPayment processes the response from the payment gateway.

Redirection to the payment gateway for a new payment instrument occurs differently for the demonstration gateway and a real gateway:

For demonstration purposes, the redirectToPaymentGateway plugin method invokes the PCF exit point called DemoPaymentGatewayPage, which calls a demonstration version of a payment gateway that PolicyCenter itself implements.
For a production environment, the code for the redirectToPaymentGateway plugin method uses a different PCF exit point to open the user interface for your real payment gateway.

The following table compares the two payment gateways:

Step	Demonstration payment gateway	Real payment gateway
1.	The `redirectToPaymentGateway` plugin method passes the transaction amount and job number to the demonstration payment system, which PolicyCenter implements as PCF pages and Gosu objects.	The `redirectToPaymentGateway` plugin method exits to the real payment system. The PCF page PaymentGateway.pcf is the exit point to the payment gateway.
2.	The PCF page DemoPaymentGatewayScreen.pcf opens and emulates a the user interface for providing credit card details in a payment gateway.	PolicyCenter uses the exit point to transfer control to the external payment system.
3.	After you enter the credit card details and click the Take Payment button, the demonstration payment gateway page validates the values on the page and opens the DemoTransactionConfirmationPage.pcf page.	You enter the credit card and payment details in the external payment system. The gateway typically does a postback action on completion. A PolicyCenter servlet processes this action. The gateway typically displays a payment confirmation page after the payment completes.
4.	When you click the Return to Merchant Site link on the DemoTransactionConfirmationPage.pcf page, the page transfers control to the PaymentGatewayForward.pcf page. The PaymentGatewayForward.pcf page builds a `PaymentGatewayResponseBase` Gosu object, and then forwards control to the processPaymentResponseAndRedirect method of a new `PaymentGatewayResponseProcessor` Gosu object. This method adds the payment to the Job entity instance.	If the payment gateway performs a postback action, the `PaymentGatewaySilentPostServlet` uses the `mapSilentPostRequestToPaymentGatewayResponse` plugin method to map the HttpServletRequest object from the external payment gateway to a `PaymentGatewayResponseBase` Gosu object. The servlet then calls the processPostbackPaymentResponse method of a new `PaymentGatewayResponseProcessor` Gosu object. This method adds the payment to the Job entity instance. If the payment gateway does not perform a postback action, the payment gateway entry point to PolicyCenter processes the response.
5.	No payment message is sent to the billing system.	PolicyCenter sends information about the payment to the billing system. If the billing system is BillingCenter, PolicyCenter calls the PaymentAPI method that creates a suspense payment.
6.	Control returns to the Payment screen.	Control returns to the Payment screen.

For a successful or voided payment, PolicyCenter removes the PaymentGatewayTransaction entity from the database.

You issue or bind the policy. PolicyCenter uses the registered billing system plugin (IBillingSystemPlugin) implementation to send a Gosu object to the billing system. PolicyCenter notifies the billing system that it has received a payment by setting the OfferNumber property on the Gosu object. The value of the OfferNumber property is the JobNumber property of the Job.