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

# addPaymentMethods

Vindicia Retain provides an optional capability to retry billing using multiple, different payment methods provided by the Merchant. This capability is enabled by Merchant Configuration performed by your Vindicia Deployment Services contact. When this setting is enabled, the Merchant can use this API method to submit additional payment method details linked to a specific customer Account. Retain will perform retries using each eligible PaymentMethod in succession (determined by ascending `sortOrder` value on each PaymentMethod object associated with the Retain customer Account). When any Transaction retry succeeds or has been attempted with each eligible PaymentMethod, Retain stops retries for that submitted Transaction.

If a retry with a specific PaymentMethod is declined with a Soft Failure response code, the PaymentMethod is unchanged and can be used during subsequent retry cycles and an additional retry is attempted in the current cycle using the next eligible PaymentMethod for that customer.

If a retry with a specific PaymentMethod is rejected with a Hard Failure response code, the PaymentMethod is marked as ineligible for future retries for any Transactions for this customer Account.

When all eligible PaymentMethods provided by the Merchant for a customer Account have been attempted, the retry cycle for that Transaction is concluded.

## Input

*auth: Credentials required to authenticate this request*

*paymentMethods*: an array of Retain [Payment Method](payment_method_data_members) objects to be associated with the Account object identified by accountVID or customerId or externalId.

**Note:** Account objects are identified by (in order of precedence) `accountVID`, `customerId` or `externalId`.

**Note:** If an Account using one of the above identifiers does not already exist, it will be created by Retain.

## Output

*return*: an object of type `Return` indicating success or failure of the call.

*response*: an array of PaymentMethodValidationResponse objects which contains the `paymentMethodId` of each PaymentMethod that returned an error.

**Note:** An empty `response` array indicates that the API call succeeded without error. For more information, see [PaymentMethodValidationResponse](PaymentMethodValidationResponse).

## Returns

This method returns the codes listed in [Retain Return Codes](retain.return_codes).

## Example

```

//Given the existing (i.e. already created via a prior billTransactions call)
//customerID McPrfx789:

$pm = new PaymentMethod();
// Merchant Customer ID should be unique for each unique Customer.
$pm->setCustomerId('McPrfx789'); //Required
$pm->setPaymentMethodId('PmPrfx012');
$pm-setPaymentMethodType('CreditCard');
$pm->setPaymentMethodIsTokenized(false);
$pm->setCreditCardAccount('4111111111111111');
$pm->setCreditCardExpirationDate('20121212');
$pm->setAccountHolderName('Calvin Hobbes');
$pm->setBillingAddressLine1('Suite 200');
$pm->setBillingAddressLine2('23 George Street');
$pm->setBillingAddressCity('Larkspur');
$pm->setBillingAddressDistrict('CA');
$pm->setBillingAddressPostalCode('94964');
$pm->setBillingAddressCountry('US');
$pm->setSortOrder(1); // Required 

$select = new select();
$ret = $select->addPaymentMethods(array{$tx});
if($ret['returnCode'] == 200)
{
    $failedTransactions = $ret['response'];
    if($failedTransactions && (sizeof($failedTransactions) > 0))
    {
        foreach ($failedTransactions as $transaction)
        {
            //Evaluate Validation failure response here.
        }
    }
}
    else
    {//Handle error condition.
}
```

**Parent topic:**[Vindicia Retain Methods](../topics/vindicia_retain_methods)


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