> ## Documentation Index
> Fetch the complete documentation index at: https://docs.slm.m1amdocs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](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/or replace the *paymentMethod* on associated *AutoBill*s 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 `Account`s. Do not replace the `paymentMethod` on this/these `Account`(s).
* `matchinPaymentMethod`—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) `AutoBill`s 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 `AutoBill`s, with a payment method matching the specified `Account's` primary payment method.
* `AllActive`—Bill all ready `AutoBills`s, replace on all `AutoBill`s 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 `AutoBil` 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 `AutoBill`s 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 `AutoBill`s 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 `4*xx*` error code if validation fails.

* *CatchUp*: if there are no `AutoBill`s 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 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 `AutoBill`s 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 `AutoBill`s in the Successes field of the `Return` object, and a list of merchant `Return` identifiers of unsuccessfully billed or updated `Return`s in the Failures field of the `Return` object.
* If the `paymentMethod` is invalid, or catch-up billing or update failed on all eligible `AutoBill`s (where there were `AutoBill`s eligible for billing or update), the call returns a list of failures in the `Return` object and an appropriate `4*xx*` 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 *updatePaymentMethod* is set to `Validate`) 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 *updatePaymentMethod* is set to `Validate`) 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 `Account` you want to catch-up billing on, and on which `AutoBill`s you want to replace the payment method.

* `None`—Do not bill on any `AutoBill`s for this/these `Account`s. 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 `AutoBill`s 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) `AutoBill`s 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 `AutoBill`s, 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 `AutoBill`s belonging directly to the specified (primary/parent) `Account`.

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

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

*successes*: Merchant identifiers for AutoBills successfully billed during catch up billing.

*failures*: Merchant identifiers for AutoBills unsuccessfully billed during catch up billing.

*initialTransaction*: Validation Transaction.

*authStatus*: If payment method validation was requested, or the initial Transaction was processed, this object will contain more information on response to the validation from the payment processor.

## Returns

In addition to those listed in [The Return Object](The_Return_Object), this call returns:

| 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 of the Return object. |
| `206` | `Partial success.` The call returns a list of merchant `AutoBill` identifiers of successfully billed or updated `AutoBill` s 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: - I`nvalid 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.` - `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` | One of the following: - `PaymentMethod failed validation.` - `Error attempting to authorize card.` - `Unable to authorize card.` |
| `404` | `No match found *error-description*.` Returned if Subscribe cannot find an account that matches the input in the Vindicia database. An error string and the failures key and list of AutoBills that failed to bill or update. |
| `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";
 if ( $response['successes'] && $response['successes'][0] )
 {
 print $response['successes'][0]." is an invoice successfully rebilled.\n";
 }
}
else if($response['returnCode'] == 402) {
print "Payment method validation failed\n";
 if ( $response['failures'] && $response['failures'][0] )
 {
 print $response['failures'][0]." is an invoice unsuccessfully rebilled.\n";
 }
}
else {

// Handle other error situations here
}
```

**Parent topic:**[Account Methods](../topics/Account_Methods)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.