addCustomerPaymentMethod

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

Description

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

Syntax

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

Arguments

Type	Name	Description
ueSecurityToken	Token	Merchant security token: used to identify merchant and validate transaction.
string	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

Type	Description
string	The ID of the new payment method.

Examples

PHP

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

    try {

      $CustNum='113701';
      $PaymentMethod=array(
        'MethodName'=>'Example',

          'CardNumber'=>'4444555566667779',
          'CardExpiration'=>'1212',
          'CardType'=>'',    
          'CardCode'=>'',
          'AvsStreet'=>'',
          'AvsZip'=>'',  

        'SecondarySort'=>0
        );

      $Default=true;
      $Verify=false;

      $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();

    }

Java

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

    try {

    //Setting Customer Number
    BigInteger custnum = new BigInteger("12345678");

    //Setting up New Payment Method
    PaymentMethod paymethod = new PaymentMethod();
        paymethod.setExpires("2012-09-01");
        CreditCardData ccdata = new CreditCardData();
            ccdata.setCardNumber("4000100011112224");
            ccdata.setCardExpiration("0912");
            ccdata.setAvsStreet("123 Main");
            ccdata.setAvsZip("12345");
        paymethod.setCreditCardData(ccdata);
        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());
    }

.NET VB

    Dim CustNum As String
            CustNum = "103125"

            Dim payMethod As newtek.PaymentMethod = New newtek.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)
            MsgBox(response)

.NET C

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";            

                newtek.PaymentMethod payMethod = new newtek.PaymentMethod();
                payMethod.CardExpiration = "1212";
                payMethod.CardNumber = "4000100011112224";
                payMethod.AvsStreet = "123 Main st.";
                payMethod.AvsZip = "90046";
                payMethod.MethodName = "My Visa";

                string response;

                try
                {
                    response = client.addCustomerPaymentMethod(token, CustNum,payMethod,false,true);
                    MessageBox.Show(string.Concat(response));
                }

                catch (Exception err)
                {
                    MessageBox.Show(err.Message);
                }

XML

Request:

    <?xml version="1.0" encoding="UTF-8"?>
       <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"xmlns:ns1="urn:newtek"
        xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
        SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
          <SOAP-ENV:Body>
             <ns1:addCustomerPaymentMethod>
                <Token xsi:type="ns1:ueSecurityToken">
                   <ClientIP xsi:type="xsd:string">123.123.123.123</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>
                   </PinHash>
                   <SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
                </Token>
                <CustNum xsi:type="xsd:string">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>
                </PaymentMethod>
                <MakeDefault xsi:type="xsd:boolean">true</MakeDefault>
                <Verify xsi:type="xsd:boolean">false</Verify>
             </ns1:addCustomerPaymentMethod>
          </SOAP-ENV:Body>
       </SOAP-ENV:Envelope>

Response:

    <?xml version="1.0" encoding="utf-8"?>
    <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:ns1="urn:newtek"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
    SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
      <SOAP-ENV:Body>
        <ns1:addCustomerPaymentMethodResponse>
          <addCustomerPaymentMethodReturn xsi:type="xsd:string">148</addCustomerPaymentMethodReturn>
        </ns1:addCustomerPaymentMethodResponse>
      </SOAP-ENV:Body>
    </SOAP-ENV:Envelope>

Change Log

Version	Change
1.7	Changed ReturnValue and CustNum to type string
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.