Skip to main content
Vindicia Knowledge Center

Account.updatePaymentMethod

Account.updatePaymentMethod

Account.updatePaymentMethod

The updatePaymentMethod method updates the Account object with the information for a payment method, such as a credit card that is on record. For example, call this method to change a credit card’s expiration date. This method is especially useful if the Account object has associated active AutoBill objects and you would like to replace their payment methods with another one to apply to the next billing.

Call this method to catch up on the billing of an AutoBill object that has stalled due to a failed billing. For example, when your customers receive an email notification about a hard failure of a subscription (AutoBill), they are usually directed to your site to take remedial action (for example, to update the payment method), which, in turn, should invoke this method to send the updated payment method information to Vindicia.

If both ignoreAvsPolicy and ignoreCvnPolicy are true, no policy evaluation will be done. If only one of those flags is set to true, policy evaluation will not be considered for that element (AVS or CVN). If no value is passed in for either parameter, they will default to false, and the AVS and CVN policy evaluations will be used to determine PaymentMethod validation status.

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.

account: the Account object whose payment method you would like to change. Use the merchantAccountId or VID to identify the object.

paymentMethod: the required PaymentMethod object that contains the new data to apply to the Account object’s payment method. (For more information, see The PaymentMethod Object.)

  • If you specify a VID or merchantPaymentMethodId to identify paymentMethod, this method updates the payment method in question. If you do not specify a VID or merchantPaymentMethodId, this method creates a new payment method, and attaches it to the Account object.
  • If you specify an existing sort order for the payment method (for example, 0, which is the default), updatePaymentMethod pushes down the payment method with the same sort order to the next increment (for example, 1), and increments the sort order of the subsequent payment methods accordingly.

updateScopeOnAccount: enumerated options controlling whether and when to bill and/orreplace the paymentMethod on associated AutoBills belonging to the specified Account. If you do not specify a value,  updateScopeOnAccount defaults to the equivalent of the matchingPaymentMethod option, as defined below.

Use the following enumerated values to specify which AutoBills to catch-up billing on, and on which AutoBills you want to replace the payment method. 

  • None—Do not bill on any AutoBills for this/these Accounts. Do not replace the paymentMethod on this/these Account(s).
  • matchingPaymentMethod—Bill only on those ready AutoBills whose payment method matches the default payment method on the specified Account. Replace the payment method only on those AutoBills whose payment method matches the default payment method on the specified Account.
  • AllDue—Bill all (account and children) AutoBills with payment methods belonging to the specified Account that are in error or ready to bill. The payment method is replaced on those billed.
  • AllDueAndMatching—Bill all (Account and children) AutoBills with payment method belonging to the specified Account that are in error or ready to bill. The payment method is replaced on those billed, as well as on any AutoBills, with a payment method matching the specified Account's primary payment method.
  • AllActive—Bill all ready AutoBills, replace on all AutoBills with payment methods belonging to the specified Account.

Note The enumerated values are the same for updateScopeOnChildren and updateScopeOnAccount. You can apply them independently or leave them null. For example, you could set AllActive on updateScopeOnChildren and None on updateScopeOnAccount. This would set the payment method on every child AutoBill to the new payment method, set the payment method on the Account to the new payment method, but not change the payment method on any AutoBills belonging directly to the specified (primary/parent) Account.


updateBehavior: specifies whether to just Update (update without validation), Validate (validate first), or CatchUp (catch up on billing first).

  • Update: the paymentMethod is saved and associated with the account. If the  updateScopeOnAccount and/or  updateScopeOnChildren values are set to a value other than None, or if the  updateScopeOnAccount value is left unspecified, the payment method associated with AutoBills within the specified scope of the update will also be set to the new or updated payment method specified in the call.
  • Validate: the call attempts to validate the payment method and, if successful, proceeds as in the Update case. Does not update and returns the appropriate 4xx error code if validation fails.
  • CatchUp: if there are no AutoBills within  updateScopeOnAccount and updateScopeOnChildren eligible for billing, the call proceeds as if Validation were set. Otherwise, for each AutoBill in the  updateScopeOnAccount and updateScopeOnChildren purview, catch-up billing is performed such that:
    • If the AutoBill is in Good Standing and is not ready to bill, the paymentMethod on the AutoBill is set to the new or updated payment method.
    •  • If the AutoBill is in Good Standing and is due to bill today, or if the AutoBill is in Soft or Hard Error and its end date is after today (that is, still within the retry period), an attempt is made to bill (or reprocess the failed billing attempt) on the AutoBill using the new or updated payment method specified in the Account.updatePaymentMethod() call. If the attempt is successful, the payment method for subsequent billing attempts on the AutoBill is set to the new or updated payment method. If the AutoBill was in error and the reprocessing attempt was successful, the AutoBill status is set to Good Standing. If the AutoBill was in Hard Error, it is reactivated.
    •  • After catch-up billing, if any AutoBill billing or reprocessing attempts were successful, the payment method on the Account is set to the new or updated payment method.

After all catch-up billing and AutoBill payment method updates have been performed:

  • If all AutoBill billing attempts were successful and any or all payment methods were updated successfully on the AutoBill(s) and Account, the call returns 200 (success) and a list of merchant AutoBill identifiers of successfully billed AutoBills in the Successes field of the Return object.
  • If some AutoBill billing attempts were successful, the call returns 206 (partial success) and a list of merchant AutoBill identifiers of successfully billed or updated AutoBills in the Successes field of the Return object, and a list of merchant AutoBill identifiers of unsuccessfully billed or updated AutoBills in the Failures field of the Return object.
  • If the paymentMethod is invalid, or catch-up billing or update failed on all eligible AutoBills (where there were AutoBills eligible for billing or update), the call returns a list of failures in the Return object and an appropriate 4xx return code.

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.

updateScopeOnChildren: enumerated options controlling whether and when to bill and/or replace the payment method on associated AutoBills belonging to the child Accounts of the specified Account. If you do not specify a value,  updateScopeOnChildren defaults to the equivalent of the none option.

Use the following enumerated values to specify which child Accounts you want to catch-up billing on, and on which AutoBills you want to replace the payment method.

  • None—Do not bill on any AutoBills for this/these Accounts. Do not replace the payment method on this/these Account(s).
  • matchingPaymentMethod—Bill only on those ready AutoBills whose payment method matches the default payment method on the specified Account. Replace the payment method only on those AutoBills whose payment method matches the default payment method on the specified Account.
  • AllDue—Bill all (account and children) AutoBills with payment methods belonging to the specified Account that are in error or ready to bill. The payment method is replaced on those billed.
  • AllDueAndMatching—Bill all (account and children) AutoBills with payment methods belonging to the specified Account that are in error or ready to bill. The payment method is replaced on those billed, as well as on any AutoBills, with a payment method matching the specified Account's primary payment method.
  • AllActive—Bill all ready AutoBills, replace on all AutoBills with payment methods belonging to the specified Account.

Note The enumerated values are the same for updateScopeOnChildren and updateScopeOnAccount. You can apply them independently or leave them null. For example, you could set AllActive on updateScopeOnChildren and None on updateScopeOnAccount. This would set the payment method on every child AutoBill to the new payment method, set the payment method on the Account to the new payment method, but not change the payment method on any AutoBills belonging directly to the specified (primary/parent) Account.


Output

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

account: the Account object whose payment method was changed.

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

Returns

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

The call succeeded.

The call returns a list of merchant AutoBill identifiers of successfully billed AutoBills in the Successes field of the Return Object.

Partial success.

The call returns a list of merchant AutoBill identifiers of successfully billed or updated AutoBills in the Successes field of the Return object, and a list of merchant AutoBill identifiers of unsuccessfully billed or updated AutoBills in the Failures field of the Return object.

Return Code

Return String

200

The call succeeded.

The call returns a list of merchant AutoBill identifiers of successfully billed AutoBills in the Successes field fo the Return object. 

206

Partial success.

The call returns a list of merchant  AutoBill identifiers of successfully billed or updated  AutoBills in the Successes field of the  Return object, and a list of merchant  AutoBill identifiers of unsuccessfully billed or updated  AutoBills in the Failures field of the  Return object.

261

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

400

One of the following:

  • Invalid Payment Method Type. (You cannot change the Payment Method Type on an existing Payment Method.)
  • No PaymentMethod specified in arguments.
  • Data validation error Failed to create Payment-Type-Specific Payment Record: Credit Card conversion failed: Credit Card failed Luhn check.

402

One of the following:

  • PaymentMethod failed validation.
  • Error attempting to authorize card.
  • Unable to authorize card.

404

No match found error-description.

Returned if CashBox cannot find an account that matches the input in the Vindicia database.

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.

Example

// to update a payment method

$accountId = "CUST219";

// Create an account object

$account = new Account();

$account->setMerchantAccountId($accountId);

$paymentMethod = new PaymentMethod();

// Update an existing payment method to a new expiration
// date and a new billing address. The code here assumes that you know
// the merchantPaymentMethodId of the payment method.

$paymentMethod->setMerchantPaymentMethodId("345abc678");
$newBillAddress = new Address();
$newBillAddress->setAddr1("123 Maple St");

// Populate rest of the address object here.

// Set the new billing address in the payment method.

$paymentMethod->setBillingAddress($newBillAddress);

// Create a new credit card object and populate it with updated
// information.

$cc = new CreditCard();
$cc->setAccount("4343121267679193");
$cc->setExpirationDate("201211");

// Set the credit card information in the payment method

$paymentMethod->setType('CreditCard');
$paymentMethod->setCreditCard($cc);

 

// Now make the updatePaymentMethod call with validation and

// replacement on all autobills enabled

$updateScopeOnAccount = 'AllActive';

$updateScopeOnChildren = 'AllActive';

$response =

$account->updatePaymentMethod($paymentMethod, $updateScopeOnAccount,

'CatchUp', 0, 0, $updateScopeOnChildren);

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

print "Call succeeded\n";

}

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

print "Payment method validation failed\n";

}

else {

// Handle other error situations here

}

For Users

Learn More
For Users

Cashbox Features

Learn More
Cashbox Features
Back to Top