In addition to the client payment component (CPC), which stores and manages a third-party payment method, the Wallet SDK supports the creation of credit cards other than the three standard types (Visa, MasterCard, American Express) that are available in the Payment Selector. In addition to these standard credit card types, the Payment Selector provides the same user interface and payment selection for the management of any other custom credit card (such as a department store charge card). The sample included with the SDK is referred to as the Other Card. This section discusses how to create a custom credit card using the Other Card sample files.
Other Card instances can be created and configured as payment options in the Payment Selector using the methods of the ICreditCardOtherCard interface. Refer to the “Credit Card Component (Other Card) Interfaces” section for a detailed description of the Other Card interfaces and function syntax.
The Other Card component is a plug-in to the standard Credit Card component. As such, it uses the Credit Card component’s user interface and multiple-threading support.
The following diagram illustrates how the Other Card component functions within the Payment Selector architecture.
Other Card components are Automation (IDispatch) objects.
As a standard ActiveX™ object, the sample Other Card DLL included with this SDK can be built using the following required tools:
The Microsoft CABinet Development Kit, which you can download from http://www.microsoft.com/intdev/cab/tools.htm, provides the compression and decompression tools used to distribute your Other Card component in easy-to-install .cab files. With the CABinet Development Kit tools, you can use the sample installation files to distribute your Other Card plug-in from your Web page.
The Other Card sample files in the SDK provide the source files that you need to construct your own Other Card component. With these tools and a few modifications to the provided sample code, you can build an Other Card credit card type. Using the default Credit Card component, you can then create and store instances of your credit card type in the registry.
To help you build an Other Card DLL, the following sample files are provided in the \SDK\Wallet\Samples\OtherCards\VolcanoCoffee subdirectory in the Microsoft® Wallet version 2.1 installation:
You can set up an Other Card component that interfaces with the Payment Selector by using the required tools and modifying the sample source files. You can then test your component by using the Payment Selector control, which you can download and install from http://www.microsoft.com/wallet.
The Payment Selector supports single processes with multiple threads and multiple processes with one or more threads. Because the Other Card component is a plug-in to the standard Credit Card component, which is multiple thread safe, the Other Card component also supports multiple threads.
This section describes the sample files included in the SDK for implementing an Other Card component. It also details what modifications, if any, must be made to each file to customize it. Many of the following files contain the comment MOD TODO to indicate each line that requires modification. Search each file for the MOD TODO comment to customize the files for your Other Card.
Comments are not allowed in the MyCard.rgs file, so that file has no MOD TODO comments, even though changes are required. See this section for more information.
This key source file is generated by the ATL Wizard, and handles DLLMain integration. This file requires no changes.
This header file handles the declaration of the COtherCardObject class.
Modify the ProgID to reflect the name of your Other Card. In the following strings, change the VCCard string to match the name of your custom credit card:
// MOD TODO: This is the program id of the other card being created. Change
// the four occurrences of VCCard to <YourCardName> This must be modified to
// reflect the naming of your Card.
#define OtherProgID "VCCard.VCCard.1"
#define WideOtherProgID L"VCCard.VCCard.1"
// MOD TODO: Change &CLSID_VCCard to &CLSID_<YourCardName>
// MOD TODO: Change both occurrences of &LIBID_VCCardLib to &LIBID_<YourCardName>Lib
public CComCoClass<CVCCard, &CLSID_VCCard>,
public IDispatchImpl<ICreditCardOtherCard, &IID_ICreditCardOtherCard, &LIBID_VCCardLib>,
public IDispatchImpl<IPaymentCCTypeInstall, &IID_IPaymentCCTypeInstall, &LIBID_VCCardLib>This source file implements the member functions of the ICreditCardOtherCard interface that is used to create and configure credit cards in the consumer’s Payment Selector. Use the provided interface functions GetBitmap, IsValid, and GetMask to manage instances of the Other Card. Explanation and examples of function syntax are provided in the “Credit Card Component (Other Card) Interfaces” section.
The file MyCard.ccp contains the comment MOD TODO to indicate each line that requires modification. Search the file for the MOD TODO comment to customize the file for your Other Card.
The sample Other Card implementation contains two credit cards: Microsoft Card and Microsoft Gold Card. In the following section, change the name of the accepted credit card type from the default MSCard or MSGCard to the short name of your Other Card. Also, change the display (friendly) names to the display names of your cards. You can also change the names of the constants, but if you do, change all occurrences in the file.
You can also indicate the maximum number of credit cards allowed for this type:.
// MOD TODO: Change the number of cards you are installing here (cMaxCards).
// MOD TODO: Change the two card name strings, = L"VCCard"; to = L"<YourCardName>";
// MOD TODO: Change the two friendly name strings, = L"Volcano Coffee Card" to
// = L"<Your Friendly Card Name>";
static const int cMaxCards = 2;
static const OLECHAR* szVCName = L"VCCard";
static const OLECHAR* szVCGName = L"VCGCard";
static const OLECHAR* szVCFName = L"Volcano Coffee Card";
static const OLECHAR* szVCGFName = L"Volcano Coffee Gold Card";
Next, change the credit-card number mask to reflect the configuration of numbers on your card. Change the following section:
// MOD TODO: These are the masks that are returned to the Add/Modify you can only
// use n = numeric and a = alpa and x = alph/numeric
//
static const OLECHAR* szVCNameMask = L"nnn-aaa-nnn";
static const OLECHAR* szVCGNameMask = L"nnn-a-nnn";
static const unsigned int cVCCard = 9;
static const unsigned int cVCGCard = 7;
For example, if your card uses four groups of four digits (for example, 1111 1111 1111 1111), change the previous code to the following:
static const OLECHAR* szMask = L"nnnn-nnnn-nnnn-nnnn";
static const unsigned int cLength = 16;
Make sure that the credit-card mask for your Other Card number does not exceed 20 digits (not including spaces).
Modify the following string to identify the cards being installed as a group:
// MOD TODO: The following string is used to identify the cards being installed as a group. If there is a single name then this should reflect the TYPE.
//
static const OLECHAR* wszAcceptName = L"Microsoft Cards";
You can modify the following string to reflect the name of the company or organization that creates the card:
// MOD TODO: The following string reflects the entity creating the card
//
static const OLECHAR* wszSource = L"Microsoft";
// MOD TODO: This structure just make it easier to grab the above definitions it should reflect the cMaxCards size. Comment out any extra cards.
//
static const CardDescription gCards[cMaxCards] = {
{szMSName,szMSFName},
{szMSGName,szMSGFName}
};
Load the bitmaps for your card by changing the following section. In this example, each card uses two bitmaps: a large and a small representation of the card:
// MOD TODO: Load the bitmaps into memory and hold onto them
// until the object is destroyed.
//
COtherCardObject::COtherCardObject()
{
if (dwBitRefCnt++ == 0) {
hSBitmap = Load256Bitmap(IDB_SMMSCRD);
hLBitmap = Load256Bitmap(IDB_MSCARD);
hSGBitmap = Load256Bitmap(IDB_SMMSGCRD);
hLGBitmap = Load256Bitmap(IDB_MSGOLDCARD);
}
}
Provide card number validation by changing the following section (the code is too long for this document, see the following header in MyCard.cpp):
// MOD TODO: Edit this routine to validate your specific card numbers.
// Note: If you have no validation checks, just return S_OK.
//
This is the module definition file created by the ATL Wizard. Change the following line to match the name of your Other Card DLL:
;MOD TODO: Change "OtherCard.DLL" to "<YourCardName>.DLL"
LIBRARY "OTHERCARD.DLL"
This is the Microsoft® Visual C++® makefile for the sample Other Card project. It is recommended that you let Developer Studio™ create a makefile for you by creating a new Developer Studio project workspace (see the section “Using Visual C++”). This file requires no changes.
This is the resource file used by your Other Card component. Change the following line to match the name of your Other Card DLL:
// MOD TODO Change this occurrence of 1 TYPELIB ""OtherCard.tlb""\r\n" to
// 1 TYPELIB ""<YourCardName>.tlb""\r\n"
//
"1 TYPELIB ""Othercard.tlb""\r\n"
You can also change the following lines to customize the version information in your Other Card DLL:
BLOCK "StringFileInfo"
BEGIN
BLOCK "040904b0"
BEGIN
VALUE "CompanyName", "Microsoft Corporation\0"
VALUE "FileDescription", "OtherCard Module\0"
VALUE "FileVersion", "1, 0, 0, 1\0"
VALUE "InternalName", "OTHERCARD\0"
VALUE "LegalCopyright", "Copyright © 1995\0"
VALUE "OriginalFilename", "OTHERCARD.DLL\0"
VALUE "ProductName", "Example Credit Card Extension\0"
VALUE "ProductVersion", "1, 0, 0, 1\0"
END
This .idl file defines the Other Card object. It is read by the MIDL compiler, which generates the type libraries. You must create two new globally unique identifiers (GUIDs) and insert them at the following locations:
// MOD TODO: Change three occurrences of VCCard to <YourCardName>
// MOD TODO: you need to replace the following two uuid's with new
// generated uuid's. These are used to identify your object and
// typelib.
[
uuid(130AF030-E8B9-11d0-BB16-00AA00A13794),
version(1.0),
helpstring("VCCard 1.0 Type Library")
]
// MOD TODO: Change VCCardLib to <YourCardName>Lib
library VCCardLib
{
importlib("stdole32.tlb");
[
uuid(130AF031-E8B9-11d0-BB16-00AA00A13794),
helpstring("VCCard Class")
]
coclass VCCard
{
[default] interface ICreditCardOtherCard;
interface IPaymentCCTypeInstall;
};
};
Because comments are not allowed in the .rgs file, you’ll find no MOD TODO comments. However, you must change the GUID specified in that file to the coclass GUID (the second GUID) that you specified in your OtherCard.idl file. Additionally, change all references to VCCard to <YourCardName>.
{
VCCard.VCCard.1 = s 'VCCard Class'
{
CLSID = s '{130AF031-E8B9-11d0-BB16-00AA00A13794}'
}
VCCard.VCCard = s 'VCCard Class'
{
CurVer = s 'VCCard.VCCard.1'
}
NoRemove CLSID
{
ForceRemove {130AF031-E8B9-11d0-BB16-00AA00A13794} = s 'VCCard Class'
{
ProgID = s 'VCCard.VCCard.1'
VersionIndependentProgID = s 'VCCard.VCCard'
ForceRemove 'Programmable'
InprocServer32 = s '%MODULE%'
{
val ThreadingModel = s 'Apartment'
}
}
}
}
This source file implements a generic registry class that controls registration with the Payment Selector. This file requires no changes.
After modifying the files previously listed, you are ready to build your own Other Card DLL. The OtherCard.mak file is a MVisual C++ makefile that you can use to build a sample Other Card component. If you use this makefile to build your Other Card DLL, you must change all references to OtherCard to the name of the credit card you are building. It is recommended, however, that you let Developer Studio create a makefile for you by creating a new Developer Studio project workspace.
If you encounter any problems creating your own version of this sample, or if you lack experience with Visual C++ 5.0, you can create a COM object by any means with which you are familiar. This object must implement ICreditCardOtherCard and IPaymentCCTypeInstall.
After you have built your Other Card component, users of your payment-enabled Web site will have to download and register the component. To accomplish this, you can customize the files located in the \SDK\Wallet\Samples\Install directory.
These files include the CabArc.exe, OtherCard.inf, OtherCard.dll and BuildCab.bat file. You use these files to build the .cab file that will referenced by the <OBJECT> tag for your plug-in.
For users of Microsoft® Internet Explorer version 3.0 and later, create a link on your Web page to the .cab file. When users load the Web page, the control and plug-in will be downloaded, installed, and registered automatically. To create a .cab file, download the CAB tools and enter the following at a command prompt:
diamond /f OtherCard.ddf
Next, modify the HTML on your Web page. For example:
<html>
<head>
<title>Standard Other Card Install</title>
</head>
<OBJECT id=paySelector classid="clsid:9DAE9125-0C35-11D0-8EEA-00A0C9054334"
codebase="http://servername/othercard.cab#Version=1,0,0,0001"
width=300 height=250 >
<PARAM Name="AcceptedTypes"
Value="visa:clear;mastercard:clear;amex:clear;othercard:clear" >
<PARAM Name="Total" Value="134.50" >
</OBJECT>
Alternatively, create a link that allows the user to explicitly download the Other Card plug-in:
<BODY>
<h2> <align=center><a href="othercard.cab">Install Other Card DLL</a> </h2>
</body>
</html>
The procedure for installing the Other Card DLL is somewhat different for users of Netscape Navigator. To support these users, build a self-extracting executable file for download. The program that extracts files from .cab files, EXTRACT.EXE, will automatically extract the files in that .cab file (and any subsequent .cab files) if it has been prefixed to the first .cab file.
For example:
C:> diamond /f othercard.ddf ; Build CAB file set othercard.cab
C:> copy /b extract.exe+othercard.cab othercard.exe ; othercard.exe is self-extracting
Create a link on your Web page to the self-extracting executable file for users to download. For example:
<html>
<head>
<title>Standard Other Card Install</title>
</head>
<BODY>
<h2> <align=center><a href="othrcard.exe">Install Other Card DLL</a> </h2>
</body>
</html>
Next, you must create a setup program that installs the files to their appropriate directories and registers them.
For information about .cab files and self-extracting archives, see the following Web site:
http://www.microsoft.com/workshop/default.asp
After you have built your Other Card, you should get a digital signature for your component to provide accountability to users downloading from your Web site. Supported in Microsoft® Internet Explorer version 3.0, Authenticode™ is Microsoft’s implementation of its code-signing proposal to the W3C. Authenticode uses documented Win32® functionality available to any Microsoft® Windows® 95–based or Microsoft® Windows NT®–based application, and works with Java applets, plug-ins, and ActiveX™ controls to provide accountability for these types of software components. Through Authenticode, end users know who published a piece of software and whether the software has been tampered with, before downloading the software to their PC.
Note that Netscape Navigator 3.0 does not support Authenticode or any code-signing technology. As such, Navigator does not recognize and alert users to unsigned plug-ins or other unsigned executable files.
For information about code signing, refer to http://www.microsoft.com/intdev/security/.
The Other Card component is a plug-in to the standard Credit Card component, and allows merchants to offer credit card payment types other than VISA, MasterCard, and American Express. These OtherCards use the following interfaces to support payment instances and installation of payment instances:
As a plug-in to the default Credit Card component, the Other Card component shares the default component’s support for multiple thread safety and the Payment Selector user interface (including the Add Card Wizard). The Credit Card component calls methods on the ICreditCardOtherCard interface to add and modify instances of the payment type, and obtain bitmaps to display in the Payment Selector user interface. Use the IPaymentOtherCardInstall and IPaymentCCTypeInstall interfaces to install and integrate payment types into a consumer’s Payment Selector. The IPaymentCCTypeInstall and IPaymentOtherCardInstall interfaces define a set of methods that add an Other Card DLL to the Credit Card component. Calls to methods of the ICreditCardOtherCard interface plug the Other Card component into the Credit Card component, thereby integrating the Other Card payment type into the Payment Selector user interface.
The ICreditCardOtherCard interface allows the Credit Card component to support Other Card components. This interface contains the following methods:
HRESULT GetBitmap(
BSTRbstrType// in
longfType// in
long *hBitMap// out
);
The GetBitmap function returns a bitmap handle based upon the type of the instance. Large (120 × 79, 16–system color) and small (30 × 18, 16–system color) bitmaps are defined or supported. It is valid to return zero if a bitmap does not exist. In this case, the default bitmap for the Payment Selector is used.
This function returns one of the following values.
| Value | Meaning |
|---|---|
| E_FAIL | Failure |
| S_OK | Success |
HRESULT GetMask(
BSTRbstrType// in
LONG *expDate// out
BSTR *bstrMask// out
);
The GetMask function returns a string containing the mask for a specified payment type. There is no default mask; therefore, if a zero (0) is returned, this is an error. A mask is required in order for a credit-card number to appear in the Add dialog box. A flag is also returned that indicates whether or not the card contains an expiration date.
Characters in the mask can be in uppercase or lowercase. The mask should not exceed 20 characters in length (excluding spaces).
If you specify constants for the mask, these are displayed in the dialog box presented to the consumer by the Payment Selector. Notice that, for purposes of transactions, these constants will not be posted as part of the consumer’s card number ; instead, only the characters entered by the consumer are posted.
This function returns one of the following values.
| Value | Meaning |
|---|---|
| E_FAIL | Failure |
| E_OUTOFMEMORY | Insufficient memory |
| S_OK | Success |
HRESULT IsValid(
BSTRbstrType// in
BSTRbstrNumber// in
long *fValid// out
);
The IsValid function determines whether the instance is valid based on the credit-card number entered by the consumer for the mask. You can include your own validation algorithm to perform further validation on the credit-card number.
This function returns one of the following values.
| Value | Meaning |
|---|---|
| E_FAIL | Failure |
| E_OUTOFMEMORY | Insufficient memory |
| S_OK | Success |
An Other Card DLL can be added to the Credit Card component using the following installation interfaces:
The Other Card DLL supports an Automation interface (IPaymentCCTypeInstall) that is called during registration. The IPaymentCCTypeInstall interface then obtains a pointer to a Credit Card component interface (IPaymentOtherCardInstall). The Credit Card CPC only installs an Other Card if it is unique. These two interfaces determine whether the Other Card to be installed has unique types before installing the Other Card’s types into the Payment Selector.
Note that the Credit Card component drives the actual installation process. The member functions of the IPaymentCCTypeInstall interface are support functions called by the Credit Card component to query the information necessary to install the Other Card DLL. The Credit Card CPC interacts with the Payment Manager during the install process.
The Credit Card DLL manages the installation process through the IPaymentCCTypeInstall interface of the Other Card DLL. During DLL registration, the Other Card writes a value into the registry informing the Credit Card CPC that it needs to be installed. The registry value is HKEY_LOCAL_MACHINE\Software\Microsoft\Internet Shopper\Install CreditCard\“ProgID.” The first time the Credit Card CPC runs, it will then install the Other Card.
Note that the Other Card installation process enforces type uniqueness across all CPCs by turning on and off types that conflict with other types. The Payment Manager determines the status of on or off for each type. For example, a new type may be turned off if the type conflicts with a type in another CPC installed in the Payment Manager.
Implemented by the Credit Card component, the IPaymentOtherCardInstall interface is obtained when an existing Other Card DLL is uninstalled, usually during unregistration of the DLL. This removes the Other Card DLL and all data associated with it.
This interface contains the following method:
HRESULT UninstallType(
BSTR bstrProgID// in
);
The UninstallType function uninstalls the Other Card DLL of the deleted payment type.
The Other Card DLL file implements the CPC installation interface IPaymentCCTypeInstall to install the Other Card’s unique type. This interface contains the following methods:
HRESULT GetInstallInfo(
long *plCount// out
BSTR *pbstrName// out
BSTR *pbstrSource// out
);
The Credit Card component calls the GetInstallInfo function to obtain general information about the Other Card DLL being installed.
This function returns one of the following values.
| Value | Meaning |
|---|---|
| E_FAIL | Failure |
| E_OUTOFMEMORY | Insufficient memory |
| S_OK | Success |
HRESULT GetInstallInfo(
longcIndex// in
BSTR *pbstrType// out
BSTR *pbstrFriendName// out
);
The GetTypeInfo function obtains information about a unique type supported by the Other Card DLL. The Credit Card component uses this information (which is accessed as a zero-based array) to track the types stored in the Other Card DLL.
This function returns one of the following values.
| Value | Meaning |
|---|---|
| E_FAIL | Failure |
| E_OUTOFMEMORY | Insufficient memory |
| S_OK | Success |
HRESULT SelfUninstall(void);
The SelfUninstall function is called from the Other Card DLL to delete itself from the Microsoft® Wallet.
None.
This function returns one of the following values.
| Value | Meaning |
|---|---|
| E_FAIL | Failure |
| E_OUTOFMEMORY | Insufficient memory |
| S_OK | Success |
HRESULT Uninstall(void);
The Credit Card component calls the Uninstall function to uninstall the Other Card DLL. The Other Card DLL should unregister itself so that it will not be recognized by the system.
None.
This function returns one of the following values.
| Value | Meaning |
|---|---|
| E_FAIL | Failure |
| E_OUTOFMEMORY | Insufficient memory |
| S_OK | Success |