Skip to main content
Vindicia Knowledge Center

PaymentMethod.update

PaymentMethod.update

PaymentMethod.update

The update method creates or updates a PaymentMethod object. To encapsulate a specific payment method for a customer, you must specify the payment type in the object’s type attribute, and then populate the payment details (specific to the payment type) in a PaymentMethodType-specific subobject. For example, if you set type to PayPal, construct a PayPal object and set it in the PaymentMethod object’s PayPal attribute.

Note The customer’s Account must exist before any Hosted Page related call references that Account.

This call supports a flag that may be set to validate the payment method. CashBox uses either $0 or $1 (or other currency) for the amount, depending on the payment method type, credit card type, and payment processor for the validation transaction. If the validation amount is not $0, CashBox might later void this transaction.

Note CashBox does not support validation for PayPal or Merchant Accepted payment method types.

In case of the credit-card payment method, you can screen the card for fraud risk when creating the PaymentMethod object by specifying a chargeback probability score (also called risk score) that is acceptable to you. CashBox scores the payment method for fraud risk by examining the billing address, the BIN (the first six digits of the card’s account number), the previous chargebacks on transactions conducted with this card, and other criteria. For details, see the Transaction.score method. If CashBox evaluates the risk score for the payment method to be higher than your acceptable score, the creation process fails.

If validate is set to true and validation fails, the PaymentMethod object is not created or updated.

The following table describes the validation process for the various payment methods.

Payment Method Type

Validation Process

Amazon

Amazon Payments methods are automatically validated upon creation/update in CashBox. If you specify Amazon as the Payment Method while creating an AutoBill object, CashBox and Amazon require that the customer agree to the recurring billing on the merchant’s site (using the Amazon-provided widgets or API). Regardless of the specified update/validate parameter, the system confirms the Amazon status for the underlying payment method selected by the customer. Where enabled for you by Amazon, a full Address Verification Response is available. It is provided by Amazon's latest value for the selected underlying payment method. Amazon does not currently provide for on-demand validation later.

Note After initial approval, an existing Billing Agreement can be used for any charges against that customer, one-time or recurring, as long as it is within the established monthly limits (with Amazon). No further validation or approval is required.

Credit card

The account number must meet the Luhn check criterion and the payment processor must authorize a transaction for a small amount (one currency unit or, if the currency is not specified on the PaymentMethod object, US$1). CashBox sends this transaction to the payment processor for authorization only and does not capture it so the customer is not charged. These transactions, whose success status is AuthorizedForValidation, are displayed on the CashBox Portal.

Direct debit

First, CashBox internally validates the account number (account) and bank sort code (bankSortCode). The rules that apply depend on the country specified in the DirectDebit object. If internal validation succeeds, CashBox contacts the payment processor (currently, Chase Paymentech only) and conducts an auth operation, with no capture, on a transaction that uses the EDD payment method for a small amount, such as one unit of the currency specified on the PaymentMethod object.

The payment processor’s initial response to the auth call is based on the verification that the account number and the bank sort code do not match any numbers in the negative file (blacklist) maintained by the processor. In that case, CashBox considers the payment method valid.

Electronic check (ECP)

CashBox supports ECP if your payment processor is Chase Paymentech or Litle.

For Chase, CashBox validates the ECP payment method by sending the LO verification code to Chase Paymentech, which verifies that the bank-account and routing numbers are valid and that they are not in Chase Paymentech’s negative file.

(You may also perform a VO validation, which is more costly and involves more thorough checks. Work with Vindicia Client Services to add it to your CashBox configuration.)

For Litle, ECP (Litle “eCheck”) data will be validated (verifying that the routing number is correctly formatted and that it exists in the Fed database) by CashBox. For auth and authCapture requests (whether performed directly by the merchant, or automatically by the CashBox rebilling system) an additional verification procedure is performed. This verification compares the ECP account information against a 3rd party database to determine if the account is associated with activities such as fraud, over drafts, or other items determined to be risk factors. If this verification procedure returns negative information, the auth or authCapture request will be rejected.

Merchant Accepted

CashBox does not validate Merchant Accepted payments.

PayPal

The PaymentMethod object methods do not support validation for PayPal. Instead, if you specify PayPal as the payment method while creating an AutoBill object, CashBox authorizes a transaction for a small amount (US $1 if the currency is USD). Such an authorization requires that the customer log in to his or her account on the PayPal site and agree to the terms and conditions of recurring billing (reference transaction). That process serves as validation of the PayPal payment method.

Token

Validation of the token payment method can occur only if that method is associated with an Account object. In that case, CashBox validates by ensuring that the token type (ID) has been previously defined and added to the Account object.

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 object to create or update. In case of an update, you can identify this object with either its VID or your payment method ID (merchantPaymentMethodId).

validate: a Boolean flag that, if set to true, causes this method to validate the PaymentMethod object first before creating or updating.

When validate is true, the AVS and CVN policies (or, in their absence, the default evaluation policy) are used to determine the status of the validation. If validation fails, the PaymentMethod is not updated. For more detail on AVS and CVN Return Codes, please work with your Vindicia Client Services representative.

minChargebackProbability: a number between 0 and 100 by which you specify your fraud risk score tolerance level. A chargeback probability (also called the risk-screening score or risk score) 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, the update call will fail.

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

replaceOnAllAutoBills: a Boolean flag that, if set to true, causes this method to propagate the updates to an existing payment method to all the AutoBill objects. This operation works only for those payment methods that are already associated with an Account object. The default is false, meaning that this method does not update any AutoBill objects.

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

replaceOnAllChildAutoBills: a Boolean flag that, if set to true, the update will propagate to the AutoBills belonging to children of this account. If replaceOnAllAutoBills is set to false, this flag is ignored. If replaceOnAllAutoBills is set to true and replaceOnAllChildAutoBills is set to true, this will affect only the parent account.

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 validate 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 validate 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.

paymentMethod: the PaymentMethod object that was created or updated. If the object was newly created, this output contains the object’s Vindicia-assigned ID in the VID attribute. CashBox masks the account numbers in this object.

created: a Boolean flag that, if set to true, indicates that this method has created a new PaymentMethod object. A false setting indicates that update has updated an existing PaymentMethod object, which occurs if a PaymentMethod object with the merchantPaymentMethodId or VID value specified in the input already exists in the Vindicia database.

validated: a Boolean flag that, if set to true, indicates that the update method has successfully validated the underlying payment method. This is meaningful only if you turned the input validate flag on.

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

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

authStatus: a TransactionStatus object containing information received from the payment processor for the underlying validation transaction. This is available only if you chose to validate the payment method.

Returns

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

Return Code

Return String

261

All active AutoBills were updated. AutoBills which are both expired and Suspended cannot be updated.

400

One of the following:

  • Error-description. (Returned if CashBox cannot map aPaymentMethod object that is passed into a database record.)
  • Data validation error Failed to create Payment-Type-Specific Payment Record: Credit Card conversion failed: Credit Card failed Luhn check.
  • Unable to save payment method: error-description.

402

Unable to authorize card.

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

Error-description.

Example

// To create a credit card based payment method and validate it.
// 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);

// not setting merchantPaymentMethodId. We can use the
// VID returned after creation as unique id for the payment method

$validate = true;
$minChargebackProbability = 100; // not evaluating risk score
$replaceOnAutoBills = false; // just creating the payment method, not

// attached to an account yet

$ip = null; // not evaluating risk score
$response = $paymentMethod->update($validate,

$minChargebackProbability,
$replaceOnAutoBills, $ip);

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

$retPm = $response['data']->paymentMethod;
print('Payment method successfully created with VID'

. $retPm->getVID());

}

else if($response['returnCode'] == 402) {

print('Payment method is invalid');

}

// check response from the payment processor

$validationTxStatus = $response['authStatus'];
if ($validationTxStatus != null) {

$creditCardStatus =

$validationTxStatus->getCreditCardStatus();

if ($creditCardStatus != null) {

$authCode = $creditCardStatus->getAuthCode();
$avsCode = $creditCardStatus->getAuthCode();
print "Card rejected with code " . $authCode . "\n";
print "Address verification code " . $avsCode . "\n";

}

}

For Users

Learn More
For Users

Cashbox Features

Learn More
Cashbox Features
Back to Top