PaymentMethod.validate
Web Session Object
Transaction Object
Token Object
Season Set Object
Refund Object
RatePlan Object
Product Object
Payment Provider Object
Payment Method Object
NameValuePair Object
GiftCard Object
Entitlement Object
Chargeback Object
Campaign Object
BillingPlan Object
AutoBill Object
Address Object
Activity Object
Account Object
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 Vindicia Subscribe. 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 Vindicia Subscribe 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 Vindicia Subscribe 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, Vindicia Subscribe 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 validateForFuturePayment 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 validateForFuturePayment 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, Vindicia Subscribe 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 Vindicia Subscribe for this payment method. If you specified minChargebackProbability of less than 100, Vindicia Subscribe 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 Vindicia Subscribe
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:
Returned if Vindicia Subscribe encounters a general error while mapping the object to a Vindicia Subscribe 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');
}
For Users
Learn More