Implementation Guide for Oracle Self-Service E-Billing > Customizing Payment >

Implementing Custom Oracle Self-Service E-Billing Payment Cartridges

You can implement two custom cartridges:

• Implementing a Demonstration Cartridge
• Implementing a Custom Credit Card Cartridge

Implementing a Demonstration Cartridge

Oracle Self-Service E-Billing Payment provides an example cartridge that demonstrates how to implement a custom cartridge. The code is in the /vobs/payment/com/edocs/payment/cassette/demo directory. There are two cartridges:

• demo_CheckCassette.java. For check payments.
• demo_CreditCardCassette.java. For credit card payments.

The example cartridge delegates all API calls to demo_CheckProcessorProxy.java and demo_CreditCardProcessorProxy.java to communicate with a dummy payment gateway.

If you configure a DDN to use the demonstration cartridge, then you can make payments against it from the user interface.

Implementing a Custom Credit Card Cartridge

The example cartridge is based on the interface com.edocs.payment.cassette.ICreditCardCassette, which extends from com.edocs.payment.cassette.IPaymentCassette, which then extends from com.edocs.payment.cassette.IEnrollmentCassette. In general, do not modify IEnrollmentCassette, because it defines how to verify a credit card when a user enrolls it through the user interface.

To implement the cartridge, extend your cartridge implementation from PaymentCassette, and implement ICreditCardCassette:

public class MyCreditCardCassette extends PaymentCassette implements ICreditCardCassette

Use demo_CreditCardCassette.java to create your implementation. You can use three implementation methods:

• IPaymentCassette.getDefaultConfigAttributes()
• ICreditCardCassette.authorize()
• ICreditCardCassette.batchAuthorize()

You must implement IPaymentCassette.getDefaultConfigAttributes() to return a list of parameters (of type com.edocs.payment.config.Attribute), which are used to configure the cartridge. Calling IPaymentCassette.getDefaultConfigAttributes() causes those parameters to be displayed in the Payment Settings of the Command Center, where you can use them to configure the cartridge. These parameters include the global ones, the ones shared by both credit card and check types, and the ones specific to this credit card cartridge. Your implementation of getDefaultConfigAttributes() must at least return the global and shared parameters in that list. See demo_CreditCardCassette.getDefaultConfigAttributes() in the Oracle Self-Service E-Billing Javadoc, and the file demo_CreditCardAttributes.java for more information. See Accessing Oracle Self-Service E-Billing Javadoc for details on accessing the Oracle Self-Service E-Billing Javadoc.

If you want to support instant payments, then you must implement the ICreditCardCassette.authorize() method. In this method, you must get the payment information from the ICreditCard object that is passed in, then send it to the payment gateway.

The payment gateway sends back a response, which you use to update the status of the ICreditCard object:

• If the payment is authorized, set the status to settled by calling:

  ICreditCard.setStatus(CreditCardState.SETTLED);

• If the payment failed authorization, set status to failed-authorize by calling:

  ICreditCard.setStatus(CreditCardState.FAILED_AUTHORIZE);

  You could also call ICreditCard.setTxnErrMsg() to log an error message.

• If there is a system or network error (Payment failed to connect to payment gateway), set the status to failed by calling:

  ICreditCard.setStatus(CreditCardState.FAILED);

  You could also call ICreditCard.setTxnErrMsg() to log an error message.

  When you call these methods, Oracle Self-Service E-Billing Payment updates the credit card information in the database. The Oracle Self-Service E-Billing Payment JSP pages get the credit card information from the user and pass the information to the cartridge. After the card is processed, Oracle Self-Service E-Billing Payment updates Oracle Self-Service E-Billing Payment database.

  If your application supports scheduled payments, then you must implement ICreditCardCassette.batchAuthorize(). This method is called by the CreditCardSubmit job, which extracts all the scheduled payments from the database and sends them to the payment gateway. Your cartridge must perform the following actions:

1. Get the scheduled payments from Oracle Self-Service E-Billing Payment database. There are examples of using the APIs in demo_CreditCardCassette.batchSubmit().
2. Loop through the list of payments and send them to the payment gateway. Set the status of each payment the same way as for instant payments. After setting the status and other information, call the Oracle Self-Service E-Billing Payment API to update this credit card back to Oracle Self-Service E-Billing database (note that this is different from Instant payments, because Oracle Self-Service E-Billing Payment does not update the database).
3. Package your custom cartridge. With Oracle WebLogic, package the custom cartridge into Payment_custom.jar which is in the lib directory.
4. Prepopulate Oracle Self-Service E-Billing Payment database.
5. Tell Oracle Self-Service E-Billing Payment about your cartridge implementation class by populating the payment_gateway_configure table. If your cartridge class name is com.edocs.ps.MyCreditCardCartridge, and you want to name it "customCCardCartridge", use:
6. insert into payment_gateway_configure(GATEWAY,PAYMENT_TYPE,CARTRIDGE_CLASS)values('customCCardCartridge', 'ccard', 'com.edocs.ps.MyCreditCardCartridge');
7. When you go to Payment Settings of Command Center and configure a DNN for your credit card cartridge, the JSP page will read the list of available cartridges from this table and allow you to select one of them.
8. After you finish all the preceding steps, create a DDN, configure a cartridge for it and then make the payments from UI.