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.