CreditCardProcessor Class Reference

This is a generic class that defines the interface between xTuple ERP and credit card processing services. More...

#include <creditcardprocessor.h>

Public Member Functions
virtual	~CreditCardProcessor ()
virtual int	authorize (const int pccardid, const int pcvv, const double pamount, double ptax, bool ptaxexempt, double pfreight, double pduty, const int pcurrid, QString &pneworder, QString &preforder, int &pccpayid, QString preftype, int &prefid)
	Processes pre-authorization transactions.
virtual int	charge (const int, const int, const double, const double, const bool, const double, const double, const int, QString &, QString &, int &, QString, int &)
	Processes charge transactions.
virtual int	chargePreauthorized (const int, const double, const int, QString &, QString &, int &)
	Processes 'capture' transactions, or charges against a prior preauthorization.
virtual int	credit (const int, const int, const double, const double ptax, const bool ptaxexempt, const double pfreight, const double pduty, const int, QString &, QString &, int &, QString, int &)
	Processes credit transactions.
virtual Q_INVOKABLE int	defaultPort (bool=false)
	Return the default port expected by the subclass.
virtual Q_INVOKABLE QString	defaultServer ()
	Return the default server expected by the subclass.
virtual Q_INVOKABLE bool	handlesChecks ()
	Returns whether the subclass handles checks.
virtual Q_INVOKABLE bool	handlesCreditCards ()
	Returns whether the subclass handles credit cards.
virtual Q_INVOKABLE bool	isLive ()
	Returns whether credit card processing is configured in live mode.
virtual Q_INVOKABLE bool	isTest ()
	Returns whether credit card processing is configured in test mode.
virtual Q_INVOKABLE void	reset ()
	Reset error handling internal settings so previous transactions don't interfere with new transactions.
virtual Q_INVOKABLE int	testConfiguration ()
	Test whether common credit card processing configuration options are consistent.
virtual int	voidPrevious (int &)
	Processes void transactions.
Static Public Member Functions
static Q_INVOKABLE ParameterList	authorize (const ParameterList &)
	Processes pre-authorization transactions.
static Q_INVOKABLE ParameterList	charge (const ParameterList &)
	Processes charge transactions.
static Q_INVOKABLE ParameterList	chargePreauthorized (const ParameterList &)
	Captures preauthorized transactions.
static Q_INVOKABLE ParameterList	credit (const ParameterList &)
	Processes credit transactions.
static Q_INVOKABLE QString	errorMsg (const int)
	Returns the error message associated with the given pcode.
static Q_INVOKABLE QString	errorMsg ()
	Returns the most recent error message set by CreditCardProcessor or one of its subclasses.
static Q_INVOKABLE CreditCardProcessor *	getProcessor (const QString=QString())
	Get a new instance of a specific CreditCardProcessor subclass.
static Q_INVOKABLE int	printReceipt (const int)
	Print the CCReceipt report for a credit card transaction.
static Q_INVOKABLE ParameterList	voidPrevious (const ParameterList &)
	Processes void transactions.
Protected Attributes
int	_defaultLivePort
QString	_defaultLiveServer
int	_defaultTestPort
QString	_defaultTestServer
QList< QPair< QString, QString > >	_extraHeaders
QHttp *	_http
bool	_passedAvs
bool	_passedCvv
QString	_plogin
QString	_ppassword
QString	_pport
QString	_pserver
Protected Member Functions
	CreditCardProcessor ()
	Construct and initialize a default CreditCardProcessor.
virtual QString	buildURL (const QString, const QString, const bool)
	Construct a valid URL from the information in the configuration.
virtual int	checkCreditCard (const int, const int, QString &)
	Check if the given credit card is consistent and active.
virtual int	checkCreditCardProcessor ()
virtual int	doAuthorize (const int, const int, const double, const double, const bool, const double, const double, const int, QString &, QString &, int &, ParameterList &)
	Placeholder for subclasses to override.
virtual int	doCharge (const int, const int, const double, const double, const bool, const double, const double, const int, QString &, QString &, int &, ParameterList &)
	Placeholder for subclasses to override.
virtual int	doChargePreauthorized (const int, const int, const double, const int, QString &, QString &, int &, ParameterList &)
	Placeholder for subclasses to override.
virtual int	doCredit (const int, const int, const double, const double, const bool, const double, const double, const int, QString &, QString &, int &, ParameterList &)
	Placeholder for subclasses to override.
virtual int	doTestConfiguration ()
	Placeholder for subclasses to override.
virtual int	doVoidPrevious (const int, const int, const double, const int, QString &, QString &, QString &, int &, ParameterList &)
	Placeholder for subclasses to override.
virtual int	fraudChecks ()
	Handle fraud checking as determined by the system configuration.
virtual int	sendViaHTTP (const QString &, QString &)
	Send an HTTP request to the configured credit card service and wait for its response.
virtual int	updateCCPay (int &, ParameterList &)
	Insert into or update the ccpay table based on parameters extracted from the credit card processing service' response to a transaction request.
Static Protected Member Functions
static double	currToCurr (const int, const int, const double, int *=0)
	Convert between two currencies.
Static Protected Attributes
static QString	_errorMsg = ""
static QHash< int, QString >	_msgHash

Detailed Description

This is a generic class that defines the interface between xTuple ERP and credit card processing services.

CreditCardProcessor encapsulates the common functionality shared across different services, including interaction with the database server and the proper stored procedures to call.

It should be subclassed once for each credit card processing company to be supported. Subclasses should override the following methods:

doAuthorize
doCharge
doChargePreauthorized
doCredit
doVoidPrevious
doTestConfiguration

Subclasses should also set

_defaultLiveServer
_defaultTestServer
_defaultLivePort
_defaultTestPort

It is the subclass' responsibility to ensure that all of the configuration options available on the Credit Card Configuration window are implemented either here or in the subclass. An example of an option that must be implemented in each subclass is CCTestResult since the method for requesting error responses from the credit card processing service is different for every service.

In addition to subclassing CreditCardProcessor, alternate credit card processing services require changing CreditCardProcessor::getProcessor and configureCC. CreditCardProcessor::getProcessor must be modified to instantiate the right subclass of CreditCardProcessor based on the CCCompany metric or its QString argument. configureCC must be modified to allow editing and saving service-specific metrics and to store the service-specific CCCompany value checked by getProcessor.

Error handling:

The following rules are followed by CreditCardProcessor, which also expects its subclasses to follow them. It is the subclass' responsibility to follow these conventions. If they are not followed, the database will not represent what really happened and the user will not be informed of problems.

Each method in CreditCardProcessor and its subclasses involved in processing credit card transactions is expected to return an integer conforming to the following pattern and set _errorMsg to the string associated with this integer in the _msgHash:

If the function returns:	It means this:
greater than 0	The interaction with the credit card processing service was successful but either there is a warning from the service, like the credit card processing company denied the transaction, or local post-processing generated an error, such as a database failure
0	the transaction succeeded in its entirety
less than 0	preprocessing failed or the credit card company returned an error, like a malformed message or communications could not be established to process the transaction

Error codes between -100 and 100 inclusive are reserved for the CreditCardProcessor class itself. Values less than -100 or greater than 100 are available for use by subclasses and should be loaded into _msgHash in the subclass' constructor.

See also:: AuthorizeDotNetProcessor; ExternalCCProcessor; YourPayProcessor; PaymentechProcessor; configureCC

Todo:: figure out how to expose portions of this in the scriptapi doxygen module

Constructor & Destructor Documentation

CreditCardProcessor::~CreditCardProcessor ( ) [virtual]

CreditCardProcessor::CreditCardProcessor ( ) [protected]

Construct and initialize a default CreditCardProcessor.

This should never be called except by the constructor of a subclass. This should always be called by the constructor of a subclass. This constructor initializes _msgHash as well as some private and protected fields.

Member Function Documentation

ParameterList CreditCardProcessor::authorize ( const ParameterList & pinput ) [static]

Processes pre-authorization transactions.

This version of authorize is intended for use by scripts. Instead of passing all of the arguments in order, this method allows creating a QtScript object and setting properties on this object by name. Then the script can pass this object to authorize(const int pccardid, const int pcvv, const double pamount, double ptax, bool ptaxexempt, double pfreight, double pduty, const int pcurrid, QString &pneworder, QString &preforder, int &pccpayid, QString preftype, int &prefid):

      var params = new Object;
      params.ccard_id = _ccardid;
      params.cvv      = _cvv.text;
      ...
      var processor = toolbox.getProcessor();
      var result = processor.authorize(params);

      if (result.returnVal < 0)
        // handle errors
      else if (result.returnVal > 0)
        // handle warnings
      ...

Parameters:

pinput

The parameter list to unpack and use to call authorize

Returns:: A parameter list containing the output parameters, plus one called returnVal holding the return value of authorize

int CreditCardProcessor::authorize	(	const int	pccardid,
		const int	pcvv,
		const double	pamount,
		double	ptax,
		bool	ptaxexempt,
		double	pfreight,
		double	pduty,
		const int	pcurrid,
		QString &	pneworder,
		QString &	preforder,
		int &	pccpayid,
		QString	preftype,
		int &	prefid
	)			`[virtual]`

Processes pre-authorization transactions.

This method performs application-level error checking and all of the database work required to handle a pre-authorization transaction. It calls doAuthorize to handle the direct communication with the service.

Warning:: This method should never be overridden. Service-specific functionality should be implemented in the doAuthorize method of the service' subclass.

Parameters:

`[in]`	pccardid	The internal id of the credit card to preauthorize
`[in]`	pcvv	The CVV/CCV code of the credit card to preauthorize
`[in]`	pamount	The total amount to preauthorize
`[in]`	ptax	The subportion of the total which is tax
`[in]`	ptaxexempt	Whether or not this transaction is tax exempt
`[in]`	pfreight	The subportion of the total which is freight
`[in]`	pduty	The subportion of the total which is customs duty
`[in]`	pcurrid	The currency of the amount to preauthorize
`[in,out]`	pneworder	The order number associated with this preauthorization
`[out]`	preforder	The reference number associated with this preauthorization (may be required to 'capture' the preauthorization)
`[out]`	pccpayid	The ccpay_id of the record created by this transaction
`[in]`	preftype	Either `cohead` or `cashrcpt` or blank
`[in,out]`	prefid	The cashrcpt_id or cohead_id associated with this transaction

Returns:: An index into _errMsg; 0 indicates success

QString CreditCardProcessor::buildURL	(	const QString	pserver,
		const QString	pport,
		const bool	pinclport
	)			`[protected, virtual]`

Construct a valid URL from the information in the configuration.

Handle the case where someone leaves off a piece of the URL when entering the basic configuration. Note that a lot of people are used to typing in web browsers, which fill in some parts for them.

If the user did not enter values for the server or the port on the configuration, use the defaults provided by the service' subclass.

Parameters:

	pserver	Use this server, or the defaultServer if blank
	pport	Use this port, or the defaultPort if blank
	pinclport	Flag whether the port should be part of the constructed URL or not

See also:: defaultServer; defaultPort

ParameterList CreditCardProcessor::charge ( const ParameterList & pinput ) [static]

Processes charge transactions.

This version of charge is intended for use by scripts. Instead of passing all of the arguments in order, this method allows creating a QtScript object and setting properties on this object by name. Then the script can pass this object to charge.

Parameters:

pinput

The parameter list to unpack and use to call charge

Returns:: A parameter list containing the output parameters, plus one called returnVal holding the return value of charge

See also:: authorize(const ParameterList &pinput)

int CreditCardProcessor::charge	(	const int	pccardid,
		const int	pcvv,
		const double	pamount,
		const double	ptax,
		const bool	ptaxexempt,
		const double	pfreight,
		const double	pduty,
		const int	pcurrid,
		QString &	pneworder,
		QString &	preforder,
		int &	pccpayid,
		QString	preftype,
		int &	prefid
	)			`[virtual]`

Processes charge transactions.

This method performs application-level error checking and all of the database work required to handle a credit card charge transaction. It calls doCharge to handle the direct communication with the service.

Warning:: This method should never be overridden. Service-specific functionality should be implemented in the doCharge method of the service' subclass.

Parameters:

`[in]`	pccardid	The internal id of the credit card to charge
`[in]`	pcvv	The CVV/CCV code of the credit card to charge
`[in]`	pamount	The total amount to charge
`[in]`	ptax	The subportion of the total which is tax
`[in]`	ptaxexempt	Whether or not this transaction is tax exempt
`[in]`	pfreight	The subportion of the total which is freight
`[in]`	pduty	The subportion of the total which is customs duty
`[in]`	pcurrid	The currency of the amount to charge
`[in,out]`	pneworder	The order number associated with this charge
`[out]`	preforder	The reference number associated with this charge
`[out]`	pccpayid	The ccpay_id of the record created by this transaction
`[in]`	preftype	Either `cohead` or `cashrcpt` or blank
`[in,out]`	prefid	The cashrcpt_id or cohead_id associated with this transaction

Returns:: An index into _errMsg; 0 indicates success

ParameterList CreditCardProcessor::chargePreauthorized ( const ParameterList & pinput ) [static]

Captures preauthorized transactions.

This version of chargePreauthorized is intended for use by scripts. Instead of passing all of the arguments in order, this method allows creating a QtScript object and setting properties on this object by name. Then the script can pass this object to chargePreauthorized.

Parameters:

pinput

The parameter list to unpack and use to call chargePreauthorized

Returns:: A parameter list containing the output parameters, plus one called returnVal holding the return value of chargePreauthorized

See also:: authorize(const ParameterList &pinput)

int CreditCardProcessor::chargePreauthorized	(	const int	pcvv,
		const double	pamount,
		const int	pcurrid,
		QString &	pneworder,
		QString &	preforder,
		int &	pccpayid
	)			`[virtual]`

Processes 'capture' transactions, or charges against a prior preauthorization.

This method performs application-level error checking and all of the database work required to 'capture' or complete the charge against a prior preauthorization. It calls doChargePreauthorized to handle the direct communication with the service.

Warning:: This method should never be overridden. Service-specific functionality should be implemented in the doChargePreauthorized method of the service' subclass.

Parameters:

`[in]`	pcvv	The CVV/CCV code of the credit card to charge
`[in]`	pamount	The total amount to charge
`[in]`	pcurrid	The currency of the amount to charge
`[in,out]`	pneworder	The order number associated with this charge
`[in,out]`	preforder	The reference number (preforder) generated by the preauthorization transaction
`[in,out]`	pccpayid	When calling the method, pccpayid should be the ccpay_id of the preauthorization record. On return, this is the ccpay_id of the charge record, which may be the same as the preauthorization record.

Returns:: An index into _errMsg; 0 indicates success

int CreditCardProcessor::checkCreditCard	(	const int	pccid,
		const int	pcvv,
		QString &	pccard_x
	)			`[protected, virtual]`

Check if the given credit card is consistent and active.

This consistency check is used in a number of places before executing a credit card transaction. It confirms that the given card is marked as active in the system and has not expired. If the card has expired based on the expiration month and year, then it is marked as expired in the database. It also makes sure that the CVV has been entered if the system is configured to require it.

Parameters:

	pccid	The ccard_id of the credit card to check
	pcvv	The CVV from the card holder, -1 if not known, -2 if the caller knows it is not required or available (such as for void transactions).
`[out]`	pccard_x	The credit card number, with most of the digits replaced with `X`. Used for reporting errors.

virtual int CreditCardProcessor::checkCreditCardProcessor ( ) [inline, protected, virtual]

ParameterList CreditCardProcessor::credit ( const ParameterList & pinput ) [static]

Processes credit transactions.

This version of credit is intended for use by scripts. Instead of passing all of the arguments in order, this method allows creating a QtScript object and setting properties on this object by name. Then the script can pass this object to credit.

Parameters:

pinput

The parameter list to unpack and use to call credit

Returns:: A parameter list containing the output parameters, plus one called returnVal holding the return value of credit

See also:: authorize(const ParameterList &pinput)

int CreditCardProcessor::credit	(	const int	pccardid,
		const int	pcvv,
		const double	pamount,
		const double	ptax,
		const bool	ptaxexempt,
		const double	pfreight,
		const double	pduty,
		const int	pcurrid,
		QString &	pneworder,
		QString &	preforder,
		int &	pccpayid,
		QString	preftype,
		int &	prefid
	)			`[virtual]`

Processes credit transactions.

This method performs application-level error checking and all of the database work required to credit a prior charge. It calls doCredit to handle the direct communication with the service.

Warning:: This method should never be overridden. Service-specific functionality should be implemented in the doCredit method of the service' subclass.

Parameters:

`[in]`	pccardid	The internal id of the credit card to credit
`[in]`	pcvv	The CVV/CCV code of the credit card to credit
`[in]`	pamount	The total amount to credit
`[in]`	ptax	The subportion of the total which is tax
`[in]`	ptaxexempt	Whether or not this transaction is tax exempt
`[in]`	pfreight	The subportion of the total which is freight
`[in]`	pduty	The subportion of the total which is customs duty
`[in]`	pcurrid	The currency of the amount to credit
`[in,out]`	pneworder	The order number associated with this credit
`[in,out]`	preforder	The reference number (preforder) generated by the charge transaction
`[in,out]`	pccpayid	When calling the method, pccpayid should be the ccpay_id of the original charge record. On return, this is the ccpay_id of the credit record.
`[in]`	preftype	Either `cohead` or `cashrcpt` or blank
`[in,out]`	prefid	The cashrcpt_id or cohead_id associated with this transaction

Returns:: An index into _errMsg; 0 indicates success

double CreditCardProcessor::currToCurr	(	const int	pfrom,
		const int	pto,
		const double	pamount,
		int *	perror = `0`
	)			`[static, protected]`

Convert between two currencies.

This is slightly different than the version in the CurrDisplay widget because credit card processing has special error reporting needs.

Parameters:

	pfrom	The source currency
	pto	The destination currency
	pamount	The value of the transaction in the source currency
`[out]`	perror	The CreditCardProcessor error code for a failed conversion

Returns:: The value of the transaction in the destination currency

int CreditCardProcessor::defaultPort ( bool ptestmode = false ) [virtual]

Return the default port expected by the subclass.

This can differ depending on whether running in live or test mode. It is the subclass' responsibility to set both default ports.

QString CreditCardProcessor::defaultServer ( ) [virtual]

Return the default server expected by the subclass.

This can differ depending on whether running in live or test mode. It is the subclass' responsibility to set both default servers.

int CreditCardProcessor::doAuthorize	(	const int	pccardid,
		const int	pcvv,
		const double	pamount,
		const double	ptax,
		const bool	ptaxexempt,
		const double	pfreight,
		const double	pduty,
		const int	pcurrid,
		QString &	pneworder,
		QString &	preforder,
		int &	pccpayid,
		ParameterList &
	)			`[protected, virtual]`