Use Case diagrams show the associated roles and accesses available to actors and other systems external to the system. They show how users can interact with the system while avoiding the complications of diagramming the internal workings of the system. There are three primary use cases for this system: shopping cart transactions, cardholder transactions and key update transactions.
Shopping cart transactions have the Merchant system create a Shopping Order that is passed on to the Acquiring system. Cardholders are then redirected to the acquiring system as well, where they supply their cardholder information and confirm the purchase details. The system then processes the purchase by parsing the details and constructing a message to send to the host. The response from the Host System is then interpreted and a Purchase Response created in the system. This Purchase Response can be pushed back to the merchant using a number of methods: e-mail, HTTP or a web interface.
Cardholder transactions function in the same manner except here, the cardholder has supplied their cardholder and order fulfillment to the merchant through a secure interface on the merchant’s web site. In this case, the merchant creates both the Shopping Order and the Purchase Order. All other aspects of the transaction are unchanged.
The final scenario is the creation of a new MAC key for a merchant. To request a MAC Key, the merchant or its agent will use a secure web interface to request a new key. Since the system uses symmetric keys for its MACs, this key will returned to the merchant and also be retained by the system for MAC verification.
The Make Shopping Cart Use Case sees the merchant web site redirect the customer’s browser to the acquirer’s web site. The acquirer’s web site uses a Cardholder Interface to display a form requesting the customer to supply cardholder and order fulfillment information. In order to display this information, the Cardholder Interface must parse the embedded XML document to extract the merchant identity, and order details. This data is used to populate the interface screens presented to the user from information provided in the Merchant Configuration database.
Once all required information is obtained from the cardholder, a transaction is created and handed off to the Transaction Verifier. The Transaction Verifier checks that all data supplied are valid and that any missing information can be obtained from the Merchant Configuration database. At this point, two types of errors can be generated: those that originated with the cardholder, and those that originated with the merchant. If the former is the case, the Cardholder Interface can request the customer to correct the supplied data and the transaction can be reprocessed during this session. In the latter case, the error is not recoverable during the current session; the customer must create a new shopping cart on the merchant system before proceeding. In either case, the error is reported back to the Cardholder Interface for display to the cardholder. An additional error report may be generated for the merchant or system administrator. If there is no error, then the completed and verified Transaction object is handed off to the Host Message Parser. A reference to the Transaction object is also handed to the Transaction Recorder for insertion into the database.
The Host Message Parser provides encapsulation of host messaging details. In this way, the acquiring system can reroute transactions to different host systems depending on predefined criteria. The Host Message Parser obtains message metadata from the Host Configuration database and then constructs a Host message from the supplied Transaction object. The resulting Host Message is then sent to the appropriate Host Connector for transmission to the host system.
The Host Connector sends a transaction to the host and awaits the response from the host. In the event of a failure of the host system to send a response within a predefined timeout setting, an error will be generated, recorded in the system database, and sent to a system administrator. Upon a successful response, the Host Connector constructs a new Host Message containing this response and returns this new Host Message to the Host Message Parser.
The Host Message Parser receives the Host Message and constructs a TransactionResponse object using metadata from the Host Configuration database. This TransactionResponse is handed to the Transaction Recorder for inclusion in the archival database. A reference of the TransactionResponse is then handed off to the Transaction Responder.
The Transaction Responder parses the appropriate information from the TransactionResponse and sends this to the Cardholder Interface. The Cardholder Interface uses this information along with the initial Transaction object to construct a return screen for the cardholder’s web browser reporting the final status of the order and supplying the final sales invoice, merchant contact information, and order confirmation data. The Transaction Responder also consults with the Merchant Configuration database and e-mails the order details to the merchant and/or pushes the transaction object back to a merchant defined URL using XML.
A cardholder order is a much simpler sequence because no interaction with the cardholder is required. Instead, the merchant is responsible for gathering all this information and passing it directly to a URL directly tied to the Transaction Verifier. The Transaction Verifier then does initial processing of the order to ensure that all required data is present and then performs some preliminary data validation. For example, it checks that the card number is a correctly formed number with a valid expiry date. Missing information is obtained from the Merchant Configuration database. If required information is still missing or any error is detected, program flow passes to the Transaction Responder, which creates a Response object documenting the error. This object is then used to return an XML message back to the merchant over the HTTP connection that initially sent the transaction.
If no error is generated, the transaction processing then proceeds as in a Shopping Cart Order use case. The exception is that no response to the user is required and the merchant response can be sent back over the same HTTP connection that initiated the transaction in the first place.
The Purchase Response sequence is a web interface for merchants. After authenticating the merchant identity, it provides an application middle-tier to effect backend database calls on the merchant’s transactions.
The Request MAC Key sequence allows the merchant to request a new key for computing MAC values. Required inputs are the merchant id, the merchant passphrase and the value of the current MAC Key against which to issue a renewal. Merchants can request a renewal at any time such as when an employee with access to the current key terminates their employment with the merchant. Because the information used in order transactions is very structured and highly predictable, it is expected that MAC keys will naturally expire within a predefined time interval. At most, keys should expire from one year of their issue. A better practice would have them expire at least every six months. Merchants generating a high volume of traffic might benefit from the security of having keys expire every three months.
When a new key is requested, the request is matched against the known merchant values of merchant id, passphrase and current key value. If this authentication is successful, then a new cryptographically strong randomly generated key is issued to the merchant over a secure web connection. This key is a four byte key with a specified sequential serial number. Upon request, the key is returned to the merchant over the secure web connection as a hexadecimal value and simultaneously stored within the merchant configuration database.
The sequence diagrams for the Process Recurring Transaction, Process Credit, Process Capture, and Process Authorization are identical to the Make Cardholder Order sequence diagram. The determination of which extension to use will be flagged in the XML document sent to the Transaction Verifier. A Make Shopping Cart Order always uses the Process Capture extension.
In the Shopping Cart Order Use case, a great deal of effort is expended on gathering and verifying data. The information-gathering task is centered in the Cardholder Interface. This module is responsible for catching the Shopping Cart Order XML document and then querying the customer for their card and order fulfillment information. This information is then used to construct a Transaction object, which is in turn a composite of ShoppingCart, Address, and Cardholder objects. The Transaction object is then passed to the Transaction Verifier. If the Transaction Verifier reports an error back to the Cardholder Interface, the Interface must determine if this is an error correctable by the cardholder (such as a bad card number) or an unrecoverable error (such as an invalid MAC). In either case, a message should be displayed to the cardholder with possibly a new form to correct any missing or inaccurate cardholder information. If the error is merchant-generated, then it must be reported to the system for referral to the merchant’s technical personnel. For this reason, merchant-generated errors cause program flow to be routed immediately to the Transaction Responder. The Responder creates a Response object identifying the type of error and reports this error to the system administrator and/or merchant.
The Transaction Verifier is responsible for verifying that all the required information is present. Any missing information must be supplied by the Merchant Configuration settings or an error will result. The Transaction Verifier also ensures that the MAC is valid for the XML document supplied. Validating the MAC involves a number of tests:
The Transaction Verifier also provides a number of additional functions:
If the Transaction Verifier detects no error, it passes the Transaction object on to the Host Message Parser. The Host Message Parser determines where the transaction is to be sent for back-end acquiring. It then uses a table of translation values to translate the required elements from the Transaction object into the host-specific string for the type of transaction to be processed.
The Host Message Parser then opens a connection to the specific host and sends the transaction string, then waits for a response. Upon receiving a response, it parses the response string into a Response object and passes this object to the Transaction Responder for further processing. Both the transaction and the response are logged to a database.
The Transaction Responder creates a Transaction Response XML document and calculates a MAC for this document using the merchant’s key. The Response object is optionally constructed into an e-mail document and delivered to the merchant and/or pushed to the merchant’s server. The Response object is also returned to the Cardholder Interface so that a web page can be constructed for the cardholder informing them of the status of their order.
Cardholder Orders are similar to Shopping Cart Orders except that no HTML interface is required. The Transaction Interface accepts an XML document and parses it into the component objects belonging to a Transaction object: Cardholder, Address, and Shopping Cart. These components are then passed on to the Transaction Verifier for creation of a Transaction Object. As in the Shopping Cart Order, the Transaction Verifier checks all aspects of the order with the exception of calculateShippingCosts. In the Cardholder Order, the price passed to the acquirer is always the final price.
If the Transaction Verifier discovers an error, processing flow is passed to the Transaction Responder. The Responder then generates a Response object documenting the details of this error and then passes the Response object back to the Transaction Interface as well as reporting the error to a system administrator and/or merchant. Otherwise, processing continues with the Host Message Parser. Order processing continues as per the Shopping Cart Order model.
The Purchase Response Class diagram is indicative of a general group of class diagrams where a merchant seeks to query the acquirer’s database concerning the status of a transaction. In some cases, these queries will be for a single transaction and in other cases, the query will seek an aggregate value such as the net or gross value of all purchases processed within a given period.
In all these cases, the class structure is comparable: a merchant points a browser to an SSL encrypted URL and logs onto the acquirer system with a username (or merchant id) and password. The Merchant Interface sends this data to the Merchant Authenticator for validation and upon a successful response, sends a cookie back to the merchant’s browser with a time-limited authentication token. This token is also stored by the acquirer system. As long as the two tokens match and the token has not expired, the merchant is deemed to be authenticated for all future connections. The token is also “freshened” with a new expiry date after every HTTP exchange.
With an authenticated session, the Merchant Interface will construct a query and send it to the Datastore Interface. The Datastore Interface will then run the query against the backend database and return the results.
It is important to note that the Datastore Interface must be protected from the end-user. Without this protection, there is a danger that the end-user could run a custom query against the database returning data that does not belong to the originating merchant.
Requesting a new MAC Key involves the Merchant authenticating themselves as in the previous example. At this point, there are two possible scenarios:
Links
[1] https://niedermayer.ca/user/login?destination=node/153%23comment-form
[2] https://niedermayer.ca/user/login?destination=node/154%23comment-form
[3] https://niedermayer.ca/user/login?destination=node/155%23comment-form
[4] https://niedermayer.ca/user/login?destination=node/156%23comment-form
[5] https://niedermayer.ca/user/login?destination=node/157%23comment-form
[6] https://niedermayer.ca/user/login?destination=node/158%23comment-form
[7] https://niedermayer.ca/user/login?destination=node/159%23comment-form
[8] https://niedermayer.ca/user/login?destination=node/160%23comment-form
[9] https://niedermayer.ca/user/login?destination=node/161%23comment-form
[10] https://niedermayer.ca/user/login?destination=node/162%23comment-form