The sample client payment component (CPC) contains sample source files and accompanying documentation that you can use to build a client payment component that is supported by the Payment Selector control. The CPC object stores instances of your payment type. Instances are added, deleted, and modified using the user interface of the Payment Selector. The Payment Selector user interface also allows the user to choose your payment type from the Payment Selector to make online purchases.
The Payment Manager manages a new CPC using the member functions of the IClientPaymentProvider interface. Your payment option is displayed by the Payment Selector user interface when your CPC registers with the Payment Selector.
The following diagram illustrates how the CPC functions within the Microsoft® Wallet architecture.
A CPC object in the Payment Selector represents a payment method such as credit cards or electronic cash debit cards. Each CPC supports one or more types of that method. For example, a type of a credit card payment method is a VISA card. Each CPC may contain zero or more instances of any type supported by that CPC. Each instance possesses a friendly name that is unique across all CPCs in the Payment Selector.
The Payment Selector provides the consumer with a rich user interface for managing and selecting instances of payment types. Payment types (such as a VISA, bank, or department store card) are stored in the Payment Selector. When a user creates a new instance of an existing payment type (such as a second bank card), that instance is stored by the payment type component. These instances are locally managed according to a friendly name that is assigned by the user. Note that instances of payment types are never shared between different components in the Payment Selector.
After a consumer selects an instance of a payment type from the Payment Selector, a payment instruction (PI) is generated in that payment type component, routed through the Payment Selector, and sent over the browser to the server for the merchant to process payment. The PI may be encrypted and will pass through the Payment Selector as opaque data.
Refer to the “Client Payment Component (CPC) Interfaces” section for a detailed description of the CPC interfaces and function syntax.
Building a CPC consists simply of building an in-process Component Object Model (COM) server that implements the appropriate interfaces. The sample included this chapter illustrates this process.
To build and configure the sample CPC described in this chapter requires the following tools:
All CPCs must be in-process COM objects.
The CPC sample files in the Microsoft® Wallet SDK provide the dialog boxes, registry controls, utility routines, multiple-threading support, and other source files that you need to construct your own component. With these tools and a few modifications to the provided sample code, you can build a CPC that creates and stores instances of its payment type.
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 CPC in easy-to-install cabinet files. With the CABinet Development Kit tools, you can use the sample installation files to distribute your CPC from your Web page.
The client payment component (CPC) sample files (located in the \SDK\Wallet\Samples\CPCs\Simple directory) give you the framework to build your CPC by providing dialog boxes, multiple thread support, source files, and installation files. The following diagram explains the process of building a CPC using these sample files.
The Wallet SDK sample CPC, which is named Internet Cash, is designed for a single type of payment. A component supports multiple types, but each type must be unique. For example, the default Credit Card component in the Payment Selector contains three unique types: VISA, MasterCard, and American Express.
The following dialog sample files generate the dialog boxes required by a component.
| File name | Function |
|---|---|
| AddDlg.cpp | Provides the Internet Cash Add dialog box for adding new instances of the sample CPC payment type (ATL Wizard generated). |
| EntPass.cpp | Enables the Internet Cash Use dialog box that asks the user for a password on any modify operations on an instance of a CPC payment type. |
| ModDlg.cpp | Provides the Modify Internet Cash dialog box for the user to modify an instance of the CPC payment type. |
| NewPass.cpp | Adds the Password dialog box. The CPC uses a wizard to step the user through the process of adding a password. |
| PIPass.cpp | Enables the Password dialog box that prompts the user for a password before posting information. Although this dialog box is not a requirement, you should provide the consumer with some notice when money is about to be spent. You must decide how to handle this prompting; instances such as microtransactions involving a few pennies may not warrant a warning. The Delete operation does not require a password. If a user forgets a password, the method of payment can be deleted and a new instance added. |
The source files that enable sample dialog boxes are standard Microsoft Developer Studio™ Wizard creations; they interact with the user to obtain information specific to the CPC, and are not very rich in sample format. The Payment Selector has a certain level of richness in its user interface that you should support when building your own dialog boxes. For example, the Add Card Wizard in the Payment Selector contains instructions for the user to explain the process of adding and using a method of payment. While building your dialog boxes, maintain the same level of richness in the dialog box user interface that the Payment Selector user interface offers.
You can use the following sample source files (located in the \CPC\sample directory) to set up your component’s DLL, access the component IClientPaymentProvider and IWalletCallback interfaces, and make changes to the registry.
| File name | Function |
|---|---|
| common.h | Header file that sets the macros for checking error codes. Provides entry keys for registering the CPC with the Payment Selector. |
| cpcinst.cpp | Contains all interfaces used during installation of the CPC. |
| CPCPlugIn.cpp | ATL-generated file that handles DLLMain integration and MFC CWinApp creation. This file has been modified for MFC threading support. |
| sdkobj.def | ATL Wizard–created CPC .def file. |
| cpcbject.mak | Make file generated by the CPC project. |
| CPCPlugIn.idl | File that defines the CPC object, which is read by the MIDL compiler. |
| CPCPlugIn.rc | CPC resource file. |
| CPCObject.cpp | Implements the member functions of the CPC interfaces. |
| regutil.cpp | Implements a generic registry class that registers the CPC. |
| utility.cpp | Defines simple utility routines used by the CPC object. |
This header file sets the macros for checking error codes and also provides the proper registry entry keys for registering the CPC with the Payment Selector. Use the unique name of your CPC as listed in the \CPCPlugIn directory to register the component.
The file common.h contains the comment MOD TODO in each line requiring modification. Search the file for the MOD TODO string and replace the default sample name Internet Cash with the unique name of your CPC:
// MOD TODO: You must create a key in the registry that reflects your CPC name. To do this you must
// replace "Internet Cash" with the name of your CPC.
//
#define RV_CCPLUGIN TEXT("HKEY_LOCAL_MACHINE\\Software\\Microsoft\\Internet Shopper\\PlugIns\\Internet Cash")
#define RV_CPCINSTALL TEXT("HKEY_LOCAL_MACHINE\\Software\\Microsoft\\Internet Shopper\\Install")
#define RK_CHANGECOUNT TEXT("ChangeCount")
#define RK_CPC_STATE TEXT("State")
Generate new programmatic identifiers (ProgIDs) for your CPC. The Payment Selector uses the ProgID to load the CPC. Note that the CPC ProgID must match the ProgID assigned in CPCPlugIn.cpp:
// MOD TODO: You must create a unque PROGID that reflects the name of the CPC. The PROGID is used by the Wallet to load the CPC. This PROGID must match the PROGID found in sdkplugin.cpp.
#define RK_PLG_VAL_CCPROGID TEXT("CPCPLUGIN.CPCPlugInObject.1")
Refer to the OLE Programmer’s Reference in the Win32® SDK for information regarding programmatic identifiers.
This key source file is generated by the ATL Wizard, and handles DLLMain integration and the MFC CWinApp creation.
It is important to note that the sample file provided has been modified to address MFC threading support for the component. If you do not use the sample file, you must devise a way to handle multiple threading and multiple processes on the client payment component level.
The CPCPlugIn.def file is created by the ATL Wizard, the CPCPlugIn.mak file is the make file generated by the sample CPC project, and the CPCPlugIn.rc file is the resource file used by your CPC.
The CPCPlugIn.idl file defines the CPC object. The MIDL compiler reads this file and then generates the type libraries and other linker files.
You should assign new globally unique identifiers (GUIDs) to configure the sample file for the CPC that you build. The file CPCPlugIn.idl contains the comment MOD TODO in each line requiring modification. Search the file for the MOD TODO comment and replace the existing GUID:
import "oaidl.idl";
import "ocidl.idl";
#include "iWalletCB.idl"
#include "iWalletCB2.idl"
#include "icpc.idl"
#include "ipayinst.idl"
// MOD TODO: Change all occurences of MyCPC to <YourCPCName>
//
// 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(5AC9D181-EC1A-11D0-BB19-00AA00A13794),
version(1.0),
helpstring("MyCPC 1.0 Type Library")
]
library MyCPCLib
{
importlib("stdole32.tlb");
importlib("stdole2.tlb");
[
uuid(5AC9D18F-EC1A-11D0-BB19-00AA00A13794),
helpstring("MyCPC Class")
]
coclass MyCPC
{
[default] interface IClientPaymentProvider;
interface IPaymentProviderInstall;
};
};
Refer to the MAPI Programmer’s Reference in the Win32 SDK for more information on creating new GUIDs.
This source file implements a generic registry class that controls registration with the Payment Selector.
This source file implements the member functions of the IClientPaymentProvider and ISelectorCallback interfaces that are used to create and configure payment types in the consumer’s Payment Selector.
In the CPCObject.cpp file, you will need to modify most of this code to support the CPC you are creating. The file CPCObject.cpp contains the comment MOD TODO in each line requiring modification. You can search the file for the MOD TODO comment to make required changes.
Change the friendly name from the default Internet Cash to the friendly name of your CPC:
// MOD TODO: This is the Friendly Name of the CPC type. You must change "Internet Cash" to the friendly name of your CPC.
//
#define SDK_TYPE L"Internet Cash"
static CString szType = SDK_TYPE;
Modify the accepted type and short name to reflect the friendly name of your CPC:
// MOD TODO: This is the Accepted Type (and short name) of the type of this CPC. You must change "ICash" to the short name of your CPC.
//
#define SDK_ACCEPT_TYPE _T("ICash")
CString szThisType = SDK_ACCEPT_TYPE;
Change the fields PAYMENT_TYPE, PAYMENT_ACCOUNT, and PAYMENT_AMOUNT given in the sample to reflect the fields that are being posted back as part of the payment instruction:
// MOD TODO: You should change this to reflect the fields that are being // posted back as part of the payment instruction. This defines a set of // constants and the names that are found in the post.
//
#define PAYMENT_TYPE 0
#define PAYMENT_ACCOUNT 1
#define PAYMENT_AMOUNT 2
static const cPaymentElements = 3; // MOD TODO: Should reflect the total number
static OLECHAR *rgszFieldNames[] =
{
L"Type",
L"Account",
L"Amount",
};
To prevent multiple processes from accessing critical sections, you should replace the sample mutex name “ICashSamplePlugin” with the unique name of your CPC:
// MOD TODO: You need to change the name of the Mutex to something that // reflects the CPC name.
//
m_hMutex = CreateMutex(
NULL, // No Scurity
FALSE, // initially not owned
"ICashSamplePluginMutex"); // name of the Mutex
if (m_hMutex == NULL)
return;
do {
dwWaitResult = WaitForSingleObject(
m_hMutex, // handle of mutex
1000L); // Wait for 1 second
Change the sample mapping file name “ICashSamplePlugin” to the unique name of your CPC:
// MOD TODO: You need to change the name of the Mapping file to something that reflects the CPC name.
//
if (dwWaitResult == WAIT_OBJECT_0) {
m_hMapObject = CreateFileMapping(
(HANDLE) 0xFFFFFFFF, // Use the Paging File
NULL, // No security
PAGE_READWRITE, // Read/Write access
0, // size: high 32-bits
sizeof(InstanceShare), // size: low 32-bits
"ICashSamplePluginShare");
if (!m_hMapObject)
return;
fInit = (GetLastError() != ERROR_ALREADY_EXISTS);
Replace the fields “PAYMENT_TYPE,” “PAYMENT_ACCOUNT”, and “PAYMENT_AMOUNT” in the sample code with the fields that will be posted back as part of the payment instruction. The SAFEARRAY will consist of name/value pairs whose names and values are stored as BSTRs:
// MOD TODO: This section of code will build the SAFEARRAY of name/value pairs that is posted back to the server.
//
FillVariants(pvar, PAYMENT_TYPE, cPaymentElements, SDK_ACCEPT_TYPE);
FillVariants(pvar, PAYMENT_ACCOUNT, cPaymentElements, m_pData->m_gData[dwIdx].Name);
FillVariantsWide(pvar, PAYMENT_AMOUNT, cPaymentElements, bstrTotal);
hr = S_OK;
Explanation and examples of function syntax are provided in the “Client Payment Component (CPC) Interfaces” section.
This source file defines a simple utility routine used by the CPC object, and provides a message box. You can modify this program to perform routines on the CPC that you create.
After modifying the client payment component (CPC) sample source files, you are ready to build your CPC DLL. The CPCPlugIn.dsw file is a Microsoft® Visual C++® makefile that you can use to build a sample CPC. If you use this makefile to build your CPC DLL, you must change all references to “cpcplgin” to the name of the payment method that 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 Component Object Model (COM) object by any means with which you are familiar. This object must implement ICreditCardEncryption2 and IPaymentProviderInstall.
The Payment Selector supports single processes with multiple threads and multiple processes with one or more threads. During the Add, Modify, and Delete functions, mutexes in the Payment Selector permit only one thread at a time to modify data. Each component is required to share its data among both multiple threads within a single process and multiple processes. Modifications using one instance of the control must be reflected in all instances. The SDK sample uses shared global memory to implement this requirement. You must ensure that multiple instances of the Create function are thread safe.
The SDK sample uses the following elements to ensure thread safety:
The MFC CWinApp class captures and transforms the first thread into an MFC thread in the component data structure when the DLL is loaded. The SDK files thrdwrap.cpp and thrdchk.h create the necessary threading structures within MFC to make MFC thread safe within a single process, independent of the shared global data structure. The thrdwrap.cpp file, which includes the thrdwrap.h header file, implements a thread class and checks thread routines to ensure that MFC has the necessary information to perform thread-safe processes. The thrdchk.h header file defines the entry points to the current thread to check whether or not it exists.
Although the majority of multiple-thread and multiple-process support occurs in the Payment Selector, you must provide a mutex for the Create function to ensure that new instances of the component are created in a thread-safe manner.
Do not modify the sample files thrdwrap.cpp and thrdchk.h, because these files support thread-safe processes in MFC.
See the Win32 Programmer’s Reference for additional information on creating a mutex.
After you have built your client payment component (CPC), users of your Web site will have to download and register the component. To accomplish this, you can customize the files located in the \CPCPlugIn\download directory.
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. For example:
<html>
<head>
<title>Standard Client Payment Component Install</title>
<meta name="GENERATOR" content="Microsoft FrontPage 1.1">
</head>
<OBJECT id=paySelector classid="clsid:3B23ADA5-E00D-11CF-8EE7-00A0C9054334"
codebase="http://example.microsoft.com/testpay/cpcplugin/cpcplugin.cab#Version=1,0,0,1135"
width=300 height=250 >
<PARAM Name="AcceptedTypes" Value="visa:clear;mastercard:clear;amex:clear;discover:clear" >
<PARAM Name="Total" Value="134.50" >
</OBJECT>
</html>
You can also create a link that allows the user to explicitly download the CPC:
<BODY>
<h2> <align=center><a href="cpcplugin.cab">Install Client Payment Component DLL</a> </h2>
</body>
</html>
The procedure for installing the CPC 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 cpcplugin.ddf ; Build CAB file set cpcplugin.cab
C:> copy /b extract.exe+cpcplugin.cab cpcplugin.exe ; cpcplugin.exe is self-extracting
Create a link on your Web page to the self-extracting executable for users to download. For example:
<html>
<head>
<title>Standard Client Payment Component Install</title>
</head>
<BODY>
<h2> <align=center><a href="cpcplugin.exe">Install Client Payment Component 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/java/cab.htm
After you have built your CPC, you should get a digital signature for your component to provide accountability to users downloading from your Web site. Supported in Internet Explorer 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. For information about code signing, refer to http://www.microsoft.com/intdev/security.
In addition to Credit Card component extensions, the Payment Manager supports instances of client payment components (CPCs) that offer other payment types other than credit cards (such as electronic cash). The following interfaces support a CPC and the installation of a CPC:
Use the functions in the client payment component (CPC) interfaces to offer additional payment types in the Microsoft Payment Selector. The Payment Manager calls methods on the IClientPaymentProvider interface to create and manage instances of a payment type in your CPC. The IWalletCallback interface methods guarantee that instances of payment types have unique names across all components in the Payment Selector. You can use these interfaces to present instances of your payment type (or types) as an option for Payment Selector users during online purchasing transactions. You must implement all the methods in the IClientPaymentProvider interface in order for the Payment Selector to fully support your CPC. In addition, call functions on the IPaymentProviderInstall interface in order to support the installation package for your CPC.
As a COM object, a CPC is responsible for its own memory allocation. When the reference count is zero, the CPC frees memory allocated to that object. All calls may return the E_OUTOFMEMORY (memory allocation failure) value.
A CPC object in the Payment Selector represents a payment method such as credit cards or electronic cash debit cards. Each CPC supports one or more types of that method. For example, a type of a credit card payment method is a VISA card. Each CPC may contain zero or more instances of any type supported by that CPC. Each instance possesses a friendly name that is unique across all CPC modules in the Payment Selector.
The Payment Selector provides the consumer with a rich user interface for managing and selecting instances of payment types. Payment types (such as a VISA, bank, or department store card) are stored in the Payment Selector. When a user creates a new instance of an existing payment type (such as a second bank card), that instance is stored by the payment type component. These instances are locally managed according to a friendly name that is assigned by the user. Note that instances of payment types are never shared between different components in the Payment Selector.
After a consumer selects an instance of a payment type from the Payment Selector, a payment instruction (PI) is generated in that payment type component, routed through the Payment Selector, and sent over the browser to the server for the merchant to process payment. The PI may be encrypted and will pass through the Payment Selector as opaque data.
All individual elements stored inside a CPC are retrieved by an index position. The accessor is treated as a zero-based array. There is no order imposed on the array and elements may move in the array during the lifetime of the object. For example, a delete operation will not leave a hole in the array. The index positions will change only during add or delete operations.
The IClientPaymentProvider interface is called from the Payment Selector and provides the following methods to create and modify instances of payment types in a CPC:
HRESULT Create(
IWalletCallback *piCB// in
);
The Create function is the initialization member function, and must be called before any other function is called. All other functions will fail if called before Create.
This function returns one of the following values.
| Value | Meaning |
|---|---|
| S_OK | Success |
| E_FAIL | Failure |
| E_OUTOFMEMORY | Out of memory |
During add and modify operations, the IWalletCallback::Exists function must be called to verify that no instance with the same friendly name exists across Payment Selector components.
HRESULT Terminate(void);
The Terminate function releases resources allocated by the object (the class destructor should also free these resources).
None.
This function returns the following value.
| Value | Meaning |
|---|---|
| S_OK | Success |
HRESULT GetTypeCount(
long *pcRet// out
);
The GetTypeCount function returns the number of types currently enabled in the CPC. All CPCs support at least one type but may have zero or more types disabled by the Payment Manager.
This function returns one of the following values.
| Value | Meaning |
|---|---|
| S_OK | Success |
| E_FAIL | Failure |
HRESULT GetSupportType(
longcIndex// in
BSTR FAR *pRetType// out
);
The GetSupportType function returns the friendly name for a payment type based on the index position. This includes only the enabled types. The friendly name for a type is the string presented to a consumer for identification (for example, “American Express”). Valid values of an index are zero through GetTypeCount minus one.
This function returns one of the following values.
| Value | Meaning |
|---|---|
| S_OK | Success. |
| E_INVALIDARG | One or more of the arguments is invalid. |
| E_OUTOFMEMORY | Out of memory. |
| E_FAIL | Failure. |
HRESULT GetInstanceCount(
long FAR *pcRet// out
);
The GetInstanceCount function returns the total count of instances stored in the CPC, for all of the enabled types. Note that there is no way to check the number of instances of each type other than counting them.
This function returns one of the following values.
| Value | Meaning |
|---|---|
| S_OK | Success |
| E_FAIL | Failure |
HRESULT GetFriendlyName(
longcIndex// in
BSTR FAR *RetName// out
);
The GetFriendlyName function returns the friendly name for an instance based upon index position. Valid values of an index are zero through GetInstanceCount minus one.
This function returns one of the following values.
| Value | Meaning |
|---|---|
| S_OK | Success. |
| E_INVALIDARG | One or more of the arguments is invalid. |
| E_OUTOFMEMORY | Out of memory. |
| E_FAIL | Failure. |
HRESULT GetInstanceType(
longcIndex// in
BSTR FAR *pRetType// out
);
The GetInstanceType function returns the friendly name of an instance’s type based upon the index.
This function returns one of the following values.
| Value | Meaning |
|---|---|
| S_OK | Success. |
| E_INVALIDARG | One or more arguments is invalid. |
| E_OUTOFMEMORY | Out of memory. |
| E_FAIL | Failure. |
HRESULT NewPaymentInstance(
BSTRbstrType// in
long FAR *pcIdx// out
);
The NewPaymentInstance function adds a new instance to the CPC. When this function is called, the Payment Selector provides the appropriate type of the instance and the CPC returns the index position of the new instance.
This function returns one of the following values.
| Value | Meaning |
|---|---|
| E_INVALIDARG | One or more of the arguments is invalid. |
| E_OUTOFMEMORY | Out of memory. |
| E_FAIL | Failure. |
| S_FALSE | Cancel by user. |
| S_OK | Success. |
During add and modify operations, the IWalletCallback::Exists function must be called to verify that no instance with the same friendly name exists across payment modules.
HRESULT DeletePaymentInstance(
BSTRbstrFriendName// in
);
The DeletePaymentInstance function deletes an instance from the CPC.
This function returns one of the following values.
| Value | Meaning |
|---|---|
| E_INVALIDARG | One or more of the arguments is not valid. |
| E_OUTOFMEMORY | Out of memory. |
| E_FAIL | Failure. |
| S_OK | Success. |
HRESULT ManagePaymentInstance(
BSTRbstrFriendName// in
long FAR *pcIdx// out
);
The ManagePaymentInstance function allows the user to modify an instance in the CPC. This function identifies an instance by its friendly name and returns its index position to the caller.
When building the CPC, you may choose not to permit modifications to the friendly name of an instance. Note that IClientPaymentProvider::Exists should be called only when the friendly name has changed. If the friendly name has not changed, then you should not call the Exists function.
This function returns one of the following values.
| Value | Meaning |
|---|---|
| E_VALIDARG | One or more of the arguments is invalid. |
| E_OUTOFMEMORY | Out of memory. |
| E_FAIL | Failure. |
| S_OK | Success. |
| S_FALSE | Cancel by user. |
During add and modify operations, the IWalletCallback::Exists function must be called to verify that no instance with the same friendly name exists across CPCs.
HRESULT GetBitmap(
longcFriendIdx// in
longfType// in
long *hBitMap// out
);
The GetBitmap function returns a bitmap handle based upon an index of an 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. Note that this function will not return an E_OUTOFMEMORY value because bitmaps are created during the Create call (which may return an E_OUTOFMEMORY value).
This function returns one of the following values.
| Value | Meaning |
|---|---|
| E_INVALIDARG | One or more of the arguments is invalid. |
| E_FAIL | Failure. |
| S_OK | Success. |
HRESULT GetTypeBitmap(
BSTRbstrType// in
longfType// in
long *hBitMap// out
);
The GetTypeBitmap function returns a bitmap handle based on a type. 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. Note that this function will not return an E_OUTOFMEMORY value because bitmaps are created during the Create call (which may return an E_OUTOFMEMORY value).
This function returns one of the following values.
| Value | Meaning |
|---|---|
| E_INVALIDARG | One or more of the arguments is invalid. |
| E_FAIL | Failure. |
| S_OK | Success. |
HRESULT Exists(
BSTRbstrFriendName// in
long *plExists// out
);
The Exists function determines whether an instance with the same friendly name as the one being created already exists in the CPC. This function ensures the uniqueness of friendly names (regardless of case) within the CPC.
This function returns one of the following values.
| Value | Meaning |
|---|---|
| E_FAIL | Failure |
| S_OK | Success |
The IWalletCallback::Exists function determines the uniqueness of a friendly name across all CPCs.
HRESULT GetChangeCount(
long *plCount// out
);
The GetChangeCount function allows the Payment Selector to test whether any data in the CPC has been changed. This function returns a change count that is a long integer that increments each time a data change (such as add, delete, or modify) is made. The count signifies to the Payment Selector that the contents of a CPC have been changed.
This function returns one of the following values.
| Value | Meaning |
|---|---|
| E_FAIL | Failure |
| E_OK | Success |
HRESULT IsValid(
BSTRbstrFriendname// in
BSTRbstrAcceptTypes// in
long *plResult// out
);
The IsValid function determines whether the instance is valid given the accepted types string. The Payment Manager calls this function to determine whether the specified instance supports any of the payment types listed in the bstrAcceptTypes string. The IsValid function is used by the user interface to indicate whether an instance of a payment type is accepted at a merchant’s site. Instances that are not accepted at a merchant’s site appear shaded.
This function returns one of the following values.
| Value | Meaning |
|---|---|
| E_FAIL | Failure. |
| E_INVALIDARG | One or more of the arguments is invalid. |
| S_OK | Success. |
The AcceptedTypes payment information property returns the types of credit-card payment that a merchant accepts for payment. The :clear value assigned to accepted credit card names signifies a clear text representation (no encryption).
This payment information property takes as a parameter bstrTypes, which is a string containing a list of name/value pairs. Note in the following example that the type name (Visa, MasterCard, Amex) and the encryption value (clear) are separated by colons:
"Visa:clear;MasterCard:clear;Amex:clear"
HRESULT IsTypeValid(
BSTRbstrType// in
BSTRbstrAcceptTypes// in
long *plResult// out
);
The IsTypeValid function determines whether a type is valid given the accepted types string. This function is used by the user interface to indicate which payment types are accepted at a merchant’s site. Payment types that are not accepted at a merchant’s site appear shaded.
This function returns one of the following values.
| Value | Meaning |
|---|---|
| E_FAIL | Failure. |
| E_INVALIDARG | One or more of the arguments is invalid. |
| S_OK | Success. |
HRESULT GeneratePaymentInformation(
BSTRbstrFriendname// in
BSTRbstrTotal// in
BSTRbstrHashOrder// in
BSTRbstrAcceptTypes// in
SAFEARRAY (VARIANT) *ppsa// out
);
The GeneratePaymentInformation function returns a payment instruction (PI) based upon the instance.
If you are using a third-party CPC, the HTML (or .asp) page needs to handle the fields that the CPC returns from the GeneratePaymentInformation call. To do this, these fields need to be added to the hidden form on your HTML page in order to get posted. You should also add the lines to initialize these form fields to their appropriate values.
When this function is called, a dialog box should be displayed to the consumer warning that a specific instance of a payment type is being charged for a shopping transaction.
This function returns one of the following values.
| Value | Meaning |
|---|---|
| E_FAIL | Failure. |
| E_INVALIDARG | One or more of its arguments is invalid. |
| E_OUTOFMEMORY | Out of memory. |
| S_OK | Success. |
The IWalletCallback interface guarantees the uniqueness of friendly names across all components in the Payment Selector. Friendly names are assigned by the user to each instance of a payment type to distinguish between multiple instances of a payment type. For example, if a user has two Visa credit cards, the first card might have the friendly name Main Visa and the second card Emergency Visa.
The IWalletCallback interface is an IDispatch interface provided for the IClientPaymentProvider::ManagePaymentInstance and the IClientPaymentProvider::NewPaymentInstance functions.
The IWalletCallback interface contains the following methods:
HRESULT Exists(
BSTRbstrFriendName// in
long *plExists// out
);
The Exists function must be called during add (IClientPaymentProvider::NewPaymentInstance) and modify (IClientPaymentProvider::ManagePaymentInstance) operations before an instance can be created or a friendly name modified. This function ensures that the friendly name being added or modified is unique across all components in the Payment Selector. A warning flag will be returned indicating whether the friendly name already exists. If so, this instance must not be created; the user should be prompted to enter a new friendly name.
This function returns one of the following values.
| Value | Meaning |
|---|---|
| S_OK | Success |
| E_FAIL | Failure |
Note that this interface is exposed to the CPC during the IClientPaymentProvider::Create function, which is called before all other functions. Therefore, the CPC must save the interface pointer to use during add and modify operations.
HRESULT GetWindowHandle(
long *hWind// out
);
The GetWindowHandle function returns the window handle of the Payment Selector's window. This handle can be used in calls to Microsoft® Windows® API functions such as MessageBox.
This function returns the following value.
| Value | Meaning |
|---|---|
| S_OK | Success |
The methods in the following interfaces support the installation of the client payment component (CPC) with the Payment Manager:
Use the IPaymentInstall interface to install and uninstall CPCs and additional payment types in the Payment Manager. This top-level install interface consists of the following methods:
HRESULT Install(
longlType// in
IPaymentProviderInstall *ipInst// in
);
Call the Install function to access the IPaymentProviderInstall interface that installs the CPC’s new payment type with the Payment Manager.
This function returns one of the following values.
| Value | Meaning |
|---|---|
| S_OK | Success |
| E_FAIL | Failure |
HRESULT Uninstall(
IPaymentProviderInstall *ipInst// in
);
This method is called when the IPaymentProviderInstall interface uninstalls a payment type. Note that removing a type from an existing CPC is not supported.
This function returns one of the following values.
| Value | Meaning |
|---|---|
| S_OK | Success |
| E_FAIL | Failure |
The IPaymentProviderInstall interface allows you to build an installation package that installs and registers your payment type with the Payment Manager. This interface consists of the following methods:
HRESULT InitInstall(void);
The InitInstall function initializes the installation process for a CPC that will be installed. Note that this is a new CPC to be installed.
None.
This function returns one of the following values.
| Value | Meaning |
|---|---|
| S_OK | Success |
| E_FAIL | Failure |
HRESULT SupportInstall(void);
The SupportInstall function initializes the Payment Manager to support the installation of a new CPC. The Payment Manager queries all existing CPCs to determine the status of their types before installing the new CPC.
Note that IPaymentProviderInstall::InitInstall is called for the new CPC after SupportInstall is called on all existing CPCs. This interface is used both to install new CPCs and to enable or disable payment types in existing CPCs and to support the installation of new CPCs.
None.
This function returns one of the following values.
| Value | Meaning |
|---|---|
| S_OK | Success |
| E_FAIL | Failure |
HRESULT ComponentInfo(
long *plCount// out
BSTR *pbstrName// out
BSTR *pbstrSource// out
BSTR * pbstrProgID// out
);
The ComponentInfo function returns information about the CPC being installed into the Payment Selector.
This function returns one of the following values.
| Value | Meaning |
|---|---|
| S_OK | Success |
| E_FAIL | Failure |
HRESULT GetFullTypeCount(
long *plCount// out, retval
);
The GetFullTypeCount function returns the number of payment types in the CPC. This number does not depend on what payment types are enabled or disabled.
This function returns one of the following values.
| Value | Meaning |
|---|---|
| S_OK | Success |
| E_FAIL | Failure |
HRESULT GetTypeInfo(
long cIndex// in
BSTR *pbstrType// out
long *plActive// out
);
Call the GetTypeInfo function to retrieve information about the status of the payment type in the Payment Selector.
This function returns one of the following values.
| Value | Meaning |
|---|---|
| S_OK | Success |
| E_FAIL | Failure |
HRESULT SetTypeActivity(
BSTRbstrType// in
longlActive// in
longfPersist// in
);
Call the SetTypeActivity function to set the activity status of a payment type within a CPC.
This function returns one of the following values.
| Value | Meaning |
|---|---|
| S_OK | Success |
| E_FAIL | Failure |
HRESULT InstanceCount(
BSTRbstrType// in
long *plCount// out
);
Call the InstanceCount function to count the instances for a payment type in the CPC.
This function returns one of the following values.
| Value | Meaning |
|---|---|
| S_OK | Success |
| E_FAIL | Failure |
HRESULT Install(void);
Call the Install function to install the CPC into the Payment Selector. This requires the CPC to save its state information.
None.
This function returns one of the following values.
| Value | Meaning |
|---|---|
| S_OK | Success |
| E_FAIL | Failure |
HRESULT Uninstall(void);
Call the Uninstall function to uninstall the CPC from the Payment Selector. This function is called from the Payment Manager when the CPC is uninstalled.
None.
This function returns one of the following values.
| Value | Meaning |
|---|---|
| S_OK | Success |
| E_FAIL | Failure |
HRESULT SelfUninstall(void);
The CPC calls the SelfUninstall function to remove the CPC DLL from the Payment Selector. This function is called from the CPC DLL during the unregister process.
None.
This function returns one of the following values.
| Value | Meaning |
|---|---|
| S_OK | Success |
| E_FAIL | Failure |