Account.updatePaymentMethod

​

Input

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

• None—Do not bill on any AutoBills for this/these Accounts. 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) 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 AutoBillss, replace on all AutoBills with payment methods belonging to the specified Account

• 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 4*xx* 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 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.

• 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 Return identifiers of unsuccessfully billed or updated Returns 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 4*xx* return code.

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

​

Output

​

Returns

​

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
}