The Credit Card client payment component (CPC) supports a Payment Builder plug-in component that implements the following interfaces:
The Payment Builder interfaces allow third-party encryption and payment instruction (PI) building methods to plug into the CPC in the Microsoft® Wallet.
The Microsoft® Wallet implements the clear text protocol, which is built into the Credit Card client payment component (CPC) and supports the type CCPMNT and all of the additional fields that contain the credit-card and billing information.
All other protocols are installed into the Credit Card CPC by registry entries in the /Credit Card/Protocol/Install registry key. When a protocol is installed, it writes its program identifier (ProgID) of the Component Object Model (COM) object that implements ICreditCardEncryption2 to this key.
When a user attempts some action that affects a given protocol, the Wallet retrieves the protocol’s ProgID from the Registry and uses it to create an instance of the affected protocol’s ICreditCardEncryption2 implementation. The Wallet then calls the appropriate interface method. Thus, for example, when a user attempts to delete a Credit Card through the Payment control interface, the Wallet calls the affected protocol’s implementation of ICreditCardEncryption2::PreDelete.
For a given payment protocol, some of the payment information stored in the Wallet (such as a credit-card number), must remain constant for the protocol to work. For example, with SET, the certificate must be valid, and that certificate is dependent on the card number and the expiration date. As such, if the shopper is able to change this information, it will invalidate the certificate for use in subsequent purchases. Using the ICreditCardEncryption2 interface, the Payment Builder is notified when the shopper is changing information about the credit card, prior to the change, and should display a warning as to the results of choosing to proceed. The Payment Builder also needs an opportunity to tell the shopper that this is happening.
The ICreditCardEncryption2_CallBack interface implements callback methods that return pointers to credit card and billing information, replacing the GetCreditCard and GetAddress function pointers in the old ICreditCardEncryption::GenPayInstruction method. Additionally, ICreditCardEncryption2_CallBack defines two methods, GetExtensionProperty and SetExtensionProperty, that the protocol can use to set or query the custom property values for the affected Credit Card.
The ICreditCardEncryption interface is no longer supported. You need to port existing code to use the ICreditCardEncryption2 interface.
The Credit Card CPC selects an encryption protocol based upon the accepted types string. The string is evaluated from left to right, comparing the payment method and protocol until a match is found.
For example, if the string “Visa:SET;Visa:Clear;MasterCard:Clear;AMEX:SET” is the accepted types string, when the user selects a Visa card, SET will be used because it is the match that is located the farthest to the left. If a MasterCard is selected, Clear will be used because it is the only protocol defined for MasterCard. If AMEX is selected, SET will be used. Matches are done left to right and the first match found is used. A merchant can move the strongest encryption protocols or preferred protocols to the left side of less preferred protocols. If the first matching protocol fails, the next matching protocol is used.
The ICreditCardEncryption2 interface allows the payment instruction (PI) to be use security protocols that the client can install in the Microsoft® Wallet. This interface consists of the following functions:
The encryption protocol used to create the payment instruction is selected based upon the AcceptedTypes payment property specified by the merchant. The AcceptedTypes payment property defines which payment types a merchant accepts in an electronic transaction. A protocol is responsible for the creation of the PI. The PI is posted back to the server as if the information were entered in an HTML form. The PI may contain one or more fields. The information is returned as a two-dimensional SAFEARRAY of name/value pairs. All PIs should contain a “TYPE” field along with all additional fields.
HRESULT CreateProtocol(
ICreditCardEncryption2_Callback *pCallBack// in
);
The Wallet calls the CreateProtocol method to pass an instance of the ICreditCardEncryption2_Callback interface to the Payment Builder's implementation of ICreditCardEncryption2.
The ICreditCardEncrypt2_Callback interface implements methods that support setting and retrieving information about the Credit Card, including its current property values. Typically, the Payment Builder's ICreditCardEncryption2 stores the ICreditCardEncryption2_Callback interface pointer, so that the callback interface's methods can be called by ICreditCardEncryption2 interface methods.
This is the first method called when a protocol is instantiated.
HRESULT GetType(
BSTR*pbstrType// out
);
The Wallet calls the GetType method upon loading the protocol to retrieve the encryption protocol type. This type appears on the left hand side of each payment method accepted by the merchant. The Credit Card component implements the type “clear”. If the AcceptedTypes property value string is “Visa:Clear”, Visa is the payment type and Clear the protocol type.
STDMETHOD Add(
HWND hWnd// in
CREDITCARDINFO *pCCInfo// in
BYTE ** ppBlob// in, out
long *cLen// in, out
);
The Wallet calls the Add method when a new payment instance is being added. The Wallet's call to this method allows the plug-in protocol to query information from the user, which is then stored for later use by the Credit Card CPC.
STDMETHOD PreModify(
long hWnd// in
CREDITCARDINFO *pOldCCInfo// in
CREDITCARDINFO *pNewCCInfo// in
BYTE ** ppBlob// out
long *cLen// out
BSTR*pbstrErrMsg// out
);
The Wallet calls the Payment Builder's implementation of PreModify to notify the payment builder that a payment instance is being changed. This notification provides the payment builder an opportunity to warn the user in the event that the modification will affect the use of the protocol. The Payment builder provides this notification by returning S_FALSE, and by storing the text of the warning in pbstrErrMsg. The Wallet then displays this message to the user.
If the user chooses to cancel the modification, the Modify method is not called.
The CPC displays the message contained in pbstrErrMsg to the user only if PreModify returns S_FALSE.
STDMETHOD Modify(
HWND hWnd// in
CREDITCARDINFO *pOldCCInfo// in
CREDITCARDINFO *pNewCCInfo// in
BYTE ** ppBlob// out
long *cLen// out
);
The Wallet calls the Payment Builder's implementation of the Modify method to modify the payment instance.
STDMETHOD PreDelete(
HWND hWnd// in
CREDITCARDINFO *pOldCCInfo// in
BYTE ** ppBlob// out
long *cLen// in, out
BSTR *pbstrErrMsg// out
);
The PreDelete method is called when a payment instance is to be deleted. The Wallet calls this method to give the Payment Builder a chance to warn the user in the event that the deletion will affect the user of the protocol. The Payment Builder provides this warning by returning S_FALSE, and by storing the text of the warning in the pbstrErrMsg out parameter.
If the shopper opts not to continue the deletion, the Delete method is not called.
The CPC displays the message contained in bstrErrMsg to the user only if PreDelete returns S_FALSE.
STDMETHOD Delete(
HWND hWnd// in
CREDITCARDINFO *pCCInfo// in
BYTE ** ppBlob// out
long *cLen// in, out
);
If the user confirms the deletion of a credit card, the Wallet calls the Delete method to delete the payment instance.
STDMETHOD GenPayInstruction(
HWND hWnd// in
BYTE *pvarBlob// in
longcLen// in
BSTR bstrFriendlyName// in
BSTRbstrTotal// in
BSTRbstrHashOrder// in
ICreditCardEncryption2_CallBack *
pCallBack// in
VARIANT *pvarNameValueArray// in
);
The GenPayInstruction method generates a payment instruction (PI) and returns the PI as a set of name/value pairs.
The ICreditCardEncryption2_Callback Interface supports methods that return the credit card and billing address information in a CREDITCARDINFO structure, and allows the Payment Builder to set and retrieve custom properties. An interface pointer on ICreditCardEncryption2_Callback is passed to the Payment Builder's implementation of ICreditCardEncryption when the Wallet calls ICreditCardEncryption::CreateProtocol.
The ICreditCardEncryption2_Callback interface supports the following methods:
The ICreditCardEncryption2::GenPayInstruction method requires a pointer to this interface.
The CREDITCARDINFO structure is defined as follows:
typedef struct
{
FRIENDLYNAME szFriendlyName; // friendly name of the card
DWORD dwFlags;
CARDNUMBER szCreditCardNumber;
EXPDATE szCreditExpiration;
DWORD dwCreditCardType; // the credit card type
CREDITCARDNAME szCreditCardName; // the name of the card
CUSTOMERNAME szCustomerName; // customer name, may be distinct from billing address name
ADDRFRIENDNAME szAddrFriendName; // Friendly name of the address
} CREDITCARDINFO, *PCREDITCARDINFO;
HRESULT GetCreditCard(
BSTRbstrFriendname, // in
BSTR bstrTotal// in
CREDITCARDINFO *pCreditCard// out
);
The GetCreditCard method returns a pointer to the credit-card information in a CREDITCARDINFO structure. The user is always asked for a password before the credit card is returned. A Payment Builder must handle a failure on this routine by returning the result back to the Credit Card component.
STDMETHOD GetBillAddress(
BSTRbstrAddrFriendName, // in
BSTR bstrPrefix// in
VARIANT *psa// out
);
The GetBillAddress function returns a pointer to the billing address that is associated with a credit card. The credit-card information must be retrieved before this method is called, because this method requires the friendly name of the Billing Address entry.
HRESULT GetExtensionProperty(
BSTR bstrPropertyNamej// in
BSTR *pbstrPropertyValue// out
);
The GetExtensionProperty function is a callback function that retrieves the value of a specified property from the script.
If the payment builder needs extra information to generate its payment instruction (the merchant name or identifier, for example), these properties can be set from JavaScript using the IPaySlideSelector's SetExtension property. The payment builder can then use ICreditCardEncryption2_Callback's GetExtensionProperty to retrieve this value.
HRESULT SetExtensionProperty(
BSTR bstrPropertyNamej// in
BSTRpbstrPropertyValue// out
);
The SetExtensionProperty function sets the value of the specified property. This property value can then be retrieved in JavaScript by means of the IPaySlidSelector's GetExtensionProperty method.