Chapter 5   Interfacing with Existing Systems



Overview

---

This chapter illustrates a typical payment being processed and describes how the payment can be initiated using the iPlanet Trustbase Payment Services Corporate Payment Initiation Library API (CPI). There are three kinds of situations that may warrant the use of the CPI library.

Figure 5-1    Buyer buys something from Sellers Website

Figure 5-2    Buyer is making a payment with a Sellers signature

Figure 5-3    Buyer trying to make a payment without the need for the seller's signature

Using the iTPS API to initiate a Payment

The Corporate Payment Initiation Library (CPI) allows a merchant (seller) web site or another application (such as a bank web site) to submit payment requests to a participant (such as the seller/buyer bank).

In order to submit a payment, typically a merchant performs the following steps:

1. Collects payment data from a customer (e.g. from HTML forms submitted to the merchant's web site).

2. Creates an XML element that represents the payment.

3. Sends the XML to the customer for signing

4. Creates any additional XML elements as required (e.g. SellerPrivateData, RemittanceData).

5. Creates a ConfigAdapter. The config adapter allows the merchant application to specify the location (URL) of his financial institution, the certificate to be used for signing payment messages and initialises the SSL subsystem.

6. Optionally defines the transport over which the message is sent using TransportAdapter

7. Submits the XML, signed data and ConfigAdapter to the PaymentInitiator which will construct a signed payment request and send it to the merchant's financial institution.

8. Receives from the PaymentInitiator a Status object, which contains the XML reply content and raw data suitable for logging.

9. Parses the XML reply content to establish the status of the payment request using other API methods e.g. responseReceived()

   
   

   ---

   Note

   Consult your iTPS and iTTM API for more information on this: com.iplanet.trustbase.initiator com.iplanet.trustbase.initiator.cpi com.iplanet.trustbase.initiator.config com.iplanet.trustbase.initiator.transport The above iTPS API can be found within the docs directory on your CD-ROM drive. The Trustbase API can be found within the iTTM installation directory or from your CD-ROM drive

   ---

   
   

Parameters needed to send a message

In order to send a message the following parameters need to be defined

1. role - identifies the role of the customer (for example `BU:01' = Buyer, `SE:01'= Seller)

2. doctype - the doctype of the request, for example

   <!DOCTYPE PaymentRequest PUBLIC \"-//IDENTRUS//ELEANOR PAYMENT REQUEST DTD//en" "http://www.identrus.com/Eleanor/1.0/ver1.0/PaymentRequest.dtd">

3. data - the data signed by the signature(s) in the pkcs7 parameter

4. elements - additional XML elements that belong in the request (e.g. Header, RemittanceData).

5. pkcs7 - array of the base64 encoded pkcs7 signed object data, each of which represents the buyer's signature. If multiple signatures are given, the multipleSignaturesType needs to be one of

ALL_SIGN_SAME_DATA, SIGN_PRECEDING_SIGNATURES.

If the pkcs7 array parameter contains one signature, the multipleSignaturesType parameter is ignored. Multiple signatures needs to be either: all sign the same application data (but not sign preceding signatures) or each (except the first) sign the preceding signatures, forming a chain.

6. config - the com.iplanet.trustbase.initiator.config.ConfigAdapterImpl for this operation the following properties needs to be present:
   1. Keystore Domain Space

   2. Signing Certificate

   3. Verification Certificate

   4. Optionally an SSL signing certificate

7. multipleSignaturesType - describes what type the multiple signatures are in the pkcs7 array parameter. This will be one of
   1. ALL_SIGN_SAME_DATA

   2. SIGN_PRECEDING_SIGNATURES.

8. transport - the com.iplanet.trustbase.initiator.TransportAdapter for this operation. This is Optional

Certificate Verification

---

The CPI packages behavior can be altered by setting properties in the ConfigAdapter. The recognised properties are defined in

com.iplanet.trustbase.initiator.PropertyCodes

This package contains details of how the Property codes can be used

How to use the API

The following sample code illustrates how to use the API and illustrate initiating a payment and sending it to iPlanet Trustbase Payment Services. There are two main aspects to this:

• How to build the CPI Library parameters

• How to send a Payment Initiation Message

  class PaymentInitiatorExample

  {

     public Status processPaymentRequest()

     {

        

  // Set up the parameters required to send a PaymentRequest

  // The role. In this case we are acting as the seller, hence the role is "SE:01"

        String role ="SE:01";

        

  // The XML DOCTYPE for the message to be sent. The doctype identifies the type of the message,

  // and the DTD that defines the structure of the message. In this case we are sending a payment

  // request, for which the public ID is -//ELEANOR PAYMENT REQUEST DTD//en and the System ID

  // is http://www.identrus.com/Eleanor/1.0/ver1.0/PaymentRequest.dtd.

        String doctype = "<!DOCTYPE PaymentRequest PUBLIC \"-//IDENTRUS//ELEANOR PAYMENT REQUEST DTD//en\""

                  +" \"http://www.identrus.com/Eleanor/1.0/ver1.0/PaymentRequest.dtd\"> ";

                    

  // Get the data describing the payment. This is the data that will be signed by the customer

        String customerData = createCustomerData(getPaymentAmount());

        

  // Get the other elements to be included in the request, such as the Header block.

        String[] elements = getElements();

        

  // Request that the customer signs the payment request. This signature is performed by the

  // smartcard plugin in the customer's browser.

        String[] customerSig = getCustomerSignature(customerData);

        

  // The signature type we are using. This defines how signatures are applied if there

  // are multiple signatures in the customerSig array. In this example code there is a single signature

  // from the customer, so the parameter is not used regardless of the value being set to                     

  // PaymentInitiator.ALL_SIGN_SAME_DATA as per below

        int multipleSignatureType = PaymentInitiator.ALL_SIGN_SAME_DATA;

        

  // Get the config adapter for this request. The config adapter is the means by which the

  // PaymentInitiator class accesses the underlying PKI and properties of the system.

        ConfigAdapter config = getConfig();

        

  // The transport adapter defines the transport over which the message is sent. Here we

  // will use HTTP

        TransportAdapter transport = new HTTPTransportAdapter();

        

  // Get an instance of the Payment Initiator,

        PaymentInitiator pi= PaymentInitiatorManager.getPaymentInitiator();                           

        

           

  // Send the request to the Payments server using the information gathered above.

        Status status = pi.send(role,

                          doctype,

                          customerData,

                          elements,

                          customerSig,

                          multipleSignatureType,

                          config,      

                          transport);      

                          

  // Retrieve the response data from the Payments Server check to see if the response is true or false

        if (status.responseReceived())

        {

  // Retrive the actual content as a String object

           String response = status.getContent();                     

           

           // Business logic to deal with the response

           // ...

           // ...

           // ...

        }

        else if      (status.hasConnectionFailed())

        {

           // No response - log an error                  

        }

        else

        {

           // fall through error handling

        }

     }

     

     public ConfigAdapter getConfig()throws Exception

     {

  // The default implementation of ConfigAdapter works from information supplied in a Properties

  // object. Certificates are retrieved from a file on disk.

        

        Properties props = new Properties();

        

  props.put(PropertyCodes.INITIATOR_KEYSTORE_DOMAIN_SPACE,"mykeystore");

  props.put(PropertyCodes.INITIATOR_KEYSTORE_SIGNING_CERTIFICATE,"server-cert);

  props.put(PropertyCodes.INITIATOR_KEYSTORE_VERIFICATION_CERTIFICATE + ".1","IdentrusRoot");

  return new ConfigAdapterImpl(props);

     }

     public String createCustomerData(String paymentAmount)

     {

  // Construct the CustomerSignedData XML block for the customer to sign.

  // There are a number of ways of constructing this block, including the            

  // iPlanet JAXHIT technology. There are a number of advantages to using

  // this technology from iPlanet, such as type checking and XML validity checking.         

  // For brevity we will just create the block as a String in this example.

  // The values here are hard coded for example only and would typically be

  // supplied by the calling Seller application

        

        // The ISO currency specified in the Eleanor Tech Spec, here we're using US $

        String currency = "USD";

        

        // The valueDate is taken from the transaction attributes agreed between Buyer and

        // Seller

        String valueDate = "2001-07-25";

        

        // The unique Eleanor ID for the request as per the Eleanor Tech Spec

        String eleanorRef = this.getEleanorRef();

        

        // The name of the seller company (i.e. us)

        String sellerName = "ACME Soap Co";

        

        // The type of obligation. In this case it is "NONE", as we are sending a plain revocable

        // payment request

        String obligation = "NONE";

        

        String customerData = "<SubscriberSignedData><NegotiatedData><Amt>"

                        +paymentAmount

                        +"</Amt><CurCode>"

                        +currency+

                        "</CurCode><RequestedValueDate>"

                        +valueDate+

                        "</RequestedValueDate></NegotiatedData><SellerPublicData><EleanorTransactionReference                                          >"

                        +eleanorRef+

                        "</EleanorTransactionReference><SellerName>"

                        +sellerName

                        +"</SellerName></SellerPublicData><Obligation>"

                        +obligation+

                        "</Obligation></SubscriberSignedData>";

        return customerData;

     

     }

     public String getElements()

     {

        // Construct the header block for the message

        // Eleanor product code as defined in the Eleanor Specification. "xPx" is the code

        // for Payment Request

         String product = "xPx";

        

        // The XML doc type (the type of the root element of the message)

         String docType = "PaymentRequest";

        

        // The version

         String version = "1.0";

        

        // Build the header block

         return new String[]{"<Header xml:lang=\"enGB\"><Product>"

                          +Product

                          +"</Product><DocumentType>"

                          +DocType

                          +"</DocumentType><Version>"

                          +Version

                          +"</Version></Header>"};

     }

     

     

     private String getEleanorRef()

     {

  // return a unique Eleanor reference number as per the Eleanor Tech Spec            

     }

     public String getPaymentAmount()

     {

  // Get the payment amount attribute from the transaction

     }

     

     public String[] getCustomerSignature(String customerData)

     {

        // Request that the customer signs the customerData with their smartcard.

        // ...

        // ...

        // ...

     }

  }

Test.java

The full source for this worked example can be found in:

/cdrom/cdrom0/iTPS/cpi/cpi.tar

The script to run test.java can be found in:

<cpi_install_dir>/bin/test.sh

The source can be found in:

<cpi_install_dir>/example/com/example/example1/Test.java