addCustomer

This method adds a customer to your stored customer database so that their information can be recalled at a later date.

Description

The customer will be assigned a unique customer number by the gateway (CustNum), which you can then use to establish recurring billing cycles, recall customer data, and manually charge the customer for later products or services without needing to reenter their information.

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

Syntax

string addCustomer ( ueSecurityToken Token, CustomerObject CustomerData )

Arguments

Type Name Description
ueSecurityToken Token Merchant security token: used to identify merchant and validate transaction.
CustomerObject CustomerData Includes customer information such as customer number, merchant assigned customer ID, billing address, receipt settings, recurring billing settings, and other pertinent information.

Return Value

Type Description
string Returns result of add customer request.

Examples

PHP

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

    try {

    $CustomerData=array(
        'BillingAddress'=>array(
            'FirstName'=>'John',
            'LastName'=>'Doe',
            'Company'=>'Acme Corp',
            'Street'=>'1234 main st',
            'Street2'=>'Suite #123',
            'City'=>'Los Angeles',
            'State'=>'CA',
            'Zip'=>'12345',
            'Country'=>'US',
            'Email'=>'charlie@newtekgateway.com',
            'Phone'=>'333-333-3333',
            'Fax'=>'333-333-3334'),
        'PaymentMethods' => array(
            array(

                        'CardNumber'=>'4444555566667779',
                        'CardExpiration'=>'0213',
                        'CardType'=>'', 'CardCode'=>'','AvsStreet'=>'',
                        'AvsZip'=>'',
                    "MethodName"=>"My Visa",
                    "SecondarySort"=>1)
            ),
            'CustomData'=>base64_encode(serialize(array("mydata"=>"We could put anything in here!"))),
            'CustomFields'=>array(
                array('Field'=>'Foo', 'Value'=>'Testing'),
                array('Field'=>'Bar', 'Value'=>'Tested')
            ),
        'CustomerID'=>123123 + rand(),
        'Description'=>'Weekly Bill',
        'Enabled'=>false,
        'Amount'=>'44.93',
        'Tax'=>'0',
        'Next'=>'2012-01-21',
        'Notes'=>'Testing the soap addCustomer Function',
        'NumLeft'=>'50',
        'OrderID'=>rand(),
        'ReceiptNote'=>'addCustomer test Created Charge',
        'Schedule'=>'weekly',
        'SendReceipt'=>true,
        'Source'=>'Recurring',
        'User'=>'',
        'CustNum'=>'C'.rand()
    );

      $Result=$client->addCustomer($token,$CustomerData);

    }

    catch(SoapFault $e) {

      echo "SoapFault: " .$e->getMessage(); print_r($e);
      echo "\n\nRequest: " . $tran->__getLastRequest();
      echo "\n\nResponse: " . $tran->__getLastResponse();
    }

Java

This example uses the Newtek Gateway Java library.

    try {

    // instantiate client connection object,  select secure.newtekgateway.com
    // as the endpoint.  Use sandbox.newtekgateway.com if connecting to
    // the sandbox server.
    UeSoapServerPortType client = newtek.getClient("sandbox.newtekgateway.com");
    // Instantiate security token object (need by all soap methods)
    UeSecurityToken token = newtek.getToken(
      "_Z0ji6VHHIzMR99PMgaf91FZxwC630mp", // source key
      "1234",  // source pin  (if assigned by merchant)
      "127.0.0.1"  // IP address of end client (if applicable)
      );

         CustomerObject customer = new CustomerObject();

    // Setup address information
         Address address = new Address();
         address.setFirstName("John");
         address.setLastName("Doe");
         address.setCompany("Acme INC");
         address.setStreet("343 Main Street");
         address.setStreet2("Suite 222");
         address.setCity("Somewhere");
         address.setState("CA");
         address.setZip("91920");
         address.setCountry("US");
         address.setEmail("joe@example.com");
         address.setFax("595-343-4454");
         address.setPhone("333-444-5555");
         customer.setBillingAddress(address);

    // Set recurring billing options
         customer.setEnabled(true);
         customer.setAmount(5.00);
         customer.setTax(0.50);
         customer.setNext("2015-09-01");

         customer.setSchedule("Monthly");
         customer.setOrderID("100090");
         customer.setDescription("Monthly Member Fee");

    // setup Payment Methods
         PaymentMethodArray paymethods = new PaymentMethodArray();
         PaymentMethod paymethod = new PaymentMethod();
         paymethod.setCardNumber("4111111111111111");
         paymethod.setCardExpiration("0919");
         paymethod.setMethodName("My Visa");
         paymethods.getPaymentMethod().add(paymethod);
         customer.setPaymentMethods(paymethods);


    // Setup custom fields
         FieldValueArray customfields = new FieldValueArray();
         customfields.getFieldValue().add(fv("Dorky", "Testing"));
         customfields.getFieldValue().add(fv("Donkey", "Tested"));
         customfields.getFieldValue().add(fv("Wonky", "Tested"));
         customer.setCustomFields(customfields);


    // Create request object

         AddCustomerRequest request = new AddCustomerRequest();
         request.setToken(token);
         request.setCustomerData(customer);

    // Create response object
         BigInteger response;


    // Add Customer
         response = client.addCustomer(token, customer);

         System.out.println("Added customer " + response);

       } catch (Exception e) {
         e.printStackTrace();
       }
     }

.NET VB

    Dim customer As newtek.CustomerObject = New newtek.CustomerObject
            Dim address As newtek.Address = New newtek.Address
            address.FirstName = "John"
            address.LastName = "Doe"
            address.Company = "Acme"
            address.Street = "123 main st."
            address.City = "Hollywood"
            address.State = "ca"
            address.Zip = "91607"
            address.Country = "USA"
            customer.BillingAddress = address

            customer.Enabled = True
            customer.Amount = 5.0
            customer.Next = "2010-08-15"
            customer.Schedule = "monthly"

            Dim payMethod(0) As newtek.PaymentMethod
            payMethod(0) = New newtek.PaymentMethod
            payMethod(0).CardExpiration = "1212"
            payMethod(0).CardNumber = "4444555566667779"
            payMethod(0).AvsStreet = "123 Main st."
            payMethod(0).AvsZip = "90046"
            payMethod(0).MethodName = "My Visa"

            customer.PaymentMethods = payMethod
            Dim response As String

            response = client.addCustomer(token, customer)
            MsgBox(String.Concat(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.

    newtek.CustomerObject customer = new newtek.CustomerObject();
                newtek.Address address = new newtek.Address();
                address.FirstName = "John";
                address.LastName = "Doe";
                address.Company = "Acme";
                address.Street = "123 main st.";
                address.City = "Hollywood";
                address.State = "ca";
                address.Zip = "91607";
                address.Country = "USA";
                customer.BillingAddress = address;

                customer.Enabled = true;
                customer.Amount = 5.00;
                customer.Next = "2010-08-15";
                customer.Schedule = "monthly";

                newtek.PaymentMethod[] payMethod = new newtek.PaymentMethod[1];
                payMethod[0] = new newtek.PaymentMethod();
                payMethod[0].CardExpiration = "1212";
                payMethod[0].CardNumber = "4444555566667779";
                payMethod[0].AvsStreet = "123 Main st.";
                payMethod[0].AvsZip = "90046";
                payMethod[0].MethodName = "My Visa";

                customer.PaymentMethods = payMethod;
                string response;

                try
                {
                    response = client.addCustomer(token, customer);
                    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:addCustomer>
                <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">dcdce3cd41a4fe05b3026cb494b82c01487266fe</HashValue>
                      <Seed xsi:type="xsd:string">11638841859-test</Seed>
                      <Type xsi:type="xsd:string">sha1</Type>
                   </PinHash>
                   <SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
                </Token>
                <CustomerData xsi:type="ns1:CustomerObject">
                   <Amount xsi:type="xsd:double">44.93</Amount>
                   <BillingAddress xsi:type="ns1:Address">
                      <City xsi:type="xsd:string">Los Angeles</City>
                      <Company xsi:type="xsd:string">Acme Corp</Company>
                      <Country xsi:type="xsd:string">US</Country>
                      <Email xsi:type="xsd:string">joe@example.com</Email>
                      <Fax xsi:type="xsd:string">333-333-3334</Fax>
                      <FirstName xsi:type="xsd:string">Clariss</FirstName>
                      <LastName xsi:type="xsd:string">Doe</LastName>
                      <Phone xsi:type="xsd:string">333-333-3333</Phone>
                      <State xsi:type="xsd:string">CA</State>
                      <Street xsi:type="xsd:string">1234 main st</Street>
                      <Street2 xsi:type="xsd:string">Suite #123</Street2>
                      <Zip xsi:type="xsd:string">12345</Zip>
                   </BillingAddress>

                   <CustomData xsi:type="xsd:string">YToxOntzOjY6Im15ZGF0YSI7czozMDoiV2UgY291bGQgcHV0IGFueXRoaW5nIGluIGhlcmUhIjt9</CustomData>
                   <CustomFields SOAP-ENC:arrayType="ns1:FieldValue[2]" xsi:type="ns1:FieldValueArray">
                      <item xsi:type="ns1:FieldValue">
                         <Field xsi:type="xsd:string">Foo</Field>
                         <Value xsi:type="xsd:string">Testing</Value>
                      </item>
                      <item xsi:type="ns1:FieldValue">
                         <Field xsi:type="xsd:string">Bar</Field>
                         <Value xsi:type="xsd:string">Tested</Value>
                      </item>
                   </CustomFields>
                   <CustomerID xsi:type="xsd:string">2203547</CustomerID>
                   <Description xsi:type="xsd:string">Weekly Bill</Description>
                   <Enabled xsi:type="xsd:boolean">true</Enabled>
                   <Next xsi:type="xsd:string">2015-07-29</Next>
                   <Notes xsi:type="xsd:string">Testing the soap addCustomer Function</Notes>
                   <NumLeft xsi:type="xsd:integer">50</NumLeft>
                   <OrderID xsi:type="xsd:string">692259714</OrderID>
                   <PaymentMethods SOAP-ENC:arrayType="ns1:PaymentMethod[1]" xsi:type="ns1:PaymentMethodArray">
                      <item xsi:type="ns1:PaymentMethod">
                         <MethodName xsi:type="xsd:string">My Visa</MethodName>
                         <SecondarySort xsi:type="xsd:integer">9</SecondarySort>
                         <AvsStreet xsi:type="xsd:string"></AvsStreet>
                         <AvsZip xsi:type="xsd:string"></AvsZip>
                         <CardCode xsi:type="xsd:string"></CardCode>
                         <CardExpiration xsi:type="xsd:string">0219</CardExpiration>
                         <CardNumber xsi:type="xsd:string">4444555566667779</CardNumber>
                         <CardType xsi:type="xsd:string"></CardType>
                      </item>
                   </PaymentMethods>
                   <ReceiptNote xsi:type="xsd:string">addCustomer test Created Charge</ReceiptNote>
                   <Schedule xsi:type="xsd:string">monthly</Schedule>
                   <SendReceipt xsi:type="xsd:boolean">true</SendReceipt>
                   <Source xsi:type="xsd:string">Recurring</Source>
                   <Tax xsi:type="xsd:double">0</Tax>
                   <User xsi:type="xsd:string"></User>
                </CustomerData>
             </ns1:addCustomer>
          </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:addCustomerResponse>
          <addCustomerReturn xsi:type="xsd:string">4608136</addCustomerReturn>
        </ns1:addCustomerResponse>
      </SOAP-ENV:Body>
    </SOAP-ENV:Envelope>

Change Log

Version Change
1.7 Changed ReturnValue to type string