PaymentMethod.validate

The validate method validates a PaymentMethod object. You call this method on an appropriately populated PaymentMethod object. The validation process varies according to the payment method type. See the PaymentMethod.update method for the validation process in the context of the validate parameter being passed to the update() call.

This call only validates the PaymentMethod object but does not create, update, or store the data in CashBox. To create or update the data, call update() on the object after validation.

This method considers the Luhn check, the authorization return, and the (merchant defined) active AVS and CVN policy when formulating the validated result.

For more detail on AVS and CVN Return Codes, please work with your Vindicia Client Services representative.

Input

srd: sparse response description, a SOAP string (which must be a JSON object), in which you specify the elements you want returned.This parameter enables the calling system to constrain a method call to return only components you specify. This gives you greater control over returned content, and improves response time within the Vindicia platform by reducing the processing needed for the call.

Some fields are required, either practically or in the WSDL, and will be returned regardless of the srd. A null srd returns the complete response.

paymentMethod: the PaymentMethod to validate.

sourceIp: the customer IP address from which the customer specified details for this payment method. It must be specified if CashBox is to evaluate risk score for this payment method, that is, if you specify minChargebackProbability to be less than 100.

minChargebackProbability: a number between 0 and 100 by which you specify your fraud risk score tolerance level. A probability of 100 indicates that CashBox is 100% certain that a transaction is fraudulent and will result in a chargeback. Specify your acceptable threshold for chargeback possibility with this parameter. If the score evaluates to be more than your tolerance level, CashBox will not validate the payment method with your payment processor, saving you the cost of obtaining validation for potentially fraudulent payment methods.

For risk score evaluation, you must specify the sourceIp parameter, described below, and the full billing address containing city, state (district), and country for the payment method.

ignoreAvsPolicy: a Boolean flag that, if set to true, will override the AVS policy, and update the paymentMethod, regardless of the AVS return code. If set to false or null, (and if validatePaymentMethod is set to true) the AVS return code will be used to determine whether to update the paymentMethod.

ignoreCvnPolicy: an optional Boolean flag that, if set to true, will override the CVN policy, and update the paymentMethod, regardless of the CVN return code. If set to false or null, (and if validatePaymentMethod is set to true) the CVN return code will be used to determine whether to update the paymentMethod.

Output

return: an object of type Return that indicates the success or failure of the call.

authStatus: a TransactionStatus object containing information received from the payment processor for the underlying validation transaction processed by your payment processor. If you have enabled risk scoring and if the score evaluates to be more than your tolerance threshold specified in the minChargebackProbability input parameter, CashBox will not populate this output parameter.

validated: a Boolean flag that, if set to true, indicates that this method has successfully validated the PaymentMethod object. A false setting indicates that the validation failed.

avsCvnPolicyEvaluationDetails: an object of type AvsCvnPolicyStatus, and contains two fields, returnCode and returnString, which pertain to the outcome of the AVS/CVN policy evaluation.

Note All other methods affected by the AVS/CVN policy return their returnCode and returnString in the Return object from the method.)

score: the fraud risk score evaluated by CashBox for this payment method. If you specified minChargebackProbability of less than 100, CashBox will evaluate the risk score for this payment method.

scoreCodes: an array of code numbers and corresponding explanatory text that explains the score evaluated by CashBox

Returns

In addition to those listed in Standard Return Codes, this call returns:

Return Code	Return String
201	VS/CVN policy not evaluated. Returned to indicate that the AutoBill was created, but the AVS policy was not evaluated, due to a lack of response from the Payment Processor.
400	One of the following: Invalid parameters: error-description. Error-description. Returned if CashBox encounters a general error while mapping the object to a CashBox database object.
407	AVS policy evaluation failed.
408	CVN policy evaluation failed.
409	AVS and CVN policy evaluations failed.
410	AVS and CVN policy evaluations could not be performed.
501	Validation not implemented for payment-method-type accounts.

Example

// To validate a credit card based payment method
// Create a payment method object to make the call

$paymentMethod = new PaymentMethod();

$paymentMethod->setType('CreditCard');
$paymentMethod->setAccountHolderName('Jane Doe');
$paymentMethod->setCustomerSpecifiedType('Visa');
$paymentMethod->setCurrency('USD');
$paymentMethod->setActive(true);

$cc = new CreditCard();
$cc->setAccount('411111111111111');
$cc->setExpirationDate('201208');

$paymentMethod->setCreditCard($cc);

// customer's ip address not necessary since we
// do not want to do risk scoring

$sourceIp = null;

// risk score threshold set to 100 since we
// do not want to do risk scoring

$minChargebackProbability = 100;

$response =

$paymentMethod->validate($sourceIp, $minChargebackProbability);

if($response['returnCode'] == 200) {

if($response['validated']) {

print('Payment method is valid');

// get AVS code

$txStatus = $response['authStatus'];
$avsCode = $txStatus->creditCardStatus->avsCode;

// examine AVS return code here

}
else {

print('Payment method is invalid');

}

}

else {

print('Error encountered during validation');

}