Soap API v1.6


This method allows you to add a new payment method to a customer record.


Multiple payment methods may be stored for each customer. There is no limit to the number of payment methods that can be stored, but only one of these methods may be marked as the default payment method for all future transactions including recurring billing and manual charges.

To set a payment method as default, pass “true” for the MakeDefault parameter. Setting a payment method to default overrides the SecordarySort parameter and sets it to 0. If another method is currently set to default, it will have its SecondarySort changed to 1.

All new payment methods will be validated by the system to be sure that the information entered fits the required format for the specified payment method. (ie: Does the credit card have 16 digits and a future expiration date? Does the check routing number have 9 digits?)

To further verify that a credit card is “good”, set the Verify parameter to “true” (available for credit cards only). This setting will cause the gateway to run an AuthOnly transaction for $0.05. Any fraud modules that are configured for the source will be run. If the transaction is declined the payment method will not be stored and a fault will be thrown with the decline or error message.

If the Verify parameter is set to “false,” the payment data will still be checked to ensure that it is formatted correctly, but the credit card validity will not be verified.

If any errors are detected or the Verify fails, a fault will be thrown. This method requires the use of the CustNum, a unique customer number assigned by the gateway. If you have lost or cannot remember the customer's CustNum, use the searchCustomers method to find the correct CustNum.

See also runCustomerTransaction, enableCustomer, disableCustomer, deleteCustomer, searchCustomerID, getCustomer, searchCustomers, getCustomerHistory, addCustomer, deleteCustomerPaymentMethod, updateCustomer, quickUpdateCustomer


integer addCustomerPaymentMethod ( ueSecurityToken Token, integer CustNum, PaymentMethod PaymentMethod, boolean MakeDefault, boolean Verify )


Type Name Description
ueSecurityToken Token Merchant security token: used to identify merchant and validate transaction.
integer CustNum A unique customer number assigned by the gateway.
PaymentMethod PaymentMethod Includes method name, description, ID, and expiration date.
boolean MakeDefault Determines default payment method for specified customer. If set to true, payment method will be marked as default.
boolean Verify If set to true, an AuthOnly verification of the credit card validity will be run. (See above.)

Return Value

integer The ID of the new payment method.



For directions on how to set up the WSDL link, create “$token” and “$client”, go to PHP Soap How-to.

try { 
  $MethodID=$client->addCustomerPaymentMethod($token, $CustNum, $PaymentMethod, 
                                         $Default, $Verify); 
catch(SoapFault $e) { 
  echo "\n\nResponse: " . $client->__getLastResponse(); 
  echo "\n\nRequest: " . $client->__getLastRequest(); 
  echo "SoapFault: " .$e->getMessage(); 


This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to either the Java JAX-RPC Howto or the Java JAX-WS Howto.

try {
//Setting Customer Number
BigInteger custnum = new BigInteger("12345678");
//Setting up New Payment Method
PaymentMethod paymethod = new PaymentMethod();
	CreditCardData ccdata = new CreditCardData();
		ccdata.setAvsStreet("123 Main");
	paymethod.setMethodName("My Visa");
//Adding Payment Method
BigInteger PaymentMethodID = client.addCustomerPaymentMethod(token, custnum, paymethod, true, true);
} catch (Exception e) {
	System.out.println("Soap Exception: " + e.getMessage());


Dim CustNum As String
        CustNum = "103125"
        Dim payMethod As usaepay.PaymentMethod = New usaepay.PaymentMethod
        payMethod.CardExpiration = "1212"
        payMethod.CardNumber = "4000100011112224"
        payMethod.AvsStreet = "123 Main st."
        payMethod.AvsZip = "90046"
        payMethod.MethodName = "My Visa"
        Dim response As String
        response = client.addCustomerPaymentMethod(token, CustNum, payMethod, False, True)


For directions on how to set up the WSDL link and create the “token” and “client” variables, go to the C Sharp .Net Soap How-to.

            string CustNum = "89792";            
            usaepay.PaymentMethod payMethod = new usaepay.PaymentMethod();
            payMethod.CardExpiration = "1212";
            payMethod.CardNumber = "4000100011112224";
            payMethod.AvsStreet = "123 Main st.";
            payMethod.AvsZip = "90046";
            payMethod.MethodName = "My Visa";
            string response;
                response = client.addCustomerPaymentMethod(token, CustNum,payMethod,false,true);
            catch (Exception err)



<?xml version="1.0" encoding="UTF-8"?> 
   <SOAP-ENV:Envelope xmlns:SOAP-ENV=""xmlns:ns1="urn:usaepay"
    xmlns:xsd="" xmlns:xsi=""
            <Token xsi:type="ns1:ueSecurityToken">
               <ClientIP xsi:type="xsd:string"></ClientIP>
               <PinHash xsi:type="ns1:ueHash">
                  <HashValue xsi:type="xsd:string">822928da5a6ca1e93b432055cc2007617b481cd8</HashValue>
                  <Seed xsi:type="xsd:string">12036339087-test</Seed>
                  <Type xsi:type="xsd:string">sha1</Type>
               <SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
            <CustNum xsi:type="xsd:integer">4608142</CustNum>
            <PaymentMethod xsi:type="ns1:PaymentMethod">
               <MethodName xsi:type="xsd:string">CreditCard</MethodName>
               <SecondarySort xsi:type="xsd:integer">8</SecondarySort>
               <AvsStreet xsi:type="xsd:string">5454 Bravo St</AvsStreet>
               <AvsZip xsi:type="xsd:string">91111</AvsZip>
               <CardCode xsi:type="xsd:string"></CardCode>
               <CardExpiration xsi:type="xsd:string">1218</CardExpiration>
               <CardNumber xsi:type="xsd:string">4444555566667779</CardNumber>
               <CardType xsi:type="xsd:string"></CardType>
            <MakeDefault xsi:type="xsd:boolean">true</MakeDefault>
            <Verify xsi:type="xsd:boolean">false</Verify>


<?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV=""
      <addCustomerPaymentMethodReturn xsi:type="xsd:integer">148</addCustomerPaymentMethodReturn>

Change Log

Version Change
1.0 Verify parameter implemented.
beta6 Method added. (See notes below)

Please Note: Beta6 supports only one payment method for each customer. This means that if you add a new payment method to a customer's account, the new method will overwrite the existing method.

Beta6 also overrides the Verify parameter, so if you add a customer payment method, the gateway will not run the AuthOnly charge of $0.01 to verify that the credit card is valid. The data will still be validated to ensure that it is in the correct format, but the Verify parameter will not be run.

developer/soap-1.6/methods/addcustomerpaymentmethod.txt · Last modified: 2015/12/08 15:53 by yaya

Page Tools