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. Subscribe 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, Subscribe might later void this transaction. Note: Subscribe 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. Subscribe 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 Subscribe 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 Subscribe. If you specify Amazon as the Payment Method while creating an AutoBill object, Subscribe 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). Subscribe 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 icrn the Subscribe Portal.
Direct debit	First, Subscribe 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, Subscribe 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, Subscribe considers the payment method valid.
Electronic check (ECP)	Subscribe supports ECP if your payment processor is Chase Paymentech or Litle. For Chase, Subscribe 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 Subscribe 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 Subscribe. For `auth` and `authCapture` requests (whether performed directly by the merchant, or automatically by the Subscribe 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	Subscribe 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, Subscribe 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, Subscribe 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 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, 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 Subscribe 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. enable3ds: Disable 3DS authentication flow for this transaction if false; if true or undefined, the 3DS authentication flow will be determined by the merchant option flag use3ds.

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. Subscribe 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 Subscribe for this payment method. If you specified minChargebackProbability of less than 100, Subscribe 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 Subscribe. 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. initialTransaction: Validation Transaction.

Returns

In addition to those listed in The Return Object, 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 Subscribe cannot map a `PaymentMethod` 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.` - `This Credit Card already exists—Policy Violation" (eradicate the newly created but failed one or ensure it is set INACTIVE).` You receive this error message when you have the Credit_Card_Constraints merchant option enabled on your site. This message means that someone is attempting to use a credit card that is already being used as the payment method on an existing account. This is not allowed.
`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";   
   }
}

Parent topic:PaymentMethod Methods

Home

Guides

APIs

Input

Output

Returns

Example

​Input

​Output

​Returns

​Example

Input

Output

Returns

Example