Soap API v1.7
The USAePay SOAP API provides a standardized web services interface that allows developers to leverage much of the gateway functionality within their applications. The API is designed to give developers the tools necessary to create highly customized payment applications. Since the API uses web standards, it is directly supported by many programming languages such as Dot Net and PHP.
Versioning
SOAP uses WSDL files to describe the methods and objects that are made available by a webservice. With each new version of the USAePay soap API a new WSDL file is released. Once a version of the API is released, it's corresponding WSDL file will not change. This allows developers to continue to use an older version of the API indefinitely without the risk of future releases breaking existing code. There is no need to upgrade to the latest version unless new functionality is desired. There is also no restriction on the number of WSDL files used by an application. Existing code can continue to use the old WSDL while newly added code can use a second WSDL link.
To create a WSDL link for your application you must login into the Developer's Center. Once logged in, click on "API Endpoints" and then "New Endpoint" to create a new WSDL link.
Current Version: 1.7
Getting Started
The following guides give specific setup instructions/background information on using Soap with some of the more common programming languages. If you are using a language not listed below, please feel free to contact us for assistance. The Soap interface can be used with any programming language that is able to communicate with an HTTPS connection.
- PHP 5 (Built-in SoapClient)
- PHP 5 (Pear Library)
- Visual Basic (.Net)
- Visual Basic 2010 (.Net 4.0)
- C# (.Net)
- Java (JAX-WS)
- Ruby
PHP 5 (Built-in SoapClient)
This guide provides information on using PHP with the USAePay SOAP API. The SOAP API provides an advanced interface to USAePay that allows merchants and resellers to access a wide range of functionality. This API requires a little more expertise than our simpler PHP Library for the Transaction API. If you are only looking to process transactions it is recommended that you use the PHP Library instead.
Choosing a SOAP Library
When using PHP there are several SOAP libraries available that can be used to make the integration with USAePay easier. While using a library is not required, it typically makes the development process much quicker. We've listed the two libraries that we recommend and actively support. There are several other libraries that should work well but we have not had the time to throughly test all of them.
PHP SoapClient extension
PHP 5 and above comes with a Soap extension included. USAePay recommends that all developers use this class if possible. This guide includes examples for the PHP 5 SoapClient and assumes that you have it installed correctly. To verify that you have the soap client installed run a script with:
<?php phpinfo() ?>
The output should include "Soap Client: enabled" If you do not have it installed and are using a Linux server, you will need to install the php-soap package. For example, on Red Hat EL or CentOS:
yum install php-soap
If you compile your own PHP server, include --enable-soap in the ./configure command.
If you do not have the ability to install software or recompile php, use the PEAR Soap library instead (see below).
PEAR::Soap
The official Pear repository includes a fairly full-featured Soap library written in PHP. Since it is written in PHP, it does not require any special privileges on the server. See PEAR::Soap for more information.
The information in this guide is for the PHP SoapClient extension. For information on using the PEAR::Soap library with USAePay, please see the PEAR Soap Guide.
Using SoapClient
Step 1: Instantiating $client
Instantiating $client Example
<?php
//for live server use 'www' for test server use 'sandbox'
$wsdl='https://www.usaepay.com/soap/gate/0AE595C1/usaepay.wsdl';
// instantiate SoapClient object as $client
$client = new SoapClient($wsdl);
?>
The first step is to instantiate the SoapClient object. In the SOAP example provided on this site, we use $client for this object.
If this fails with the error:
Fatal error: Cannot instantiate non-existent class: soapclient
then you do not have the SoapClient extension installed. See the directions above for more info on installing the extension.
If this fails with the error:
Unable to retrieve WSDL https://www.usaepay.com/soap/gate/xxxxxxxx/usaepay.wsdl
then remove usaepay.wsdl from the link leaving only https://www.usaepay.com/soap/gate/xxxxxxxx/ and try again.
Step 2: Building Security $token
Building Security $token Example
<?php
$sourcekey = 'yQbOFkmykeygoeshere3Lc9PH1l14';
$pin = '1234';
// generate random seed value
$seed=time() . rand();
// make hash value using sha1 function
$clear= $sourcekey . $seed . $pin;
$hash=sha1($clear);
// assembly ueSecurityToken as an array
$token=array(
'SourceKey'=>$sourcekey,
'PinHash'=>array(
'Type'=>'sha1',
'Seed'=>$seed,
'HashValue'=>$hash
),
'ClientIP'=>$_SERVER['REMOTE_ADDR'],
);
?>
The ueSecurityToken object is used to securely identify the merchant to the gateway. To build a token, you will need the merchant's Source Key and Pin.
The source key is created by the merchant in the Merchant Console under the Settings - API Keys screen. Many of the methods in the SOAP API require the use of a PIN, and it is recommended that you always use a PIN. The merchant assigns the PIN when creating the source key.
Additional Help
For questions, please email devsupport@usaepay.com
PHP 5 (Pear Library)
This guide provides information on using the PEAR::Soap library with the USAePay SOAP API. The SOAP API provides an advanced interface to USAePay that allows merchants and resellers to access a wide range of functionality. This API requires a little more expertise than our simpler PHP Library for the Transaction API. If you are only looking to process transactions, we recommend that you use the PHP Library instead.
The official Pear repository includes a fairly full-featured Soap library written in PHP. Since it is written in PHP, it does not require any special privileges to install on your web server. See PEAR::Soap for more information.
Using PEAR::Soap
Step 1: Including the SOAP library
Including the SOAP library Example
<?php
require_once 'SOAP/Base.php';
require_once 'SOAP/Client.php';
?>
If you have installed the PEAR::Soap library in the standard location, you should be able to use the code to the right. Otherwise, make sure to either add the library to your include path or provide the full path to the library files.
Step 2: Instantiating $client
Instantiating $client Example
<?php
//for live server use 'www' for test server use 'sandbox'
$wsdl='https://www.usaepay.com/soap/gate/3213EA2A/usaepay.wsdl';
// instantiate SOAP_Client object as $client
$client = new SOAP_Client($wsdl);
?>
The first step is to instantiate the SOAP_Client object. In the SOAP example provided on this site, we use $client for this object.
Step 3: Building Security $token
Building Security $token Example
<?php
$sourcekey = 'yQbOFkmykeygoeshere3Lc9PH1l14';
$pin = '1234';
// generate random seed value
$seed=time() . rand();
// make hash value using sha1 function
$clear= $sourcekey . $seed . $pin;
$hash=sha1($clear);
// assembly ueSecurityToken as an array
$token=array(
'SourceKey'=>$sourcekey,
'PinHash'=>array(
'Type'=>'sha1',
'Seed'=>$seed,
'HashValue'=>$hash
),
'ClientIP'=>$_SERVER['REMOTE_ADDR'];
);
?>
The ueSecurityToken object is used to securely identify the merchant to the gateway. To build a token, you will need the merchant's Source Key and Pin. The source key is created by the merchant in the Merchant Console under the Settings - API Keys screen. Many of the methods in the SOAP API require the use of a PIN, and it is recommended that you always use a PIN. The merchant assigns the PIN when creating the source key.
Examples
The majority of examples listed in the documentation as PHP5 will work with either the built-in Soap client, or the Pear Library. In cases where different syntax is required for the Pear library, a separate example is required.
Visual Basic .Net
Adding a Web Reference
Step 1: Generate a WSDL
For testing on sandbox you can use:
https://sandbox.usaepay.com/soap/gate/15E7FB61/usaepay.wsdl
but it is recommend that you generate your own WSDL link in the Developer's Center.
Step 2: Add WSDL to the Project in Visual Studio:
In the Solution Explorer, select the project that will be using the web service. Right-click on the project and choose Add Web Reference and a dialog box will open.
Populate the URL field with your USAePay generated WSDL link. Click Go.
Step 3: Change Web Reference name to "usaepay":
A security warning will appear, click Yes and change the Web Reference name to:
usaepay
Then click Add Reference to confirm.
Once complete, you have now added a web reference called usaepay to your project.
Using the Web Reference
To use the USAePay web reference, you must generate a token. The token authenticates your application to the gateway. This requires generating an MD5 hash value. The following steps walk through the process of creating this token. Once the token is created, running specific methods is fairly easy. For examples of a specific methods, please refer to the examples provide on each method page.
Step 1: Including Required Imports
Required Imports Example
Imports System
Imports System.Web
Imports System.IO
Imports System.Security.Cryptography
Imports System.Text
The generation of MD5 hash requires some .NET libraries be imported into your code. Typically these import statements will go at the top of the your code.
Step 2: Instantiating the Client
Instantiating $client Example
Dim client As New usaepay.usaepayService 'usaepay is the name of your Web Reference
The next step is to instantiate the client object. In the soap examples provided on this site, we use the variable client for this object.
Step 3: Set a Proxy Server (if needed)
Setting a Proxy Server Example
Dim proxycreds As New System.Net.NetworkCredential("user", "password", "Domain")
Dim proxy As New System.Net.WebProxy("127.0.0.1", 80)
proxy.Credentials = proxycreds
client.Proxy = proxy
If your network requires you to use a proxy server, the next step is to reference the proxy server. If you do not have a proxy server, skip this step.
Step 4a: Building Security Token
Building Security $token Example
Dim token As New usaepay.ueSecurityToken
token.SourceKey = "ENTER_SOURCE_KEY_HERE"
token.ClientIP = "127.0.0.1"
token.PinHash = New usaepay.ueHash
token.PinHash.Seed = "5678" 'Hard coded seed for easy troubleshooting
token.PinHash.Type = "md5" 'Type of encryption
Dim prehashvalue As String
prehashvalue = token.SourceKey & token.PinHash.Seed & "1234" 'Put together the pieces
token.PinHash.HashValue = Me.GenerateHash(prehashvalue) 'Pass the prehashvalue to a GenerateHash function
The ueSecurityToken object is used to securely identify the merchant to the gateway. To build a token, you will need the merchant's Source Key and Pin.
The source key is created by the merchant in the Merchant Console under the Settings - API Keys screen. Many of the methods in the SOAP API require the use of a PIN, and it is recommended that you always use a PIN. The merchant assigns the PIN when creating the source key.
Step 4b: Generating a Hash
Generate Hash Example
Private Function GenerateHash(ByVal SourceText As String) As String
'Instantiate an MD5 Provider object
Dim md5 As New MD5CryptoServiceProvider
'Compute the hash value from the source
Dim ByteHash() As Byte = md5.ComputeHash(Encoding.Default.GetBytes(SourceText))
'Instantiate a StringBuilder object
Dim sb As New StringBuilder
'Repack binary hash as hex
For c As Integer = 0 To ByteHash.Length - 1
sb.AppendFormat("{0:x2}", ByteHash(c))
Next c
'Return the hex hash
Return sb.ToString
End Function
The code you use to build a security token expects a GenerateHash method to be present in your class. Copy and paste the function to the right into your class.
Handling Events
Example Code
Private WithEvents client As usaepay.usaepayService
Private Sub handleStatusUpdate(ByVal sender, ByVal ev As usaepay.addCustomerCompletedEventArgs) Handles client.addCustomerCompleted
MsgBox("Customer added!")
End Sub
The visual studio webservice implementation allows you to subscribe to a "completed" event that will be raised when a soap call completes. The following code demonstrates how to subscribe to the addCustomerCompleted event:
Additional Help
For questions, please email devsupport@usaepay.com
Visual Basic 2010 Guide
Adding a Web Reference
Step 1: Generate a WSDL
For testing on sandbox you can use:
https://sandbox.usaepay.com/soap/gate/15E7FB61/usaepay.wsdl
but it is recommend that you generate your own WSDL link in the Developer's Center.
Step 2: Add WSDL to the Project in Visual Studio:
In the Solution Explorer, select the project that will be using the web service. Right-click on the project and choose Add Service Reference and a dialog box will open.
Populate the URL field with your USAePay generated WSDL link. Click Go.
Step 3: Change Service Reference name to "usaepay":
Change the Namespace field to:
usaepay
Then click OK to confirm
Once complete, you have now added a service reference called usaepay to your project.
Using the Web Service Reference
To use the USAePay web reference, you must generate a token. The token authenticates your application to the gateway. This requires generating an MD5 hash value. The following steps walk through the process of creating this token. Once the token is created, running specific methods is fairly easy. For examples of specific methods, please refer to the examples provided on each method's page.
Step 1: Including Required Imports
Required Imports Example
Imports System
Imports System.Web
Imports System.IO
Imports System.Security.Cryptography
Imports System.Text
The generation of an MD5 hash value requires that you import some .NET libraries into your code. Typically these import statements will go at the top of the your code.
Step 2: Instantiating the Client
Instantiating $client Example
Dim client As New usaepay.ueSoapServerPortTypeClient 'usaepay' is the name of your Web Reference
The next step is to instantiate the client object. In the soap examples provided on this site, we use the variable "client" for this object.
Step 3: Setting a Proxy Server (if needed)
Setting a Proxy Server Example
Dim proxycreds As New System.Net.NetworkCredential("user", "password", "Domain")
Dim proxy As New System.Net.WebProxy("127.0.0.1", 80)
proxy.Credentials = proxycreds
client.Proxy = proxy
If your network requires you to use a proxy server, the next step is to reference the proxy server. If you do not have a proxy server, skip this step.
Step 4a: Building Security Token
Building Security $token Example
Dim token As New usaepay.ueSecurityToken
token.SourceKey = "P11PON_ENTER_SOURCE_KEY_HERE_KSQr1VT81"
token.ClientIP = "127.0.0.1"
token.PinHash = New usaepay.ueHash
token.PinHash.Seed = "5678" 'Hard coded seed for easy troubleshooting
token.PinHash.Type = "md5" 'Type of encryption
Dim prehashvalue As String
prehashvalue = token.SourceKey & token.PinHash.Seed & "1234" 'Put together the pieces
token.PinHash.HashValue = Me.GenerateHash(prehashvalue) 'Pass the prehashvalue to a GenerateHash function
The ueSecurityToken object is used to securely identify the merchant to the gateway. To build a token, you will need the merchant's Source Key and Pin.
The source key is created by the merchant in the Merchant Console under the Settings - API Keys screen. Many of the methods in the SOAP API require the use of a PIN, and it is recommended that you always use a PIN. The merchant assigns the PIN when creating the source key.
Step 4b: Generating a Hash
Generate Hash Example
Private Function GenerateHash(ByVal SourceText As String) As String
'Instantiate an MD5 Provider object
Dim md5 As New MD5CryptoServiceProvider
'Compute the hash value from the source
Dim ByteHash() As Byte = md5.ComputeHash(Encoding.Default.GetBytes(SourceText))
'Instantiate a StringBuilder object
Dim sb As New StringBuilder
'Repack binary hash as hex
For c As Integer = 0 To ByteHash.Length - 1
sb.AppendFormat("{0:x2}", ByteHash(c))
Next c
'Return the hex hash
Return sb.ToString
End Function
The code you use to build a security token expects a "GenerateHash" method to be present in your class. Copy and paste the function to the right into your class.
Handling Events
Example Code
Private WithEvents client As usaepay.usaepayService
Private Sub handleStatusUpdate(ByVal sender, ByVal ev As usaepay.addCustomerCompletedEventArgs) Handles client.addCustomerCompleted
MsgBox("Customer added!")
End Sub
The visual studio webservice implementation allows you to subscribe to a "completed" event that will be raised when a soap call completes. The following code demonstrates how to subscribe to the addCustomerCompleted event:
Additional Help
For questions, please email devsupport@usaepay.com
C Sharp
Adding a Web Reference
Step 1: Generate a WSDL
For testing on sandbox you can use:
https://sandbox.usaepay.com/soap/gate/15E7FB61/usaepay.wsdl
but it is recommend that you generate your own WSDL link in the Developer's Center.
Step 2: Add WSDL to the Project in Visual Studio:
In the Solution Explorer, select the project that will be using the web service. Right-click on the project and choose Add Web Reference and a dialog box will open.
Populate the URL field with your USAePay generated WSDL link. Click Go.
A security warning will appear, click Yes and change the Web Reference name to:
usaepay
Then click Add Reference to confirm.
Once complete, you have now added a web reference called usaepay to your project.
Using the Web Reference
To use the USAePay web reference, you must generate a token. The token authenticates your application to the gateway. This requires generating an MD5 hash value. The following steps walk through the process of creating this token. Once the token is created, running specific methods is fairly easy. For examples of a specific methods, please refer to the examples provide on each method page.
Step 1: Including Required Headers
Required Headers Example
using System;
using System.Web;
using System.Security.Cryptography;
using System.Text;
The generation of MD5 hash requires some .NET libraries be imported into your code. Typically these using statements will go at the top of the your code.
Step 2: Instantiating the Client
Instantiating $client Example
usaepay.usaepayService client = new usaepayService(); //usaepay is the name of your Web Reference
The next step is to instantiate the client object. In the soap examples provided on this site, we use the variable client for this object.
Step 3: Set a Proxy Server (if needed)
Setting a Proxy Server Example
System.Net.NetworkCredential proxycreds = new System.Net.NetworkCredential("user", "password");
System.Net.WebProxy proxy = new System.Net.WebProxy("127.0.0.1", 80); //address of proxy server
proxy.Credentials = proxycreds;
client.Proxy = proxy;
If your network requires you to use a proxy server, the next step is to reference the proxy server. If you do not have a proxy server, skip this step.
Step 4a: Building Security Token
Building Security $token Example
usaepay.ueSecurityToken token = new usaepay.ueSecurityToken();
token.SourceKey = "P11PON_ENTER_SOURCE_KEY_HERE_KSQr1VT81";
token.ClientIP = "11.22.33.44"; // IP address of end user (if applicable)
string pin = "1234"; // pin assigned to source
usaepay.ueHash hash = new usaepay.ueHash();
hash.Type = "md5"; // Type of encryption
hash.Seed = Guid.NewGuid().ToString(); // unique encryption seed
string prehashvalue = string.Concat(token.SourceKey, hash.Seed, pin); // combine data into single string
hash.HashValue = GenerateHash(prehashvalue); // generate hash
token.PinHash = hash; // add hash value to token
The ueSecurityToken object is used to securely identify the merchant to the gateway. To build a token, you will need the merchant's Source Key and Pin.
The source key is created by the merchant in the Merchant Console under the Settings - API Keys screen. Many of the methods in the SOAP API require the use of a PIN, and it is recommended that you always use a PIN. The merchant assigns the PIN when creating the source key.
Step 4b: Generating a Hash
Generate Hash Example
private static string GenerateHash(string input)
{
// Create a new instance of the MD5CryptoServiceProvider object.
MD5 md5Hasher = MD5.Create();
// Convert the input string to a byte array and compute the hash.
byte[] data = md5Hasher.ComputeHash(Encoding.Default.GetBytes(input));
// Create a new Stringbuilder to collect the bytes
// and create a string.
StringBuilder sBuilder = new StringBuilder();
// Loop through each byte of the hashed data
// and format each one as a hexadecimal string.
for (int i = 0; i < data.Length; i++)
{
sBuilder.Append(data[i].ToString("x2"));
}
// Return the hexadecimal string.
return sBuilder.ToString();
}
The above code expects a GenerateHash method to be present in your class. Copy and paste the function below into your class.
Step 5: Calling Soap Method
Call Method Example Code
try
{
// close current open batch
result = client.closeBatch(token, "0");
if (result) MessageBox.Show("Batch closed successfully");
else MessageBox.Show("Batch failed to close");
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
Now that you have a security token created you can make calls to the soap methods listed in the api. For example, to close the currently open credit credit card batch:
Sample Code
The above link is a zip file containing a Visual Studio project that provides some basic soap examples. To use the example project you must generate a source key on sandbox. If you do not have a sandbox account please log into the Developer's Center and request a test account. Examples can be found on many of the method and object documentation pages.
Additional Help
For questions, please email devsupport@usaepay.com
Java JAX-WS
The following guide demonstrates how to use the USAePay-jaxws.jar package. This package contains a helper class for easily generating security tokens, classes for all USAePay soap objects and a client service class for calling soap methods.
Downloads
| File | Version | Release Date | Description |
|---|---|---|---|
| usaepayapi-jaxws-1.6.4.zip | 1.6.4 | 6/2/15 | Library for Live/Production |
| usaepayapi-jaxws-1.6.4.jar.zip | 1.6.4 | 6/2/15 | Library for Sandbox |
Using Library
Step 1: Import Classes
Import Classes Example
import com.usaepay.api.jaxws.*;
In classes that are going to use the USAePay soap methods or object, you need to import the appropriate classes from com.usaepay.api.jaxws package. The following will import all usaepay objects at once:
Step 2a: Instantiating the Client
Instantiating $client Example
// Instantiate client for production
UeSoapServerPortType client = usaepay.getClient();
All calls to the USAePay soap servers are handled by a client object of type UeSoapServerPortType. There are two ways to instantiate the client object. To instantiate a client for use with the main production servers, use this example.
Step 2b: Specify Server
Specify Server Example
// Instantiate client for sandbox
UeSoapServerPortType client = usaepay.getClient("sandbox.usaepay.com");
Alternately, you can specify a server hostname, which will allow you to setup a connection to the sandbox server for testing or a backup datacenter (see the high availability programming guide).
Step 3: Building Security Token
Building Security $token Example
UeSecurityToken token = usaepay.getToken(
"_Z0ji6VHHIzMR99PMgaf91FZxwC630mp", // source key. Make sure to use your source key here
"1234", // source pin (if assigned by merchant)
"127.0.0.1" // IP address of end client (if applicable)
);
A token object (of type ueSecurityToken) is required by all SOAP methods in the USAePay API. It is used to identify the merchant.
Step 4: Calling a SOAP Method
Call Method Example Code
// instantiate TransactionRequestObject
TransactionRequestObject params = new TransactionRequestObject();
// set card holder name
params.setAccountHolder("Test Joe");
// instantiate and populate transaction details
TransactionDetail details = new TransactionDetail();
details.setAmount(22.34);
details.setDescription("My Test Sale");
details.setInvoice("119891");
params.setDetails(details);
// instantiate and populate credit card data
CreditCardData ccdata = new CreditCardData();
ccdata.setCardNumber("4111111111111111");
ccdata.setCardExpiration("0919");
params.setCreditCardData(ccdata);
// instantiate and populate CustomFileds
// This example shows how to set gateway timeout
FieldValueArray FieldArray = new FieldValueArray();
FieldValue field1 = new FieldValue();
field1.setField("UMtimeout");
field1.setValue("1");
FieldArray.getFieldValue().add(field1);
params.setCustomFields(FieldArray);
// instantiate and populate LineItem
LineItemArray itemArray = new LineItemArray();
LineItem item1 = new LineItem();
item1.setProductName("test");
item1.setDescription("testdesc");
item1.setSKU("4214124");
item1.setUnitPrice("2");
item1.setQty("5");
itemArray.getItem().add(item1);
LineItem item2 = new LineItem();
item2.setProductName("test2");
item2.setDescription("testdesc2");
item2.setSKU("5326236");
item2.setUnitPrice("3");
item2.setQty("5");
itemArray.getItem().add(item2);
params.setLineItems(itemArray);
// Create response object
TransactionResponse response;
// run sale
response = client.runSale(token, params);
// Display response
System.out.println("Response: " + response.getResult() + " RefNum: " + response.getRefNum()
+ " Error: " + response.getError());
} catch (Exception e) {
System.out.println("Soap Exception: " + e.getMessage());
Soap methods are called using the client object. This is an example for calling the runSale method. For further examples, see the soap api documentation.
Additional Help
For questions, please email devsupport@usaepay.com
Ruby
Downloads
You can download the files below or create them by running the command:
wsdl2ruby.rb --wsdl https://www.usaepay.com/soap/gate/*********/usaepay.wsdl --type client
for Sandbox Server use Sandbox wsdl link. You can generate a link in the Developer's Center.
| File | Version | Release Date | Description |
|---|---|---|---|
| Download usaepay_ruby_live.zip | 1.0.0 | 3/21/11 | Library for Live/Production |
| Download usaepay_ruby_sandbox.zip | 1.0.0 | 3/21/11 | Library for Sandbox |
Step 1: Import Classes
Import Classes Example
require 'usaepayDriver'
In classes that are going to use the USAePay SOAP methods or object, you need to include the appropriate classes. This example will import all usaepay objects at once.
If you place files in another directory, you should specify the correct path to:
usaepayDriver.rb
Step 2: Instantiate Client Object
Instantiating $client Example
# Instantiate client
@client=UeSoapServerPortType.new
All calls to the USAePay soap servers are handled by a client object of type UeSoapServerPortType.
Step 3: Building Security Token
Building Security $token Example
# Create security token
require 'digest'
def getToken(key,pin)
token=UeSecurityToken.new
token.clientIP = "123.123.123.123"
hash=UeHash.new
t=Time.now
seed = "#{t.year}#{t.month}#{t.day}#{t.hour}#{rand(1000)}"
prehash = "#{key}#{seed}#{pin.to_s.strip}"
hash.seed=seed
hash.type="sha1"
hash.hashValue=Digest::SHA1.hexdigest(prehash).to_s
token.pinHash = hash
token.sourceKey=key
return token
end
token=getToken("YOUR_SOURCE KEY","1234")
A token object (of type ueSecurityToken) is required by all SOAP methods in the USAePay API. It is used to identify the merchant.
Step 4: Calling a SOAP Method
Call Method Example Code
request=TransactionRequestObject.new
request.accountHolder="TesterJones"
request.command="sale"
details=TransactionDetail.new
details.amount="1.00"
details.description="example sale"
request.details=details
creditcard=CreditCardData.new
creditcard.avsStreet="123 main st."
creditcard.avsZip="90010"
creditcard.cardNumber="4444555566667779"
creditcard.cardExpiration="1212"
request.creditCardData=creditcard
@client=UeSoapServerPortType.new
response=@client.runTransaction(token,request)
p "RefNum:#{response.refNum}"
SOAP methods are called using the client object. Below is an example for calling the runTransaction method. For further examples, see the SOAP API documentation.
Troubleshooting
Uninitialized constant SOAP::Mapping::EncodedRegistry
Make sure that you have soap4r installed or install it by running :
gem install soap4r --include-dependencies
and add the following to /config/environment.rb:
require 'rubygems'
gem 'soap4r'
Additional Help
For questions, please email devsupport@usaepay.com
Transaction Methods
Use the transactions methods to process credit card, debit card, and ACH transactions including:
| Sale | Refund/Void | Queue/Capture/Void | Transaction API |
|---|---|---|---|
| runSale | runCredit | postAuth | runTransaction |
| runAuthOnly | runCheckCredit | queueTransaction | runTransactionAPI |
| runCheckSale | runQuickCredit | captureTransaction | |
| runQuickSale | refundTransaction | overrideTransaction | |
| voidTransaction |
Sales and Authorizations
This section will show you how to initiate sale and authonly transactions. Please refer to the typical use cases for specific implementation details.
runSale
Example Request
<?php
try {
$Request=array(
'AccountHolder' => 'Tester Jones',
'Details' => array(
'Description' => 'Example Transaction',
'Amount' => '4.00',
'Invoice' => '44539'
),
'CreditCardData' => array(
'CardNumber' => '4444555566667779',
'CardExpiration' => '0919',
'AvsStreet' => '1234 Main Street',
'AvsZip' => '99281',
'CardCode' => '999'
)
);
$res=$client->runSale($token, $Request);
}
catch (SoapFault $e) {
echo $client->__getLastRequest();
echo $client->__getLastResponse();
die("QuickSale failed :" .$e->getMessage());
}
?>
try {
TransactionRequestObject params = new TransactionRequestObject();
// set card holder name
params.setAccountHolder("Test Joe");
// populate transaction details
TransactionDetail details = new TransactionDetail();
details.setAmount(22.34);
details.setDescription("My Test Sale");
details.setInvoice("119891");
params.setDetails(details);
// populate credit card data
CreditCardData ccdata = new CreditCardData();
ccdata.setCardNumber("4444555566667779");
ccdata.setCardExpiration("0919");
ccdata.setCardCode("999");
params.setCreditCardData(ccdata);
// Create request object
RunSale request = new RunSale();
request.setToken(token);
request.setParams(params);
// Create response object
TransactionResponse response;
// run sale
response = client.runSale(token, params);
System.out.println("Result: " + response.getResult());
} catch (Exception e) {
System.out.println("Soap Exception: " + e.getMessage());
}
Dim client As usaepay.usaepayService = New usaepay.usaepayService
Dim token As usaepay.ueSecurityToken
token = Me.CreateToken("714SSUxv1uohng2XkMJ7kLpETsu58G66", "1234")
Dim transaction As usaepay.TransactionRequestObject = New usaepay.TransactionRequestObject
transaction.CreditCardData = New usaepay.CreditCardData
transaction.CreditCardData.CardNumber = "4444555566667779"
transaction.CreditCardData.CardExpiration = "0919"
transaction.CreditCardData.CardCode = "999"
transaction.Details = New usaepay.TransactionDetail
transaction.Details.Amount = 9.02
transaction.Details.AmountSpecified = True
transaction.Details.Invoice = "434534"
transaction.Details.Description = "Example transaction"
Dim response As usaepay.TransactionResponse
response = client.runSale(token, transaction)
If response.ResultCode = "A" Then
MsgBox("Transaction Approved, Reference Number: " & response.RefNum & vbLf _
& "AVS Result: " & response.AvsResult)
ElseIf response.ResultCode = "D" Then
MsgBox("Transaction Declined, Reason: " & response.Error)
Else
MsgBox("Transaction Error, Reason: " & response.Error)
End If
usaepay.TransactionRequestObject tran = new usaepay.TransactionRequestObject();
tran.Details = new usaepay.TransactionDetail();
tran.Details.Amount = 1.00;
tran.Details.AmountSpecified = true;
tran.Details.Invoice = "1234";
tran.Details.Description = "Example Transaction";
tran.CreditCardData = new usaepay.CreditCardData();
tran.CreditCardData.CardNumber = "4444555566667779";
tran.CreditCardData.CardExpiration = "1219";
usaepay.TransactionResponse response = new usaepay.TransactionResponse();
try
{
response = client.runTransaction(token, tran);
if (response.ResultCode == "A")
{
MessageBox.Show(string.Concat("Transaction Approved, RefNum: ",
response.RefNum));
}
else
{
MessageBox.Show(string.Concat("Transaction Failed: ",
response.Error));
}
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="urn:usaepay"
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:runSale>
<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">58bdbfeb7c15078fa62291bd6a4473990dd50dd8</HashValue>
<Seed xsi:type="xsd:string">11139209200-test</Seed>
<Type xsi:type="xsd:string">sha1</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
</Token>
<Params xsi:type="ns1:TransactionRequestObject">
<AccountHolder xsi:type="xsd:string">Tester Jones</AccountHolder>
<BillingAddress xsi:type="ns1:Address">
<City xsi:type="xsd:string">Albany</City>
<Company xsi:type="xsd:string">testing</Company>
<Country xsi:type="xsd:string">Un</Country>
<FirstName xsi:type="xsd:string">SoapAPI</FirstName>
<LastName xsi:type="xsd:string">Testor</LastName>
<Phone xsi:type="xsd:string">5183310981</Phone>
<State xsi:type="xsd:string">NY</State>
<Street xsi:type="xsd:string">180 State st</Street>
<Street2 xsi:type="xsd:string">133 Lancaster st</Street2>
<Zip xsi:type="xsd:string">12210</Zip>
</BillingAddress>
<ClientIP xsi:type="xsd:string">123.123.123.123</ClientIP>
<Command xsi:type="xsd:string">sale</Command>
<CreditCardData xsi:type="ns1:CreditCardData">
<AvsStreet xsi:type="xsd:string">1234 Main Street</AvsStreet>
<AvsZip xsi:type="xsd:string">99281</AvsZip>
<CardCode xsi:type="xsd:string">123boatload1293</CardCode>
<CardExpiration xsi:type="xsd:string">1215</CardExpiration>
<CardNumber xsi:type="xsd:string">4444555566667779</CardNumber>
</CreditCardData>
<CustomerID xsi:type="xsd:string">123456</CustomerID>
<Details xsi:type="ns1:TransactionDetail">
<Amount xsi:type="xsd:double">22</Amount>
<Clerk xsi:type="xsd:string">John Doe</Clerk>
<Currency xsi:type="xsd:string">0</Currency>
<Description xsi:type="xsd:string">Example Transaction</Description>
<Discount xsi:type="xsd:double">10</Discount>
<Invoice xsi:type="xsd:string">44539</Invoice>
<OrderID xsi:type="xsd:string">12345</OrderID>
<PONum xsi:type="xsd:string">54321</PONum>
<Shipping xsi:type="xsd:double">2</Shipping>
<Subtotal xsi:type="xsd:double">12</Subtotal>
<Table xsi:type="xsd:string">1</Table>
<Tax xsi:type="xsd:double">10</Tax>
<Terminal xsi:type="xsd:string">15</Terminal>
<Tip xsi:type="xsd:double">8</Tip>
</Details>
<LineItems SOAP-ENC:arrayType="ns1:LineItem[1]" xsi:type="ns1:LineItemArray">
<item xsi:type="ns1:LineItem">
<SKU xsi:type="xsd:string">1234</SKU>
<ProductName xsi:type="xsd:string">Test Example</ProductName>
<Description xsi:type="xsd:string">Test</Description>
<UnitPrice xsi:type="xsd:string">19.99</UnitPrice>
<Qty xsi:type="xsd:string">9</Qty>
<Taxable xsi:type="xsd:boolean">true</Taxable>
</item>
</LineItems>
<ShippingAddress xsi:type="ns1:Address">
<City xsi:type="xsd:string">Los Angeles</City>
<Company xsi:type="xsd:string">Location 2</Company>
<Country xsi:type="xsd:string">Un</Country>
<FirstName xsi:type="xsd:string">Ship</FirstName>
<LastName xsi:type="xsd:string">Tome</LastName>
<Phone xsi:type="xsd:string">3133129163</Phone>
<State xsi:type="xsd:string">CA</State>
<Street xsi:type="xsd:string">9999 s sycamore</Street>
<Street2 xsi:type="xsd:string">9999 Lancaster st</Street2>
<Zip xsi:type="xsd:string">90036</Zip>
</ShippingAddress>
</Params>
</ns1:runSale>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example Response
<?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="urn:usaepay"
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:runSaleResponse>
<runSaleReturn xsi:type="ns1:TransactionResponse">
<AcsUrl xsi:type="xsd:string"></AcsUrl>
<AuthAmount xsi:type="xsd:double">22</AuthAmount>
<AuthCode xsi:type="xsd:string">036685</AuthCode>
<AvsResult xsi:type="xsd:string">Address: Match & 5 Digit Zip: Match</AvsResult>
<AvsResultCode xsi:type="xsd:string">YYY</AvsResultCode>
<BatchNum xsi:type="xsd:string">1</BatchNum>
<BatchRefNum xsi:type="xsd:string">197454</BatchRefNum>
<CardCodeResult xsi:type="xsd:string">No Match</CardCodeResult>
<CardCodeResultCode xsi:type="xsd:string">N</CardCodeResultCode>
<CardLevelResult xsi:type="xsd:string">Visa Traditional</CardLevelResult>
<CardLevelResultCode xsi:type="xsd:string">A</CardLevelResultCode>
<ConversionRate xsi:type="xsd:double">0</ConversionRate>
<ConvertedAmount xsi:type="xsd:double">0</ConvertedAmount>
<ConvertedAmountCurrency xsi:type="xsd:string">840</ConvertedAmountCurrency>
<CustNum xsi:type="xsd:string">0</CustNum>
<Error xsi:type="xsd:string">Approved</Error>
<ErrorCode xsi:type="xsd:integer">0</ErrorCode>
<isDuplicate xsi:type="xsd:boolean">false</isDuplicate>
<Payload xsi:type="xsd:string"></Payload>
<RefNum xsi:type="xsd:string">100103898</RefNum>
<Result xsi:type="xsd:string">Approved</Result>
<ResultCode xsi:type="xsd:string">A</ResultCode>
<Status xsi:type="xsd:string">Pending</Status>
<StatusCode xsi:type="xsd:string">P</StatusCode>
<VpasResultCode xsi:type="xsd:string"></VpasResultCode>
</runSaleReturn>
</ns1:runSaleResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Run a new sale transaction.
This method is equivalent to running the runTransaction method with the Command set to "Sale."
It will run a transaction charging a customer's credit card or checking account for the desired amount. If a mistake is made or a refund must be given you can use either the voidTransaction or runCredit method.
If the sale is for a customer whose information has been stored, you may use the runQuickSale method to avoid having to reenter all of the customer's information.
Related Methods
Syntax
TransactionResponse runSale ( ueSecurityToken Token, TransactionRequestObject Params )
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| %TransactionRequestObject% | Params | Transaction details from all fields of the transaction form. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| %TransactionResponse% | object | Returns a TransactionResponse object containing the results of the transaction and all relevant data. |
runAuthOnly
Example Request
<?php
try {
$Request=array(
'AccountHolder' => 'Tester Jones',
'Details' => array(
'Description' => 'Example Transaction',
'Amount' => '4.00',
'Invoice' => '44539'
),
'CreditCardData' => array(
'CardNumber' => '4444555566667779',
'CardExpiration' => '0919',
'AvsStreet' => '1234 Main Street',
'AvsZip' => '99281',
'CardCode' => '999'
)
);
$res=$client->runAuthOnly($token, $Request);
}
catch (SoapFault $e) {
echo $client->__getLastRequest();
echo $client->__getLastResponse();
die("QuickSale failed :" .$e->getMessage());
}
?>
try {
TransactionRequestObject params = new TransactionRequestObject();
// set card holder name
params.setAccountHolder("Test Joe");
// populate transaction details
TransactionDetail details = new TransactionDetail();
details.setAmount(22.34);
details.setDescription("My Test Sale");
details.setInvoice("119891");
params.setDetails(details);
// populate credit card data
CreditCardData ccdata = new CreditCardData();
ccdata.setCardNumber("4444555566667779");
ccdata.setCardExpiration("0919");
ccdata.setCardCode("999");
params.setCreditCardData(ccdata);
// Create request object
RunAuthOnly request = new RunAuthOnly();
request.setToken(token);
request.setParams(params);
// Create response object
TransactionResponse response;
// run sale
response = client.runAuthOnly(token, params);
System.out.println("Result: " + response.getResult());
} catch (Exception e) {
System.out.println("Soap Exception: " + e.getMessage());
}
Dim client As usaepay.usaepayService = New usaepay.usaepayService
Dim token As usaepay.ueSecurityToken
token = Me.CreateToken("714SSUxv1uohng2XkMJ7kLpETsu58G66", "1234")
Dim tran As usaepay.TransactionRequestObject = New usaepay.TransactionRequestObject
tran.CreditCardData = New usaepay.CreditCardData
tran.CreditCardData.CardNumber = "4444555566667779"
tran.CreditCardData.CardExpiration = "0919"
tran.CreditCardData.CardCode = "999"
tran.Details = New usaepay.TransactionDetail
tran.Details.Amount = 9.02
tran.Details.AmountSpecified = True
tran.Details.Invoice = "434534"
tran.Details.Description = "Example transaction"
Dim response As usaepay.TransactionResponse
response = client.runAuthOnly(token, tran)
If response.ResultCode = "A" Then
MsgBox("Transaction Approved, Refernce Number: " & response.RefNum)
ElseIf response.ResultCode = "D" Then
MsgBox("Transaction Declined, Reason: " & response.Error)
Else
MsgBox("Transaction Error, Reason: " & response.Error)
End If
usaepay.TransactionRequestObject tran = new usaepay.TransactionRequestObject();
tran.Command = "cc:authonly";
tran.Details = new usaepay.TransactionDetail();
tran.Details.Amount = 1.00;
tran.Details.AmountSpecified = true;
tran.Details.Invoice = "1234";
tran.Details.Description = "Example Transaction";
tran.CreditCardData = new usaepay.CreditCardData();
tran.CreditCardData.CardNumber = "4444555566667779";
tran.CreditCardData.CardExpiration = "1219";
usaepay.TransactionResponse response = new usaepay.TransactionResponse();
try
{
response = client.runTransaction(token, tran);
if (response.ResultCode == "A")
{
MessageBox.Show(string.Concat("Transaction Approved, RefNum: ",
response.RefNum));
}
else
{
MessageBox.Show(string.Concat("Transaction Failed: ",
response.Error));
}
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="urn:usaepay"
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:runAuthOnly>
<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">58bdbfeb7c15078fa62291bd6a4473990dd50dd8</HashValue>
<Seed xsi:type="xsd:string">11139209200-test</Seed>
<Type xsi:type="xsd:string">sha1</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
</Token>
<Params xsi:type="ns1:TransactionRequestObject">
<AccountHolder xsi:type="xsd:string">Tester Jones</AccountHolder>
<BillingAddress xsi:type="ns1:Address">
<City xsi:type="xsd:string">Albany</City>
<Company xsi:type="xsd:string">testing</Company>
<Country xsi:type="xsd:string">Un</Country>
<FirstName xsi:type="xsd:string">SoapAPI</FirstName>
<LastName xsi:type="xsd:string">Testor</LastName>
<Phone xsi:type="xsd:string">5183310981</Phone>
<State xsi:type="xsd:string">NY</State>
<Street xsi:type="xsd:string">180 State st</Street>
<Street2 xsi:type="xsd:string">133 Lancaster st</Street2>
<Zip xsi:type="xsd:string">12210</Zip>
</BillingAddress>
<ClientIP xsi:type="xsd:string">123.123.123.123</ClientIP>
<Command xsi:type="xsd:string">authonly</Command>
<CreditCardData xsi:type="ns1:CreditCardData">
<AvsStreet xsi:type="xsd:string">1234 Main Street</AvsStreet>
<AvsZip xsi:type="xsd:string">99281</AvsZip>
<CardCode xsi:type="xsd:string">123boatload1293</CardCode>
<CardExpiration xsi:type="xsd:string">1219</CardExpiration>
<CardNumber xsi:type="xsd:string">4444555566667779</CardNumber>
</CreditCardData>
<CustomerID xsi:type="xsd:string">123456</CustomerID>
<Details xsi:type="ns1:TransactionDetail">
<Amount xsi:type="xsd:double">22</Amount>
<Clerk xsi:type="xsd:string">John Doe</Clerk>
<Currency xsi:type="xsd:string">0</Currency>
<Description xsi:type="xsd:string">Example Transaction</Description>
<Discount xsi:type="xsd:double">10</Discount>
<Invoice xsi:type="xsd:string">44539</Invoice>
<OrderID xsi:type="xsd:string">12345</OrderID>
<PONum xsi:type="xsd:string">54321</PONum>
<Shipping xsi:type="xsd:double">2</Shipping>
<Subtotal xsi:type="xsd:double">12</Subtotal>
<Table xsi:type="xsd:string">1</Table>
<Tax xsi:type="xsd:double">10</Tax>
<Terminal xsi:type="xsd:string">15</Terminal>
<Tip xsi:type="xsd:double">8</Tip>
</Details>
<LineItems SOAP-ENC:arrayType="ns1:LineItem[1]" xsi:type="ns1:LineItemArray">
<item xsi:type="ns1:LineItem">
<SKU xsi:type="xsd:string">1234</SKU>
<ProductName xsi:type="xsd:string">Test Example</ProductName>
<Description xsi:type="xsd:string">Test</Description>
<UnitPrice xsi:type="xsd:string">19.99</UnitPrice>
<Qty xsi:type="xsd:string">9</Qty>
<Taxable xsi:type="xsd:boolean">true</Taxable>
</item>
</LineItems>
<ShippingAddress xsi:type="ns1:Address">
<City xsi:type="xsd:string">Los Angeles</City>
<Company xsi:type="xsd:string">Location 2</Company>
<Country xsi:type="xsd:string">Un</Country>
<FirstName xsi:type="xsd:string">Ship</FirstName>
<LastName xsi:type="xsd:string">Tome</LastName>
<Phone xsi:type="xsd:string">3133129163</Phone>
<State xsi:type="xsd:string">CA</State>
<Street xsi:type="xsd:string">9999 s sycamore</Street>
<Street2 xsi:type="xsd:string">9999 Lancaster st</Street2>
<Zip xsi:type="xsd:string">90036</Zip>
</ShippingAddress>
</Params>
</ns1:runAuthOnly>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example Response
<?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="urn:usaepay"
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:runAuthOnlyResponse>
<runAuthOnlyReturn xsi:type="ns1:TransactionResponse">
<AcsUrl xsi:type="xsd:string"></AcsUrl>
<AuthAmount xsi:type="xsd:double">0</AuthAmount>
<AuthCode xsi:type="xsd:string">036996</AuthCode>
<AvsResult xsi:type="xsd:string">Address: Match & 5 Digit Zip: Match</AvsResult>
<AvsResultCode xsi:type="xsd:string">YYY</AvsResultCode>
<BatchNum xsi:type="xsd:string">0</BatchNum>
<BatchRefNum xsi:type="xsd:string">197454</BatchRefNum>
<CardCodeResult xsi:type="xsd:string">No Match</CardCodeResult>
<CardCodeResultCode xsi:type="xsd:string">N</CardCodeResultCode>
<CardLevelResult xsi:type="xsd:string">Unknown Code</CardLevelResult>
<CardLevelResultCode xsi:type="xsd:string"></CardLevelResultCode>
<ConversionRate xsi:type="xsd:double">0</ConversionRate>
<ConvertedAmount xsi:type="xsd:double">0</ConvertedAmount>
<ConvertedAmountCurrency xsi:type="xsd:string">840</ConvertedAmountCurrency>
<CustNum xsi:type="xsd:string">0</CustNum>
<Error xsi:type="xsd:string">Approved</Error>
<ErrorCode xsi:type="xsd:integer">0</ErrorCode>
<isDuplicate xsi:type="xsd:boolean">true</isDuplicate>
<Payload xsi:type="xsd:string"></Payload>
<RefNum xsi:type="xsd:string">100104998</RefNum>
<Result xsi:type="xsd:string">Approved</Result>
<ResultCode xsi:type="xsd:string">A</ResultCode>
<Status xsi:type="xsd:string">Pending</Status>
<StatusCode xsi:type="xsd:string">P</StatusCode>
<VpasResultCode xsi:type="xsd:string"></VpasResultCode>
</runAuthOnlyReturn>
</ns1:runAuthOnlyResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Run an authorization only transaction.
This method is equivalent to running the runTransaction method with the Command set to "AuthOnly."
It will run an authorization check on a customer's credit card or checking account without actually charging the customer's account.
Related Methods
Syntax
TransactionResponse runAuthOnly ( ueSecurityToken Token, TransactionRequestObject Params )
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| %TransactionRequestObject% | Params | Transaction details from all fields of the transaction form. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| %TransactionResponse% | object | Returns a TransactionResponse object containing the results of the transaction and all relevant data. |
runCheckSale
Example Request
<?php
try {
$Request=array(
'AccountHolder' => 'Tester Jones',
'Details' => array(
'Description' => 'Example Transaction',
'Amount' => '4.99',
'Invoice' => '44539'
),
'CheckData' => array(
'CheckNumber' => '1234',
'Routing' => '123456789',
'Account' => '11111111',
'AccountType' => 'Savings',
'DriversLicense' => '34521343',
'DriversLicenseState' => 'CA',
'RecordType' => 'PPD'
)
);
$res=$client->runCheckSale($token, $Request);
}
catch (SoapFault $e) {
echo $client->__getLastRequest();
echo $client->__getLastResponse();
die("runCheckSale failed :" .$e->getMessage());
}
?>
try {
TransactionRequestObject params = new TransactionRequestObject();
//set account holder name
params.setAccountHolder("Test Joe");
// populate transaction details
TransactionDetail details = new TransactionDetail();
details.setAmount(22.34);
details.setDescription("My Test Sale");
details.setInvoice("119891");
params.setDetails(details);
// populate credit card data
CheckData checkdata = new CheckData();
checkdata.setRouting("123123123");
checkdata.setAccount("321321");
params.setCheckData(checkdata);
// Create response object
TransactionResponse response;
// run sale
response = client.runCheckSale(token, params);
System.out.println("Response: " + response.getResult() + " RefNum: " + response.getRefNum());
} catch (Exception e) {
System.out.println("Soap Exception: " + e.getMessage());
}
Dim client As usaepay.usaepayService = New usaepay.usaepayService
Dim token As usaepay.ueSecurityToken
token = Me.CreateToken("714SSUxv1uohng2XkMJ7kLpETsu58G66", "1234")
Dim transaction As usaepay.TransactionRequestObject = New usaepay.TransactionRequestObject
transaction.CheckData = New usaepay.CheckData
transaction.CheckData.Account = "1112223333"
transaction.CheckData.Routing = "123456789"
transaction.CheckData.DriversLicense = "D5555555"
transaction.CheckData.DriversLicenseState = "CA"
transaction.Details = New usaepay.TransactionDetail
transaction.Details.Amount = "1.00"
transaction.Details.AmountSpecified = True
transaction.Details.Invoice = "55555"
transaction.Details.Description = "Test Check Sale"
transaction.AccountHolder = "Test Guy"
Dim response As usaepay.TransactionResponse = New usaepay.TransactionResponse
response = client.runCheckSale(token, transaction)
If response.ResultCode = "A" Then
MsgBox("Transaction Approved, Reference Number: " & response.RefNum)
ElseIf response.ResultCode = "D" Then
MsgBox("Transaction Declined, Reason: " & response.Error)
Else
MsgBox("Transaction Error, Reason: " & response.Error)
End If
usaepay.TransactionRequestObject tran = new usaepay.TransactionRequestObject();
tran.Details = new usaepay.TransactionDetail();
tran.Details.Amount = 1.00;
tran.Details.AmountSpecified = true;
tran.Details.Invoice = "1234";
tran.Details.Description = "Sample Check Sale";
tran.CheckData = new usaepay.CheckData();
tran.CheckData.Account = "1112223333";
tran.CheckData.Routing = "123456789";
tran.CheckData.DriversLicense = "D5555555";
tran.CheckData.DriversLicenseState = "CA";
tran.AccountHolder = "Test Guy";
usaepay.TransactionResponse response = new usaepay.TransactionResponse();
try
{
response = client.runCheckSale(token, tran);
if (response.ResultCode == "A")
{
MessageBox.Show(string.Concat("Transaction Approved, RefNum: ",
response.RefNum));
}
else
{
MessageBox.Show(string.Concat("Transaction Failed: ",
response.Error));
}
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="urn:usaepay"
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:runCheckSale>
<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">58bdbfeb7c15078fa62291bd6a4473990dd50dd8</HashValue>
<Seed xsi:type="xsd:string">11139209200-test</Seed>
<Type xsi:type="xsd:string">sha1</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
</Token>
<Params xsi:type="ns1:TransactionRequestObject">
<AccountHolder xsi:type="xsd:string">Tester Jones</AccountHolder>
<BillingAddress xsi:type="ns1:Address">
<City xsi:type="xsd:string">Albany</City>
<Company xsi:type="xsd:string">testing</Company>
<Country xsi:type="xsd:string">Un</Country>
<FirstName xsi:type="xsd:string">SoapAPI</FirstName>
<LastName xsi:type="xsd:string">Testor</LastName>
<Phone xsi:type="xsd:string">5183310981</Phone>
<State xsi:type="xsd:string">NY</State>
<Street xsi:type="xsd:string">180 State st</Street>
<Street2 xsi:type="xsd:string">133 Lancaster st</Street2>
<Zip xsi:type="xsd:string">12210</Zip>
</BillingAddress>
<CheckData xsi:type="ns1:CheckData">
<Account xsi:type="xsd:string">11111111</Account>
<AccountType xsi:type="xsd:string">Savings</AccountType>
<CheckNumber xsi:type="xsd:integer">1234</CheckNumber>
<DriversLicense xsi:type="xsd:string">34521343</DriversLicense>
<DriversLicenseState xsi:type="xsd:string">CA</DriversLicenseState>
<RecordType xsi:type="xsd:string">PPD</RecordType>
<Routing xsi:type="xsd:string">123456789</Routing>
</CheckData>
<ClientIP xsi:type="xsd:string">123.123.123.123</ClientIP>
<Command xsi:type="xsd:string">check</Command>
<CustomerID xsi:type="xsd:string">123456</CustomerID>
<Details xsi:type="ns1:TransactionDetail">
<Amount xsi:type="xsd:double">22</Amount>
<Clerk xsi:type="xsd:string">John Doe</Clerk>
<Currency xsi:type="xsd:string">0</Currency>
<Description xsi:type="xsd:string">Example Transaction</Description>
<Discount xsi:type="xsd:double">10</Discount>
<Invoice xsi:type="xsd:string">44539</Invoice>
<OrderID xsi:type="xsd:string">12345</OrderID>
<PONum xsi:type="xsd:string">54321</PONum>
<Shipping xsi:type="xsd:double">2</Shipping>
<Subtotal xsi:type="xsd:double">12</Subtotal>
<Table xsi:type="xsd:string">1</Table>
<Tax xsi:type="xsd:double">10</Tax>
<Terminal xsi:type="xsd:string">15</Terminal>
<Tip xsi:type="xsd:double">8</Tip>
</Details>
<LineItems SOAP-ENC:arrayType="ns1:LineItem[1]" xsi:type="ns1:LineItemArray">
<item xsi:type="ns1:LineItem">
<SKU xsi:type="xsd:string">1234</SKU>
<ProductName xsi:type="xsd:string">Test Example</ProductName>
<Description xsi:type="xsd:string">Test</Description>
<UnitPrice xsi:type="xsd:string">19.99</UnitPrice>
<Qty xsi:type="xsd:string">9</Qty>
<Taxable xsi:type="xsd:boolean">true</Taxable>
</item>
</LineItems>
<ShippingAddress xsi:type="ns1:Address">
<City xsi:type="xsd:string">Los Angeles</City>
<Company xsi:type="xsd:string">Location 2</Company>
<Country xsi:type="xsd:string">Un</Country>
<FirstName xsi:type="xsd:string">Ship</FirstName>
<LastName xsi:type="xsd:string">Tome</LastName>
<Phone xsi:type="xsd:string">3133129163</Phone>
<State xsi:type="xsd:string">CA</State>
<Street xsi:type="xsd:string">9999 s sycamore</Street>
<Street2 xsi:type="xsd:string">9999 Lancaster st</Street2>
<Zip xsi:type="xsd:string">90036</Zip>
</ShippingAddress>
</Params>
</ns1:runCheckSale>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example Response
<?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="urn:usaepay"
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:runCheckSaleResponse>
<runCheckSaleReturn xsi:type="ns1:TransactionResponse">
<AcsUrl xsi:type="xsd:string"></AcsUrl>
<AuthAmount xsi:type="xsd:double">0</AuthAmount>
<AuthCode xsi:type="xsd:string">TM2C2B</AuthCode>
<AvsResult xsi:type="xsd:string">No AVS response (Typically no AVS data sent or swiped transaction)
</AvsResult>
<AvsResultCode xsi:type="xsd:string"></AvsResultCode>
<BatchNum xsi:type="xsd:string">151117</BatchNum>
<BatchRefNum xsi:type="xsd:string">0</BatchRefNum>
<CardCodeResult xsi:type="xsd:string">No CVV2/CVC data available for transaction.</CardCodeResult>
<CardCodeResultCode xsi:type="xsd:string"></CardCodeResultCode>
<CardLevelResult xsi:type="xsd:string">Unknown Code</CardLevelResult>
<CardLevelResultCode xsi:type="xsd:string"></CardLevelResultCode>
<ConversionRate xsi:type="xsd:double">0</ConversionRate>
<ConvertedAmount xsi:type="xsd:double">0</ConvertedAmount>
<ConvertedAmountCurrency xsi:type="xsd:string">840</ConvertedAmountCurrency>
<CustNum xsi:type="xsd:string">0</CustNum>
<Error xsi:type="xsd:string"></Error>
<ErrorCode xsi:type="xsd:integer">0</ErrorCode>
<isDuplicate xsi:type="xsd:boolean">false</isDuplicate>
<Payload xsi:type="xsd:string"></Payload>
<RefNum xsi:type="xsd:sting">102131500</RefNum>
<Result xsi:type="xsd:string">Approved</Result>
<ResultCode xsi:type="xsd:string">A</ResultCode>
<Status xsi:type="xsd:string">Pending</Status>
<StatusCode xsi:type="xsd:string">P</StatusCode>
<VpasResultCode xsi:type="xsd:string"></VpasResultCode>
</runCheckSaleReturn>
</ns1:runCheckSaleResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Run a new check sale transaction.
This method is equivalent to running the runTransaction method with the Command set to Check:Sale. Instead of charging a customer's credit card, this method uses the customer's bank information (bank routing number and customer account number) to electronically deduct the required funds from the customer's checking account.
It will run a transaction debit a customer's checking or savings account via ACH for the desired amount. If a mistake is made or a refund must be given you can use either the overrideTransaction, voidTransaction, refundTransaction or runCheckCredit method.
If the sale is for a customer whose information has been stored, you may use the runCustomerTransaction method to avoid having to reenter all of the customer's information.
Related Methods
Syntax
TransactionResponse runSale ( ueSecurityToken Token, TransactionRequestObject Params )
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| %TransactionRequestObject% | Params | Transaction details from all fields of the transaction form. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| %TransactionResponse% | object | Returns a TransactionResponse object containing the results of the transaction and all relevant data. |
runQuickSale
Example Request
<?php
try {
$refnum="1nfmkr4rsmtxhm5";
$details=array(
"Amount"=>4.00,
"Invoice"=>1234,
"Description"=>"Test Transaction",
"PONum"=>"",
"OrderID"=>1234,
"Tax"=>0,
"Tip"=>0,
"NonTax"=>false,
"Shipping"=>0,
"Discount"=>0,
"Subtotal"=>4.00
);
print_r($client->runQuickSale($token,$refnum, $details, true));
}
catch(SoapFault $e) {
echo $e->getMessage();
echo "\n\nRequest: " . $client->__getLastRequest();
echo "\n\nResponse: " . $client->__getLastResponse();
}
?>
try {
//Set RefNum to the transaction refference number
//you want to run a quick sale on
BigInteger RefNum = new BigInteger("123456789");
//populate transaction details
TransactionDetail details = new TransactionDetail();
details.setAmount(22.34);
details.setDescription("QuickSale");
details.setInvoice("119891");
// Create response object
TransactionResponse response;
response = client.runQuickSale(token, RefNum, details, false);
System.out.println("Response: " + response.getResult());
System.out.println("RefNum: " + response.getRefNum());
} catch (Exception e) {
System.out.println("Soap Exception: " + e.getMessage());
}
Dim client As usaepay.usaepayService = New usaepay.usaepayService
Dim token As usaepay.ueSecurityToken
token = Me.CreateToken("714SSUxv1uohng2XkMJ7kLpETsu58G66", "1234")
Dim refnum As Integer
Dim details As usaepay.TransactionDetail = New usaepay.TransactionDetail
Dim authonly As Boolean
refnum = "46990567"
details.Amount = "34.50"
details.AmountSpecified = True
details.Description = "Example QuickSale"
details.Invoice = "123456"
authonly = False
Dim response As usaepay.TransactionResponse
response = client.runQuickSale(token, refnum, details, authonly)
If response.ResultCode = "A" Then
MsgBox("Transaction Approved, Refernce Number: " & response.RefNum)
ElseIf response.ResultCode = "D" Then
MsgBox("Transaction Declined, Reason: " & response.Error)
Else
MsgBox("Transaction Error, Reason: " & response.Error)
End If
usaepay.TransactionDetail details = new usaepay.TransactionDetail();
string refnum;
bool authonly;
refnum = "46973415";
authonly = false;
details.Amount = 34.50;
details.AmountSpecified = true;
details.Description = "Example QuickSale";
details.Invoice = "123456";
usaepay.TransactionResponse response = new usaepay.TransactionResponse();
try
{
response = client.runQuickSale(token, refnum, details, authonly);
if (response.ResultCode == "A")
{
MessageBox.Show(string.Concat("Transaction Approved, RefNum: ",
response.RefNum));
}
else
{
MessageBox.Show(string.Concat("Transaction Failed: ",
response.Error));
}
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="urn:usaepay"
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:runQuickSale>
<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">c453ae7c15f208e6e30e81f9c9882ff9c0fa36d7</HashValue>
<Seed xsi:type="xsd:string">11794238107-test</Seed>
<Type xsi:type="xsd:string">sha1</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
</Token>
<RefNum xsi:type="xsd:string">102161632</RefNum>
<Details xsi:type="ns1:TransactionDetail">
<Amount xsi:type="xsd:double">22</Amount>
<Clerk xsi:type="xsd:string">John Doe</Clerk>
<Currency xsi:type="xsd:string">0</Currency>
<Description xsi:type="xsd:string">Example Transaction</Description>
<Discount xsi:type="xsd:double">10</Discount>
<Invoice xsi:type="xsd:string">44539</Invoice>
<OrderID xsi:type="xsd:string">12345</OrderID>
<PONum xsi:type="xsd:string">54321</PONum>
<Shipping xsi:type="xsd:double">2</Shipping>
<Subtotal xsi:type="xsd:double">12</Subtotal>
<Table xsi:type="xsd:string">1</Table>
<Tax xsi:type="xsd:double">10</Tax>
<Terminal xsi:type="xsd:string">15</Terminal>
<Tip xsi:type="xsd:double">8</Tip>
</Details>
<AuthOnly xsi:type="xsd:boolean">false</AuthOnly>
</ns1:runQuickSale>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example Response
<?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="urn:usaepay"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body>
<ns1:runQuickSaleResponse>
<runQuickSaleReturn xsi:type="ns1:TransactionResponse">
<AcsUrl xsi:nil="true" />
<AuthAmount xsi:type="xsd:double">22</AuthAmount>
<AuthCode xsi:type="xsd:string">056852</AuthCode>
<AvsResult xsi:type="xsd:string">Address: Match & 5 Digit Zip: Match</AvsResult>
<AvsResultCode xsi:type="xsd:string">YYY</AvsResultCode>
<BatchNum xsi:type="xsd:string">198205</BatchNum>
<BatchRefNum xsi:type="xsd:string">198205</BatchRefNum>
<CardCodeResult xsi:type="xsd:string">Match</CardCodeResult>
<CardCodeResultCode xsi:type="xsd:string">M</CardCodeResultCode>
<CardLevelResult xsi:type="xsd:string">Visa Traditional</CardLevelResult>
<CardLevelResultCode xsi:type="xsd:string">A</CardLevelResultCode>
<ConversionRate xsi:type="xsd:double">0</ConversionRate>
<ConvertedAmount xsi:type="xsd:double">0</ConvertedAmount>
<ConvertedAmountCurrency xsi:nil="true" />
<CustNum xsi:type="xsd:string">0</CustNum>
<Error xsi:type="xsd:string">Approved</Error>
<ErrorCode xsi:type="xsd:integer">0</ErrorCode>
<isDuplicate xsi:type="xsd:boolean">false</isDuplicate>
<Payload xsi:nil="true" />
<RefNum xsi:type="xsd:string">102162016</RefNum>
<Result xsi:type="xsd:string">Approved</Result>
<ResultCode xsi:type="xsd:string">A</ResultCode>
<Status xsi:type="xsd:string">Pending</Status>
<StatusCode xsi:type="xsd:string">P</StatusCode>
<VpasResultCode xsi:type="xsd:string"></VpasResultCode>
</runQuickSaleReturn>
</ns1:runQuickSaleResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
This method allows you to run a new transaction using the payment data from a previous transaction. Simply pass the reference number ($RefNum) of the previous transaction and the gateway will automatically transfer the credit card or electronic check (ACH) information for use in the new transaction. Some credit card information, such as the card code and magnetic strip cannot be stored. This may cause the new transaction to come in at a higher rate than the original.
Related Methods
Syntax
TransactionResponse runQuickSale ( ueSecurityToken Token, string RefNum, TransactionDetail Details, boolean AuthOnly )
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| %Details% | object | Transaction details: amount, clerk, currency, |
| RefNum | string | Unique transaction reference number assigned by the gateway. You can also use TransKey in the RefNum field. |
| AuthOnly | boolean | If true, the transaction will be authorized, but not be submitted for settlement. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| %TransactionResponse% | object | Returns a TransactionResponse object containing the results of the transaction and all relevant data. |
Exceptions
| Code | Message | Advice |
|---|---|---|
| 20002 | Invalid Security Token. | Supplied security token is invalid. |
| 10105 | Unable to find original transaction. | The specified transaction RefNum did not match an eligible transaction or the transaction belongs to a different merchant. |
| 10136 | Original transaction not approved. | QuickSale only allowed for transactions that were approved. |
Change Log
| Version | Change |
|---|---|
| 1.7 | TransKey can be used in RefNum field. |
Voids and Refunds
This section will show you how to initiate credit, refund, and void transactions. Please refer to the typical use cases for specific implementation details.
runCredit
Example Request
<?php
try {
$Request=array(
'AccountHolder' => 'Tester Jones',
'Details' => array(
'Description' => 'Example Transaction',
'Amount' => '4.00',
'Invoice' => '44539'
),
'CreditCardData' => array(
'CardNumber' => '4444555566667779',
'CardExpiration' => '0919',
'AvsStreet' => '1234 Main Street',
'AvsZip' => '99281',
'CardCode' => '999'
)
);
$res=$client->runCredit($token, $Request);
print_r($res);
}
catch (SoapFault $e) {
echo $client->__getLastRequest();
echo $client->__getLastResponse();
die("QuickSale failed :" .$e->getMessage());
}
?>
try {
TransactionRequestObject params = new TransactionRequestObject();
// set card holder name
params.setAccountHolder("Test Joe");
// populate transaction details
TransactionDetail details = new TransactionDetail();
details.setAmount(22.34);
details.setDescription("My Test Sale");
details.setInvoice("119891");
params.setDetails(details);
// populate credit card data
CreditCardData ccdata = new CreditCardData();
ccdata.setCardNumber("4444555566667779");
ccdata.setCardExpiration("0919");
ccdata.setCardCode("999");
params.setCreditCardData(ccdata);
// Create request object
RunSale request = new RunSale();
request.setToken(token);
request.setParams(params);
// Create response object
TransactionResponse response;
// run credit
response = client.runCredit(token, params);
System.out.println("Result: " + response.getResult());
} catch (Exception e) {
System.out.println("Soap Exception: " + e.getMessage());
}
Dim client As usaepay.usaepayService = New usaepay.usaepayService
Dim token As usaepay.ueSecurityToken
token = Me.CreateToken("714SSUxv1uohng2XkMJ7kLpETsu58G66", "1234")
Dim transaction As usaepay.TransactionRequestObject = New usaepay.TransactionRequestObject
transaction.CreditCardData = New usaepay.CreditCardData
transaction.CreditCardData.CardNumber = "4444555566667779"
transaction.CreditCardData.CardExpiration = "1219"
transaction.CreditCardData.CardCode = "999"
transaction.Details = New usaepay.TransactionDetail
transaction.Details.Amount = "1.00"
transaction.Details.AmountSpecified = True
transaction.Details.Invoice = "12345"
transaction.Details.Description = "Sample Credit"
Dim response As usaepay.TransactionResponse = New usaepay.TransactionResponse
response = client.runCredit(token, transaction)
If response.ResultCode = "A" Then
MsgBox("Transaction Approved, Refnum: " & response.RefNum)
Else
MsgBox("Transaction Error, Reason: " & response.Error)
End If
usaepay.TransactionRequestObject tran = new usaepay.TransactionRequestObject();
tran.Details = new usaepay.TransactionDetail();
tran.Details.Amount = 1.00;
tran.Details.AmountSpecified = true;
tran.Details.Invoice = "1234";
tran.Details.Description = "Sample Credit";
tran.CreditCardData = new usaepay.CreditCardData();
tran.CreditCardData.CardNumber = "4444555566667779";
tran.CreditCardData.CardExpiration = "1219";
usaepay.TransactionResponse response = new usaepay.TransactionResponse();
try
{
response = client.runCredit(token, tran);
if (response.ResultCode == "A")
{
MessageBox.Show(string.Concat("Transaction Approved, RefNum: ",
response.RefNum));
}
else
{
MessageBox.Show(string.Concat("Transaction Failed: ",
response.Error));
}
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="urn:usaepay"
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:runCredit>
<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">78a337fec71c936604c1c1f93ac6b8db9b6dce53</HashValue>
<Seed xsi:type="xsd:string">11639208872-test</Seed>
<Type xsi:type="xsd:string">sha1</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
</Token>
<Params xsi:type="ns1:TransactionRequestObject">
<AccountHolder xsi:type="xsd:string">Tester Jones</AccountHolder>
<BillingAddress xsi:type="ns1:Address">
<City xsi:type="xsd:string">Albany</City>
<Company xsi:type="xsd:string">testing</Company>
<Country xsi:type="xsd:string">Un</Country>
<FirstName xsi:type="xsd:string">SoapAPI</FirstName>
<LastName xsi:type="xsd:string">Testor</LastName>
<Phone xsi:type="xsd:string">5183310981</Phone>
<State xsi:type="xsd:string">NY</State>
<Street xsi:type="xsd:string">180 State st</Street>
<Street2 xsi:type="xsd:string">133 Lancaster st</Street2>
<Zip xsi:type="xsd:string">12210</Zip>
</BillingAddress>
<ClientIP xsi:type="xsd:string">123.123.123.123</ClientIP>
<Command xsi:type="xsd:string">credit</Command>
<CreditCardData xsi:type="ns1:CreditCardData">
<AvsStreet xsi:type="xsd:string">1234 Main Street</AvsStreet>
<AvsZip xsi:type="xsd:string">99281</AvsZip>
<CardCode xsi:type="xsd:string">123boatload1293</CardCode>
<CardExpiration xsi:type="xsd:string">1219</CardExpiration>
<CardNumber xsi:type="xsd:string">4444555566667779</CardNumber>
</CreditCardData>
<CustomerID xsi:type="xsd:string">123456</CustomerID>
<Details xsi:type="ns1:TransactionDetail">
<Amount xsi:type="xsd:double">22</Amount>
<Clerk xsi:type="xsd:string">John Doe</Clerk>
<Currency xsi:type="xsd:string">0</Currency>
<Description xsi:type="xsd:string">Example Transaction</Description>
<Discount xsi:type="xsd:double">10</Discount>
<Invoice xsi:type="xsd:string">44539</Invoice>
<OrderID xsi:type="xsd:string">12345</OrderID>
<PONum xsi:type="xsd:string">54321</PONum>
<Shipping xsi:type="xsd:double">2</Shipping>
<Subtotal xsi:type="xsd:double">12</Subtotal>
<Table xsi:type="xsd:string">1</Table>
<Tax xsi:type="xsd:double">10</Tax>
<Terminal xsi:type="xsd:string">15</Terminal>
<Tip xsi:type="xsd:double">8</Tip>
</Details>
<LineItems SOAP-ENC:arrayType="ns1:LineItem[1]" xsi:type="ns1:LineItemArray">
<item xsi:type="ns1:LineItem">
<SKU xsi:type="xsd:string">1234</SKU>
<ProductName xsi:type="xsd:string">Test Example</ProductName>
<Description xsi:type="xsd:string">Test</Description>
<UnitPrice xsi:type="xsd:string">19.99</UnitPrice>
<Qty xsi:type="xsd:string">9</Qty>
<Taxable xsi:type="xsd:boolean">true</Taxable>
</item>
</LineItems>
<ShippingAddress xsi:type="ns1:Address">
<City xsi:type="xsd:string">Los Angeles</City>
<Company xsi:type="xsd:string">Location 2</Company>
<Country xsi:type="xsd:string">Un</Country>
<FirstName xsi:type="xsd:string">Ship</FirstName>
<LastName xsi:type="xsd:string">Tome</LastName>
<Phone xsi:type="xsd:string">3133129163</Phone>
<State xsi:type="xsd:string">CA</State>
<Street xsi:type="xsd:string">9999 s sycamore</Street>
<Street2 xsi:type="xsd:string">9999 Lancaster st</Street2>
<Zip xsi:type="xsd:string">90036</Zip>
</ShippingAddress>
</Params>
</ns1:runCredit>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example Response
<?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="urn:usaepay"
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:runCreditResponse>
<runCreditReturn xsi:type="ns1:TransactionResponse">
<AcsUrl xsi:type="xsd:string"></AcsUrl>
<AuthAmount xsi:type="xsd:double">0</AuthAmount>
<AuthCode xsi:type="xsd:string">100116409</AuthCode>
<AvsResult xsi:type="xsd:string">Unmapped AVS response ( )</AvsResult>
<AvsResultCode xsi:type="xsd:string"></AvsResultCode>
<BatchNum xsi:type="xsd:string">0</BatchNum>
<BatchRefNum xsi:type="xsd:string">0</BatchRefNum>
<CardCodeResult xsi:type="xsd:string">No CVV2/CVC data available for transaction.</CardCodeResult>
<CardCodeResultCode xsi:type="xsd:string"></CardCodeResultCode>
<CardLevelResult xsi:type="xsd:string">Unknown Code</CardLevelResult>
<CardLevelResultCode xsi:type="xsd:string"></CardLevelResultCode>
<ConversionRate xsi:type="xsd:double">0</ConversionRate>
<ConvertedAmount xsi:type="xsd:double">0</ConvertedAmount>
<ConvertedAmountCurrency xsi:type="xsd:string">840</ConvertedAmountCurrency>
<CustNum xsi:type="xsd:string">0</CustNum>
<Error xsi:type="xsd:string"></Error>
<ErrorCode xsi:type="xsd:integer">0</ErrorCode>
<isDuplicate xsi:type="xsd:boolean">false</isDuplicate>
<Payload xsi:type="xsd:string"></Payload>
<RefNum xsi:type="xsd:string">100106386</RefNum>
<Result xsi:type="xsd:string">Approved</Result>
<ResultCode xsi:type="xsd:string">A</ResultCode>
<Status xsi:type="xsd:string">Pending</Status>
<StatusCode xsi:type="xsd:string">P</StatusCode>
<VpasResultCode xsi:type="xsd:string"></VpasResultCode>
</runCreditReturn>
</ns1:runCreditResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
This method runs a Credit transaction in order to refund all or part of a previous Sale, or issue an open credit to a customer's credit card. Use the runCredit method to refund a customer's card once the initial Sale has been settled. If the batch that the Sale is in has not yet been settled, you may want to use the (#voidtransaction) method instead, which will prevent the initial Sale from ever appearing on the customer's credit card statement. (See the description of the (#voidtransaction) method for more details.) Using the runCredit method will cause both the initial charge and the credit to appear on the customer's credit card statement.
Related Methods
Syntax
TransactionResponse runCredit ( ueSecurityToken Token, TransactionRequestObject Params )
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| %TransactionRequestObject% | Params | Transaction details from all fields of the transaction form. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| %TransactionResponse% | object | Returns a TransactionResponse object containing the results of the transaction and all relevant data. |
runCheckCredit
Example Request
<?php
try {
$Request=array(
'AccountHolder' => 'Tester Jones',
'Details' => array(
'Description' => 'Example Transaction',
'Amount' => '4.99',
'Invoice' => '44539'
),
'CheckData' => array(
'CheckNumber' => '1234',
'Routing' => '123456789',
'Account' => '11111111',
'AccountType' => 'Savings',
'DriversLicense' => '34521343',
'DriversLicenseState' => 'CA',
'RecordType' => 'PPD'
)
);
$res=$client->runCheckCredit($token, $Request);
}
catch (SoapFault $e) {
echo $client->__getLastRequest();
echo $client->__getLastResponse();
die("runCheckCredit failed :" .$e->getMessage());
}
?>
try {
TransactionRequestObject params = new TransactionRequestObject();
//set account holder name
params.setAccountHolder("Test Joe");
// populate transaction details
TransactionDetail details = new TransactionDetail();
details.setAmount(22.34);
details.setDescription("My Test Sale");
details.setInvoice("119891");
params.setDetails(details);
// populate credit card data
CheckData checkdata = new CheckData();
checkdata.setRouting("123123123");
checkdata.setAccount("321321");
params.setCheckData(checkdata);
// Create request object
RunCheckCredit request = new RunCheckCredit();
request.setToken(token);
request.setParams(params);
// Create response object
TransactionResponse response;
// run credit
response = client.runCheckCredit(token, params);
System.out.println("Response: " + response.getResult() + " RefNum: " + response.getRefNum());
} catch (Exception e) {
System.out.println("Soap Exception: " + e.getMessage());
}
Dim client As usaepay.usaepayService = New usaepay.usaepayService
Dim token As usaepay.ueSecurityToken
token = Me.CreateToken("714SSUxv1uohng2XkMJ7kLpETsu58G66", "1234")
Dim transaction As usaepay.TransactionRequestObject = New usaepay.TransactionRequestObject
transaction.CheckData = New usaepay.CheckData
transaction.CheckData.Account = "1112223333"
transaction.CheckData.Routing = "123456789"
transaction.CheckData.DriversLicense = "D5555555"
transaction.CheckData.DriversLicenseState = "CA"
transaction.Details = New usaepay.TransactionDetail
transaction.Details.Amount = "1.00"
transaction.Details.AmountSpecified = True
transaction.Details.Invoice = "55555"
transaction.Details.Description = "Test Check Sale"
transaction.AccountHolder = "Test Guy"
Dim response As usaepay.TransactionResponse
response = client.runCheckCredit(token, transaction)
If response.ResultCode = "A" Then
MsgBox("Transaction Approved, Reference Number: " & response.RefNum)
ElseIf response.ResultCode = "D" Then
MsgBox("Transaction Declined, Reason: " & response.Error)
Else
MsgBox("Transaction Error, Reason: " & response.Error)
End If
usaepay.TransactionRequestObject tran = new usaepay.TransactionRequestObject();
tran.Details = new usaepay.TransactionDetail();
tran.Details.Amount = 1.00;
tran.Details.AmountSpecified = true;
tran.Details.Invoice = "1234";
tran.Details.Description = "Sample Check Credit";
tran.CheckData = new usaepay.CheckData();
tran.CheckData.Account = "1112223333";
tran.CheckData.Routing = "123456789";
tran.CheckData.DriversLicense = "D5555555";
tran.CheckData.DriversLicenseState = "CA";
tran.AccountHolder = "Test Guy";
usaepay.TransactionResponse response = new usaepay.TransactionResponse();
try
{
response = client.runCheckCredit(token, tran);
if (response.ResultCode == "A")
{
MessageBox.Show(string.Concat("Transaction Approved, RefNum: ",
response.RefNum));
}
else
{
MessageBox.Show(string.Concat("Transaction Failed: ",
response.Error));
}
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="urn:usaepay"
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:runCheckCredit>
<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">58bdbfeb7c15078fa62291bd6a4473990dd50dd8</HashValue>
<Seed xsi:type="xsd:string">11139209200-test</Seed>
<Type xsi:type="xsd:string">sha1</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
</Token>
<Params xsi:type="ns1:TransactionRequestObject">
<AccountHolder xsi:type="xsd:string">Tester Jones</AccountHolder>
<BillingAddress xsi:type="ns1:Address">
<City xsi:type="xsd:string">Albany</City>
<Company xsi:type="xsd:string">testing</Company>
<Country xsi:type="xsd:string">Un</Country>
<FirstName xsi:type="xsd:string">SoapAPI</FirstName>
<LastName xsi:type="xsd:string">Testor</LastName>
<Phone xsi:type="xsd:string">5183310981</Phone>
<State xsi:type="xsd:string">NY</State>
<Street xsi:type="xsd:string">180 State st</Street>
<Street2 xsi:type="xsd:string">133 Lancaster st</Street2>
<Zip xsi:type="xsd:string">12210</Zip>
</BillingAddress>
<CheckData xsi:type="ns1:CheckData">
<Account xsi:type="xsd:string">11111111</Account>
<AccountType xsi:type="xsd:string">Savings</AccountType>
<CheckNumber xsi:type="xsd:integer">1234</CheckNumber>
<DriversLicense xsi:type="xsd:string">34521343</DriversLicense>
<DriversLicenseState xsi:type="xsd:string">CA</DriversLicenseState>
<RecordType xsi:type="xsd:string">PPD</RecordType>
<Routing xsi:type="xsd:string">123456789</Routing>
</CheckData>
<ClientIP xsi:type="xsd:string">123.123.123.123</ClientIP>
<Command xsi:type="xsd:string">checkcredit</Command>
<CustomerID xsi:type="xsd:string">123456</CustomerID>
<Details xsi:type="ns1:TransactionDetail">
<Amount xsi:type="xsd:double">22</Amount>
<Clerk xsi:type="xsd:string">John Doe</Clerk>
<Currency xsi:type="xsd:string">0</Currency>
<Description xsi:type="xsd:string">Example Transaction</Description>
<Discount xsi:type="xsd:double">10</Discount>
<Invoice xsi:type="xsd:string">44539</Invoice>
<OrderID xsi:type="xsd:string">12345</OrderID>
<PONum xsi:type="xsd:string">54321</PONum>
<Shipping xsi:type="xsd:double">2</Shipping>
<Subtotal xsi:type="xsd:double">12</Subtotal>
<Table xsi:type="xsd:string">1</Table>
<Tax xsi:type="xsd:double">10</Tax>
<Terminal xsi:type="xsd:string">15</Terminal>
<Tip xsi:type="xsd:double">8</Tip>
</Details>
<LineItems SOAP-ENC:arrayType="ns1:LineItem[1]" xsi:type="ns1:LineItemArray">
<item xsi:type="ns1:LineItem">
<SKU xsi:type="xsd:string">1234</SKU>
<ProductName xsi:type="xsd:string">Test Example</ProductName>
<Description xsi:type="xsd:string">Test</Description>
<UnitPrice xsi:type="xsd:string">19.99</UnitPrice>
<Qty xsi:type="xsd:string">9</Qty>
<Taxable xsi:type="xsd:boolean">true</Taxable>
</item>
</LineItems>
<ShippingAddress xsi:type="ns1:Address">
<City xsi:type="xsd:string">Los Angeles</City>
<Company xsi:type="xsd:string">Location 2</Company>
<Country xsi:type="xsd:string">Un</Country>
<FirstName xsi:type="xsd:string">Ship</FirstName>
<LastName xsi:type="xsd:string">Tome</LastName>
<Phone xsi:type="xsd:string">3133129163</Phone>
<State xsi:type="xsd:string">CA</State>
<Street xsi:type="xsd:string">9999 s sycamore</Street>
<Street2 xsi:type="xsd:string">9999 Lancaster st</Street2>
<Zip xsi:type="xsd:string">90036</Zip>
</ShippingAddress>
</Params>
</ns1:runCheckCredit>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example Response
<?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"xmlns:ns1="urn:usaepay"
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:runCheckCreditResponse>
<runCheckCreditReturn xsi:type="ns1:TransactionResponse">
<AcsUrl xsi:type="xsd:string"></AcsUrl>
<AuthAmount xsi:type="xsd:double">0</AuthAmount>
<AuthCode xsi:type="xsd:string">TM6484</AuthCode>
<AvsResult xsi:type="xsd:string">No AVS response (Typically no AVS data sent or swiped transaction)
</AvsResult>
<AvsResultCode xsi:type="xsd:string"></AvsResultCode>
<BatchNum xsi:type="xsd:string">151117</BatchNum>
<BatchRefNum xsi:type="xsd:string">0</BatchRefNum>
<CardCodeResult xsi:type="xsd:string">No CVV2/CVC data available for transaction.</CardCodeResult>
<CardCodeResultCode xsi:type="xsd:string"></CardCodeResultCode>
<CardLevelResult xsi:type="xsd:string">Unknown Code</CardLevelResult>
<CardLevelResultCode xsi:type="xsd:string"></CardLevelResultCode>
<ConversionRate xsi:type="xsd:double">0</ConversionRate>
<ConvertedAmount xsi:type="xsd:double">0</ConvertedAmount>
<ConvertedAmountCurrency xsi:type="xsd:string">840</ConvertedAmountCurrency>
<CustNum xsi:type="xsd:string">0</CustNum>
<Error xsi:type="xsd:string"></Error>
<ErrorCode xsi:type="xsd:integer">0</ErrorCode>
<isDuplicate xsi:type="xsd:boolean">false</isDuplicate>
<Payload xsi:type="xsd:string"></Payload>
<RefNum xsi:type="xsd:string">102132826</RefNum>
<Result xsi:type="xsd:string">Approved</Result>
<ResultCode xsi:type="xsd:string">A</ResultCode>
<Status xsi:type="xsd:string">Pending</Status>
<StatusCode xsi:type="xsd:string">P</StatusCode>
<VpasResultCode xsi:type="xsd:string"></VpasResultCode>
</runCheckCreditReturn>
</ns1:runCheckCreditResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
This method uses ACH to sends funds to a customer, employee, vendor, etc. It can be used to "refund" a sale or make a payment to someone (ie payroll). This transaction type is "stand alone" and does not pull the account and routing number from a previous sale. You must provide the Routing and Account properties in the CheckData object. If you want to use the account data from a prior transaction by referencing the RefNum, use the (#refundtransaction) or (#runquickcredit methods.
This feature, sometimes referred as "Reverse ACH", "Check Credit" or "Disbursement", is not available with all check processors. For those processors that do support it, merchants must request that it is enabled for their account. Contact your merchant service provider for further information.
If this method is used to reverse or refund an electronic check transaction, please be aware that both the original transaction and the refund will appear as separate transactions on the customer's bank account statement. To reverse a sale without creating a new transaction, you must use the (#voidtransaction) method. Please see the description of the (#voidtransaction) method for more details on how to determine which of these methods is most appropriate.
Related Methods
Syntax
TransactionResponse runCheckCredit ( ueSecurityToken Token, TransactionRequestObject Params )
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| %TransactionRequestObject% | Params | Transaction details from all fields of the transaction form. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| %TransactionResponse% | object | Returns a TransactionResponse object containing the results of the transaction and all relevant data. |
runQuickCredit
Example Request
<?php
try {
$refnum="1nfmkr4rsmtxhm5";
$details=array(
"Amount"=>4.00,
"Invoice"=>1234,
"Description"=>"Test Transaction",
"PONum"=>"",
"OrderID"=>1234,
"Tax"=>0,
"Tip"=>0,
"NonTax"=>false,
"Shipping"=>0,
"Discount"=>0,
"Subtotal"=>4.00
);
print_r($client->runQuickCredit($token,$refnum, $details));
}
catch(SoapFault $e) {
echo $e->getMessage();
echo "\n\nRequest: " . $client->__getLastRequest();
echo "\n\nResponse: " . $client->__getLastResponse();
}
?>
try {
//Set RefNum to the transaction refference number
//you want to run a quick credit on
BigInteger RefNum = new BigInteger("123456789");
//populate transaction details
TransactionDetail details = new TransactionDetail();
details.setAmount(22.34);
details.setDescription("QuickCredit");
details.setInvoice("119891");
// Create response object
TransactionResponse response;
response = client.runQuickCredit(token, RefNum, details, false);
System.out.println("Response: " + response.getResult());
System.out.println("RefNum: " + response.getRefNum());
} catch (Exception e) {
System.out.println("Soap Exception: " + e.getMessage());
}
Dim client As usaepay.usaepayService = New usaepay.usaepayService
Dim token As usaepay.ueSecurityToken
token = Me.CreateToken("714SSUxv1uohng2XkMJ7kLpETsu58G66", "1234")
Dim refnum As Integer
Dim details As usaepay.TransactionDetail = New usaepay.TransactionDetail
refnum = "46990787"
details.Amount = "1.00"
details.AmountSpecified = True
details.Description = "Example QuickCredit"
details.Invoice = "123456"
Dim response As usaepay.TransactionResponse
response = client.runQuickCredit(token, refnum, details)
If response.ResultCode = "A" Then
MsgBox("Transaction Approved, Reference Number: " & response.RefNum)
ElseIf response.ResultCode = "D" Then
MsgBox("Transaction Declined, Reason: " & response.Error)
Else
MsgBox("Transaction Error, Reason: " & response.Error)
End If
Dim client As usaepay.usaepayService = New usaepay.usaepayService
Dim token As usaepay.ueSecurityToken
token = Me.CreateToken("714SSUxv1uohng2XkMJ7kLpETsu58G66", "1234")
Dim refnum As Integer
Dim details As usaepay.TransactionDetail = New usaepay.TransactionDetail
refnum = "46990787"
details.Amount = "1.00"
details.AmountSpecified = True
details.Description = "Example QuickCredit"
details.Invoice = "123456"
Dim response As usaepay.TransactionResponse
response = client.runQuickCredit(token, refnum, details)
If response.ResultCode = "A" Then
MsgBox("Transaction Approved, Reference Number: " & response.RefNum)
ElseIf response.ResultCode = "D" Then
MsgBox("Transaction Declined, Reason: " & response.Error)
Else
MsgBox("Transaction Error, Reason: " & response.Error)
End If
usaepay.TransactionDetail details = new usaepay.TransactionDetail();
string refnum;
refnum = "46973415";
details.Amount = 34.50;
details.AmountSpecified = true;
details.Description = "Example QuickCredit";
details.Invoice = "123456";
usaepay.TransactionResponse response = new usaepay.TransactionResponse();
try
{
response = client.runQuickCredit(token, refnum, details);
if (response.ResultCode == "A")
{
MessageBox.Show(string.Concat("Transaction Approved, RefNum: ",
response.RefNum));
}
else
{
MessageBox.Show(string.Concat("Transaction Failed: ",
response.Error));
}
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="urn:usaepay"
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:runQuickCredit>
<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">91524b471de4baf26cc6abec7e81e16108354d61</HashValue>
<Seed xsi:type="xsd:string">12115174123-test</Seed>
<Type xsi:type="xsd:string">sha1</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
</Token>
<RefNum xsi:type="xsd:string">102164125</RefNum>
<Details xsi:type="ns1:TransactionDetail">
<Amount xsi:type="xsd:double">22</Amount>
<Clerk xsi:type="xsd:string">John Doe</Clerk>
<Currency xsi:type="xsd:string">0</Currency>
<Description xsi:type="xsd:string">Example Transaction</Description>
<Discount xsi:type="xsd:double">10</Discount>
<Invoice xsi:type="xsd:string">44539</Invoice>
<OrderID xsi:type="xsd:string">12345</OrderID>
<PONum xsi:type="xsd:string">54321</PONum>
<Shipping xsi:type="xsd:double">2</Shipping>
<Subtotal xsi:type="xsd:double">12</Subtotal>
<Table xsi:type="xsd:string">1</Table>
<Tax xsi:type="xsd:double">10</Tax>
<Terminal xsi:type="xsd:string">15</Terminal>
<Tip xsi:type="xsd:double">8</Tip>
</Details>
<param3 xsi:type="xsd:boolean">false</param3>
</ns1:runQuickCredit>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example Response
<?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="urn:usaepay"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body>
<ns1:runQuickCreditResponse>
<runQuickCreditReturn xsi:type="ns1:TransactionResponse">
<AcsUrl xsi:nil="true" />
<AuthAmount xsi:type="xsd:double">0</AuthAmount>
<AuthCode xsi:type="xsd:string">102174451</AuthCode>
<AvsResult xsi:type="xsd:string">Unmapped AVS response ( )</AvsResult>
<AvsResultCode xsi:type="xsd:string"></AvsResultCode>
<BatchNum xsi:type="xsd:string">198205</BatchNum>
<BatchRefNum xsi:type="xsd:string">198205</BatchRefNum>
<CardCodeResult xsi:type="xsd:string">No CVV2/CVC data available for transaction.</CardCodeResult>
<CardCodeResultCode xsi:type="xsd:string"></CardCodeResultCode>
<CardLevelResult xsi:type="xsd:string">Unknown Code</CardLevelResult>
<CardLevelResultCode xsi:type="xsd:string"></CardLevelResultCode>
<ConversionRate xsi:type="xsd:double">0</ConversionRate>
<ConvertedAmount xsi:type="xsd:double">0</ConvertedAmount>
<ConvertedAmountCurrency xsi:nil="true" />
<CustNum xsi:type="xsd:string">0</CustNum>
<Error xsi:type="xsd:string"></Error>
<ErrorCode xsi:nil="true" />
<isDuplicate xsi:type="xsd:boolean">false</isDuplicate>
<Payload xsi:nil="true" />
<RefNum xsi:type="xsd:string">102164428</RefNum>
<Result xsi:type="xsd:string">Approved</Result>
<ResultCode xsi:type="xsd:string">A</ResultCode>
<Status xsi:type="xsd:string">Pending</Status>
<StatusCode xsi:type="xsd:string">P</StatusCode>
<VpasResultCode xsi:type="xsd:string"></VpasResultCode>
</runQuickCreditReturn>
</ns1:runQuickCreditResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
This method allows you to run a new transaction using stored customer data. Simply pass the reference number (RefNum) of a previous transaction and the gateway will automatically transfer the credit card information for use in the new transaction. Some credit card information, such as the card code and magnetic strip cannot be stored. This may cause the new transaction to come in at a higher rate than the original.
Related Methods
Syntax
TransactionResponse runQuickCredit ( ueSecurityToken Token, string RefNum, TransactionDetail Details )
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| %Details% | object | Transaction details: amount, clerk, currency, |
| RefNum | string | Unique transaction reference number assigned by the gateway. You can also use TransKey in the RefNum field. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| %TransactionResponse% | object | Returns a TransactionResponse object containing the results of the transaction and all relevant data. |
Change Log
| Version | Description |
|---|---|
| 1.7 | TransKey can be used in RefNum field. |
refundTransaction
Example Request
<?php
try {
$refnum="1009411";
$amount="1.99";
print_r($client->refundTransaction($token,$refnum, $amount));
}
catch(SoapFault $e) {
echo $e->getMessage();
echo "\n\nRequest: " . $client->__getLastRequest();
echo "\n\nResponse: " . $client->__getLastResponse();
}
A refund with additional information passed.
$Request=array(
'AccountHolder' => 'Tester Jones',
'ClientIP' => '123.123.123.123',
'CustomerID' => '123456',
'Command' => 'refund',
'Details' => array(
'Amount' => '10.00',
'Clerk' => 'John Doe',
'Description' => 'Refund transaction',
'Invoice' => '44539',
'OrderID' => '12345',
'PONum' => '54321',
'Table' => '1',
'Terminal' => '27',
),
'RefNum' => $SaleRefNum
);
$res=$client->runTransaction($token, $Request);
?>
try {
//Set RefNum to the Reference Number of transaction you
//want to refund.
BigInteger RefNum = _runTransaction();
TransactionResponse response;
response = client.refundTransaction(token, RefNum, 10.10);
System.out.println(response.getStatus());
} catch (Exception e) {
System.out.println("Soap Exception: " + e.getMessage());
}
Dim client As usaepay.usaepayService = New usaepay.usaepayService
Dim token As usaepay.ueSecurityToken
token = Me.CreateToken("714SSUxv1uohng2XkMJ7kLpETsu58G66", "1234")
Dim transaction As usaepay.TransactionRequestObject = New usaepay.TransactionRequestObject
transaction.Details = New usaepay.TransactionDetail
transaction.Details.Amount = "11.11"
transaction.Details.AmountSpecified = "true"
transaction.Details.Invoice = "123456"
transaction.AuthCode = "009915"
transaction.RefNum = "46993455"
Dim response As usaepay.TransactionResponse = New usaepay.TransactionResponse
response = client.captureTransaction(token, transaction.RefNum, transaction.Details.Amount)
If response.ResultCode = "A" Then
MsgBox("Transaction Approved, Refnum: " & response.RefNum)
Else
MsgBox("Transaction Error, Reason: " & response.Error)
End If
string refnum;
double amount;
refnum = "46973575";
amount = 10.00;
usaepay.TransactionResponse response = new usaepay.TransactionResponse();
try
{
response = client.refundTransaction(token, refnum, amount);
if (response.ResultCode == "A")
{
MessageBox.Show(string.Concat("Transaction Approved, RefNum: ",
response.RefNum));
}
else
{
MessageBox.Show(string.Concat("Transaction Failed: ",
response.Error));
}
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="urn:usaepay"
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:refundTransaction>
<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">45d3fc860f3baefbaaab7435253d56fd1337b716</HashValue>
<Seed xsi:type="xsd:string">1199745214-test</Seed>
<Type xsi:type="xsd:string">sha1</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
</Token>
<RefNum xsi:type="xsd:string">102226408</RefNum>
<Amount xsi:type="xsd:double">3</Amount>
</ns1:refundTransaction>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example Response
<?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="urn:usaepay"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body>
<ns1:refundTransactionResponse>
<refundTransactionReturn xsi:type="ns1:TransactionResponse">
<AcsUrl xsi:nil="true" />
<AuthAmount xsi:type="xsd:double">0</AuthAmount>
<AuthCode xsi:type="xsd:string">102236539</AuthCode>
<AvsResult xsi:type="xsd:string">Unmapped AVS response ( )</AvsResult>
<AvsResultCode xsi:type="xsd:string"></AvsResultCode>
<BatchNum xsi:nil="true" />
<BatchRefNum xsi:nil="true" />
<CardCodeResult xsi:type="xsd:string">No CVV2/CVC data available for transaction.</CardCodeResult>
<CardCodeResultCode xsi:type="xsd:string"></CardCodeResultCode>
<CardLevelResult xsi:type="xsd:string">Unknown Code</CardLevelResult>
<CardLevelResultCode xsi:type="xsd:string"></CardLevelResultCode>
<ConversionRate xsi:type="xsd:double">0</ConversionRate>
<ConvertedAmount xsi:type="xsd:double">0</ConvertedAmount>
<ConvertedAmountCurrency xsi:nil="true" />
<CustNum xsi:type="xsd:string">0</CustNum>
<Error xsi:type="xsd:string"></Error>
<ErrorCode xsi:nil="true" />
<isDuplicate xsi:type="xsd:boolean">false</isDuplicate>
<Payload xsi:nil="true" />
<RefNum xsi:type="xsd:sting">102226516</RefNum>
<Result xsi:type="xsd:string">Approved</Result>
<ResultCode xsi:type="xsd:string">A</ResultCode>
<Status xsi:type="xsd:string">Pending</Status>
<StatusCode xsi:type="xsd:string">P</StatusCode>
<VpasResultCode xsi:type="xsd:string"></VpasResultCode>
</refundTransactionReturn>
</ns1:refundTransactionResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
This method refunds a sale. Both credit card and check sale transactions may be refunded. You may choose to refund the entire amount or just a portion of the original sale.
For credit cards, the refund will show up as a separate transaction on the card holder's statement. To cancel the original sale before the batch it is in has been settled, the (#voidtransaction) method should be used instead.
The transaction to be refunded must be retrieved using the reference number (RefNum) assigned to the transaction by the gateway. The RefNum is assigned by the gateway and returned when a transaction is processed. To find a missing RefNum, use the (#searchtransactions) method.
This method pulls forward all of the information such as invoice number from the original sale transaction and saves it with the refund transaction. If you want to override any of this information, use (#runtransaction) with the "Command" parameter set to "Refund" and the "RefNum" parameter set to the transaction refnum of the sale. You can then populate the (#details) object with any information specific to the refund.
Related Methods
Syntax
TransactionResponse refundTransaction ( ueSecurityToken Token, string, RefNum, double Amount )
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| RefNum | string | Unique transaction reference number assigned by the gateway. You can also use TransKey in the RefNum field. |
| Amount | double | Amount to be refunded (set to 0 if refunding entire original amount) |
Response Parameters
| Name | Type | Description |
|---|---|---|
| %TransactionResponse% | object | Returns a TransactionResponse object containing the results of the transaction and all relevant data. |
voidTransaction
Example Request
<?php
try {
$Request=array(
'AccountHolder' => 'Tester Jones',
'Command' => 'authonly',
'Details' => array(
'Description' => 'Example Transaction',
'Amount' => '4.00',
'Invoice' => '44539'
),
'CreditCardData' => array(
'CardNumber' => '4444555566667779',
'CardExpiration' => '0919',
'AvsStreet' => '1234 Main Street',
'AvsZip' => '99281',
'CardCode' => '999'
)
);
$temp=$client->runTransaction($token, $Request);
$res=$client->voidTransaction($token,$temp->RefNum);
print_r($res);
}
catch (SoapFault $e) {
die("Void Transaction failed :" .$e->getMessage());
}
?>
Dim client As usaepay.usaepayService = New usaepay.usaepayService
Dim token As usaepay.ueSecurityToken
token = Me.CreateToken("714SSUxv1uohng2XkMJ7kLpETsu58G66", "1234")
Dim transaction As usaepay.TransactionRequestObject = New usaepay.TransactionRequestObject
Dim refnum As String
Dim void As Boolean
refnum = "46980114"
void = True
Dim result As Boolean
result = client.voidTransaction(token, refnum)
If result = True Then
MsgBox("Transaction Voided")
Else
MsgBox("An error occured.")
End If
string refnum;
Boolean response;
refnum = "46973526";
try
{
response = client.voidTransaction(token, refnum);
if (response == true)
{
MessageBox.Show(string.Concat("Transaction voided"));
}
else
{
MessageBox.Show(string.Concat("An error occured"));
}
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="urn:usaepay"
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:voidTransaction>
<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">aece31e8de6306a0ba601939813554b7351470ef</HashValue>
<Seed xsi:type="xsd:string">11333566304-test</Seed>
<Type xsi:type="xsd:string">sha1</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT
</SourceKey>
</Token>
<RefNum xsi:type="xsd:string">102229369</RefNum>
</ns1:voidTransaction>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example Response
<?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"xmlns:ns1="urn:usaepay"
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:voidTransactionResponse>
<voidTransactionReturn xsi:type="xsd:boolean">true</voidTransactionReturn>
</ns1:voidTransactionResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
This function will void a transaction that was previously authorized. Once a transaction has been voided, it will not show up on the customer's credit card statement. Customers who have online banking that allows them to see "Pending" transactions may see the voided transaction for a few days before it disappears.
You can only void a transaction that hasn't been settled yet. A transaction is settled when the batch that it is in has been closed. If the transaction has been settled, you must run a credit instead using the (#runcredit) method. If you run a credit, both the credit and the initial charge will show up on the customer's credit card statement. (See the (#runcredit) method for more details.)
The transaction to be voided must be retrieved using the reference number (RefNum) assigned to the transaction by the gateway. The RefNum is assigned by the gateway and returned when a transaction is processed. To find a missing RefNum, use the (#searchtransactions) method.
Related Methods
Syntax
TransactionResponse voidTransaction ( ueSecurityToken Token, string RefNum )
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| RefNum | string | Unique transaction reference number assigned by the gateway. You can also use TransKey in the RefNum field. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| voidTransactionReturn | boolean | Returns confirmation of request only if successful. If request fails, an exception will be thrown. |
Change Log
| Version | Change |
|---|---|
| 1.7 | TransKey can be used in RefNum field. |
Queue and Capture
queueTransaction
Example Request
<?php
try {
$RefNum="onfmz93jtw93c1g";
$res=$client->queueTransaction($token, $RefNum);
print_r($res);
}
catch (SoapFault $e){
die("queueTransaction failed :" .$e->getMessage());
}
?>
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="urn:usaepay" 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:queueTransaction>
<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">0fce6e926d22ce2c068c8d417cbe7c670056f59f1cb01678d75c7352e003324e</HashValue>
<Seed xsi:type="xsd:string">1539018251449307535sadfpouhasodf8uh</Seed>
<Type xsi:type="xsd:string">sha256</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">chwl7EPgI56G8X76a0ME509Vc2z3BGge</SourceKey>
</Token>
<RefNum xsi:type="xsd:string">onfmz93jtw93c1g</RefNum>
</ns1:queueTransaction>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example Response
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="urn:usaepay" 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:queueTransactionResponse>
<queueTransactionReturn xsi:type="xsd:boolean">true</queueTransactionReturn>
</ns1:queueTransactionResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Queue a specific transaction.
This function will queue a transaction that was previously authorized. You can only queue a transaction that hasn't been settled yet. A transaction is settled when the batch that it is in has been closed.
The transaction to be queued must be retrieved using the reference number (RefNum or TransKey) assigned to the transaction by the gateway. The RefNum is assigned by the gateway and returned when a transaction is processed. To find a missing RefNum, use the searchTransactions method.
Related Methods
Syntax
boolean queueTransaction ( ueSecurityToken Token, string RefNum )
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| RefNum | string | Unique transaction reference number assigned by the gateway. You can also use TransKey in the RefNum field. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| queueTransactionReturn | boolean | Returns confirmation of request only if successful. If request fails, an exception will be thrown. |
Change Log
| Version | Change |
|---|---|
| 1.7 | Added Method. |
captureTransaction
Example Request
<?php
try {
//Initial Authorization
$Request=array(
'AccountHolder' => 'Tester Jones',
'Command' => 'authonly',
'Details' => array(
'Description' => 'Example Transaction',
'Amount' => '4.00',
'Invoice' => '44539'
),
'CreditCardData' => array(
'CardNumber' => '4444555566667779',
'CardExpiration' => '0919',
'AvsStreet' => '1234 Main Street',
'AvsZip' => '99281',
'CardCode' => '999'
)
);
$amount='4.00';
$temp=$client->runTransaction($token, $Request);
//Capturing the authorization
$IfAuthExpired = 'ReAuth';
$res=$client->captureTransaction($token,$temp->RefNum,$amount, $IfAuthExpired);
}
catch (SoapFault $e) {
echo $client->__getLastRequest();
echo $client->__getLastResponse();
die("Capture Transaction failed :" .$e->getMessage());
}
?>
try {
//Setting RefNum from the original transaction
BigInteger RefNum = new BigInteger('12345678');
//Setting Amount to capture
Double Amount = new Double(12.34);
//Create Transaction Response
TransactionResponse Response;
Response = client.captureTransaction(token,RefNum,Amount);
} catch (Exception e) {
System.out.println("Soap Exception: " + e.getMessage());
}
Dim client As usaepay.usaepayService = New usaepay.usaepayService
Dim token As usaepay.ueSecurityToken
token = Me.CreateToken("714SSUxv1uohng2XkMJ7kLpETsu58G66", "1234")
Dim transaction As usaepay.TransactionRequestObject = New usaepay.TransactionRequestObject
transaction.Details = New usaepay.TransactionDetail
transaction.Details.Amount = "11.11"
transaction.Details.AmountSpecified = "true"
transaction.Details.Invoice = "123456"
transaction.AuthCode = "009915"
transaction.RefNum = "46993455"
Dim response As usaepay.TransactionResponse = New usaepay.TransactionResponse
response = client.captureTransaction(token, transaction.RefNum, transaction.Details.Amount)
If response.ResultCode = "A" Then
MsgBox("Transaction Approved, Refnum: " & response.RefNum)
Else
MsgBox("Transaction Error, Reason: " & response.Error)
End If
usaepay.TransactionRequestObject tran = new usaepay.TransactionRequestObject();
tran.Details = new usaepay.TransactionDetail();
tran.Details.Amount = 1.00;
tran.Details.AmountSpecified = true;
tran.Details.Invoice = "123456";
tran.RefNum = "47001545";
usaepay.TransactionResponse response = new usaepay.TransactionResponse();
try
{
response = client.captureTransaction(token, tran.RefNum, tran.Details.Amount);
if (response.ResultCode == "A")
{
MessageBox.Show(string.Concat("Transaction Approved, RefNum: ",
response.RefNum));
}
else
{
MessageBox.Show(string.Concat("Transaction Failed: ",
response.Error));
}
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="urn:usaepay"
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:captureTransaction>
<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">c420eb2f0a410bd1baab227b43c84b3ba7dad5ae</HashValue>
<Seed xsi:type="xsd:string">11367276629-test</Seed>
<Type xsi:type="xsd:string">sha1</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
</Token>
<RefNum xsi:type="xsd:sting">1nfmkr4rsmtxhm5</RefNum>
<Amount xsi:type="xsd:double">0</Amount>
</ns1:captureTransaction>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example Response
<?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="urn:usaepay"
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:captureTransactionResponse>
<captureTransactionReturn xsi:type="ns1:TransactionResponse">
<AcsUrl xsi:type="xsd:string"></AcsUrl>
<AuthAmount xsi:type="xsd:double">0</AuthAmount>
<AuthCode xsi:type="xsd:string">066952</AuthCode>
<AvsResult xsi:type="xsd:string">No AVS response(Typically no AVS data sent or swiped transaction)
</AvsResult>
<AvsResultCode xsi:type="xsd:string"></AvsResultCode>
<BatchNum xsi:type="xsd:string">0</BatchNum>
<BatchRefNum xsi:type="xsd:string">0</BatchRefNum>
<CardCodeResult xsi:type="xsd:string">No CVV2/CVC data available for transaction.</CardCodeResult>
<CardCodeResultCode xsi:type="xsd:string"></CardCodeResultCode>
<CardLevelResult xsi:type="xsd:string">Unknown Code</CardLevelResult>
<CardLevelResultCode xsi:type="xsd:string"></CardLevelResultCode>
<ConversionRate xsi:type="xsd:double">0</ConversionRate>
<ConvertedAmount xsi:type="xsd:double">0</ConvertedAmount>
<ConvertedAmountCurrency xsi:type="xsd:string">840</ConvertedAmountCurrency>
<CustNum xsi:type="xsd:string">0</CustNum>
<Error xsi:type="xsd:string">Approved</Error>
<ErrorCode xsi:type="xsd:integer">0</ErrorCode>
<isDuplicate xsi:type="xsd:boolean">false</isDuplicate>
<Payload xsi:type="xsd:string"></Payload>
<RefNum xsi:type="xsd:string">102208900</RefNum>
<TransKey xsi:type="xsd:string">lnfkx4pr89yq4yh</TransKey>
<Result xsi:type="xsd:string">Approved</Result>
<ResultCode xsi:type="xsd:string">A</ResultCode>
<Status xsi:type="xsd:string">Pending</Status>
<StatusCode xsi:type="xsd:string">P</StatusCode>
<VpasResultCode xsi:type="xsd:string"></VpasResultCode>
</captureTransactionReturn>
</ns1:captureTransactionResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Move an authorized transaction into the current batch for settlement. It is possible to capture an amount other than the one originally authorized, however, you must follow the guidelines established by the merchant service bank. Capturing a higher or lower dollar amount could result in additional penalties and fees.
Most banks typically allow no more than 10 days to pass between the authorization/capture and settlement of a transaction.
If you do not wish to capture a previously authorized transaction, you may void the original authorization rather than capturing a 0 dollar amount, or simply allow the captured transaction to time out.
Related Methods
Syntax
TransactionResponse captureTransaction ( ueSecurityToken Token, string RefNum, double Amount, string IfAuthExpired )
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| RefNum | string | Unique transaction reference number assigned by the gateway. You can also use TransKey in the RefNum field. |
| Amount | double | Capture Amount if different from authorization |
| IfAuthExpired | string | Controls what will happen if the authorization has expired. Possible values are: - Error will block the capture request - ReAuth will attempt to reauthorize the funds - Capture will ignore the authorization date and proceed with capture. If left blank, Capture will be assumed. The amount of time between an authorization expires is controlled by the Expire Auths After setting. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| %TransactionResponse% | object | Returns a TransactionResponse object containing the results of the transaction and all relevant data. |
Change Log
| Version | Change |
|---|---|
| 1.7 | TransKey can be used in RefNum field. |
postAuth
Example Request
<?php
try {
$Request=array(
'AccountHolder' => 'Tester Jones',
'Details' => array(
'Description' => 'Example Transaction',
'Amount' => '4.00',
'Invoice' => '44539'
),
'CreditCardData' => array(
'CardNumber' => '4444555566667779',
'CardExpiration' => '0919',
'AvsStreet' => '1234 Main Street',
'AvsZip' => '99281',
'CardCode' => '999'
)
);
$res=$client->postAuth($token, $Request);
print_r($res);
}
catch (SoapFault $e) {
echo $client->__getLastRequest();
echo $this->client->__getLastResponse();
die("QuickSale failed :" .$e->getMessage());
}
?>
try {
TransactionRequestObject params = new TransactionRequestObject();
// set card holder name and AuthCode
params.setAccountHolder("Test Joe");
params.setAuthCode("123123");
// populate transaction details
TransactionDetail details = new TransactionDetail();
details.setAmount(22.34);
details.setDescription("My Test Sale");
details.setInvoice("119891");
params.setDetails(details);
// populate credit card data
CreditCardData ccdata = new CreditCardData();
ccdata.setCardNumber("4444555566667779");
ccdata.setCardExpiration("0912");
ccdata.setCardCode("999");
params.setCreditCardData(ccdata);
// Create response object
TransactionResponse response;
// run sale
response = client.postAuth(token, params);
System.out.println("Response: " + response.getResult());
System.out.println("RefNum: " + response.getRefNum());
} catch (Exception e) {
System.out.println("Soap Exception: " + e.getMessage());
}
Dim client As usaepay.usaepayService = New usaepay.usaepayService
Dim token As usaepay.ueSecurityToken
token = Me.CreateToken("714SSUxv1uohng2XkMJ7kLpETsu58G66", "1234")
Dim transaction As usaepay.TransactionRequestObject = New usaepay.TransactionRequestObject
transaction.Details = New usaepay.TransactionDetail
transaction.Details.Amount = "11.11"
transaction.Details.AmountSpecified = "true"
transaction.Details.Invoice = "123456"
transaction.AuthCode = "009915"
transaction.RefNum = "46993455"
Dim response As usaepay.TransactionResponse = New usaepay.TransactionResponse
response = client.captureTransaction(token, transaction.RefNum, transaction.Details.Amount)
If response.ResultCode = "A" Then
MsgBox("Transaction Approved, Refnum: " & response.RefNum)
Else
MsgBox("Transaction Error, Reason: " & response.Error)
End If
usaepay.TransactionRequestObject tran = new usaepay.TransactionRequestObject();
tran.CreditCardData = new usaepay.CreditCardData();
tran.CreditCardData.CardNumber = "4444555566667779";
tran.CreditCardData.CardExpiration = "1212";
tran.CreditCardData.CardCode = "123";
tran.Details = new usaepay.TransactionDetail();
tran.Details.Amount = 1.01;
tran.Details.AmountSpecified = true;
tran.Details.Invoice = "123456";
tran.RefNum = "46973415";
tran.AuthCode = "035786";
usaepay.TransactionResponse response = new usaepay.TransactionResponse();
try
{
response = client.postAuth(token, tran);
if (response.ResultCode == "A")
{
MessageBox.Show(string.Concat("Transaction Approved, RefNum: ",
response.RefNum));
}
else
{
MessageBox.Show(string.Concat("Transaction Failed: ",
response.Error));
}
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="urn:usaepay"
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:postAuth>
<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">14c4f0deb8dda1f6e9260b3cc64544d08c036a7a</HashValue>
<Seed xsi:type="xsd:string">1219649637-test</Seed>
<Type xsi:type="xsd:string">sha1</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
</Token>
<Params xsi:type="ns1:TransactionRequestObject">
<AccountHolder xsi:type="xsd:string">Tester Jones</AccountHolder>
<AuthCode xsi:type="xsd:string">12345</AuthCode>
<BillingAddress xsi:type="ns1:Address">
<City xsi:type="xsd:string">Albany</City>
<Company xsi:type="xsd:string">testing</Company>
<Country xsi:type="xsd:string">Un</Country>
<FirstName xsi:type="xsd:string">SoapAPI</FirstName>
<LastName xsi:type="xsd:string">Testor</LastName>
<Phone xsi:type="xsd:string">5183310981</Phone>
<State xsi:type="xsd:string">NY</State>
<Street xsi:type="xsd:string">180 State st</Street>
<Street2 xsi:type="xsd:string">133 Lancaster st</Street2>
<Zip xsi:type="xsd:string">12210</Zip>
</BillingAddress>
<ClientIP xsi:type="xsd:string">123.123.123.123</ClientIP>
<Command xsi:type="xsd:string">sale</Command>
<CreditCardData xsi:type="ns1:CreditCardData">
<AvsStreet xsi:type="xsd:string">1234 Main Street</AvsStreet>
<AvsZip xsi:type="xsd:string">99281</AvsZip>
<CardCode xsi:type="xsd:string">123boatload1293</CardCode>
<CardExpiration xsi:type="xsd:string">1215</CardExpiration>
<CardNumber xsi:type="xsd:string">4444555566667779</CardNumber>
</CreditCardData>
<CustomerID xsi:type="xsd:string">123456</CustomerID>
<Details xsi:type="ns1:TransactionDetail">
<Amount xsi:type="xsd:double">22</Amount>
<Clerk xsi:type="xsd:string">John Doe</Clerk>
<Currency xsi:type="xsd:string">0</Currency>
<Description xsi:type="xsd:string">Example Transaction</Description>
<Discount xsi:type="xsd:double">10</Discount>
<Invoice xsi:type="xsd:string">44539</Invoice>
<OrderID xsi:type="xsd:string">12345</OrderID>
<PONum xsi:type="xsd:string">54321</PONum>
<Shipping xsi:type="xsd:double">2</Shipping>
<Subtotal xsi:type="xsd:double">12</Subtotal>
<Table xsi:type="xsd:string">1</Table>
<Tax xsi:type="xsd:double">10</Tax>
<Terminal xsi:type="xsd:string">15</Terminal>
<Tip xsi:type="xsd:double">8</Tip>
</Details>
<LineItems SOAP-ENC:arrayType="ns1:LineItem[1]" xsi:type="ns1:LineItemArray">
<item xsi:type="ns1:LineItem">
<SKU xsi:type="xsd:string">1234</SKU>
<ProductName xsi:type="xsd:string">Test Example</ProductName>
<Description xsi:type="xsd:string">Test</Description>
<UnitPrice xsi:type="xsd:string">19.99</UnitPrice>
<Qty xsi:type="xsd:string">9</Qty>
<Taxable xsi:type="xsd:boolean">true</Taxable>
</item>
</LineItems>
<ShippingAddress xsi:type="ns1:Address">
<City xsi:type="xsd:string">Los Angeles</City>
<Company xsi:type="xsd:string">Location 2</Company>
<Country xsi:type="xsd:string">Un</Country>
<FirstName xsi:type="xsd:string">Ship</FirstName>
<LastName xsi:type="xsd:string">Tome</LastName>
<Phone xsi:type="xsd:string">3133129163</Phone>
<State xsi:type="xsd:string">CA</State>
<Street xsi:type="xsd:string">9999 s sycamore</Street>
<Street2 xsi:type="xsd:string">9999 Lancaster st</Street2>
<Zip xsi:type="xsd:string">90036</Zip>
</ShippingAddress>
</Params>
</ns1:postAuth>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example Response
<?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="urn:usaepay"
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:postAuthResponse>
<postAuthReturn xsi:type="ns1:TransactionResponse">
<AcsUrl xsi:type="xsd:string"></AcsUrl>
<AuthAmount xsi:type="xsd:double">0</AuthAmount>
<AuthCode xsi:type="xsd:string"></AuthCode>
<AvsResult xsi:type="xsd:string">No AVS response(Typically no AVS data sent or swiped transaction)
</AvsResult>
<AvsResultCode xsi:type="xsd:string"></AvsResultCode>
<BatchNum xsi:type="xsd:string">0</BatchNum>
<BatchRefNum xsi:type="xsd:string">0</BatchRefNum>
<CardCodeResult xsi:type="xsd:string">No CVV2/CVC data available for transaction.</CardCodeResult>
<CardCodeResultCode xsi:type="xsd:string"></CardCodeResultCode>
<CardLevelResult xsi:type="xsd:string">Unknown Code</CardLevelResult>
<CardLevelResultCode xsi:type="xsd:string"></CardLevelResultCode>
<ConversionRate xsi:type="xsd:double">0</ConversionRate>
<ConvertedAmount xsi:type="xsd:double">0</ConvertedAmount>
<ConvertedAmountCurrency xsi:type="xsd:string">840</ConvertedAmountCurrency>
<CustNum xsi:type="xsd:string">0</CustNum>
<Error xsi:type="xsd:string"></Error>
<ErrorCode xsi:type="xsd:integer">0</ErrorCode>
<isDuplicate xsi:type="xsd:boolean">false</isDuplicate>
<Payload xsi:type="xsd:string"></Payload>
<RefNum xsi:type="xsd:string">102183394</RefNum>
<Result xsi:type="xsd:string">Approved</Result>
<ResultCode xsi:type="xsd:string">A</ResultCode>
<Status xsi:type="xsd:string">Pending</Status>
<StatusCode xsi:type="xsd:string">P</StatusCode>
<VpasResultCode xsi:type="xsd:string"></VpasResultCode>
</postAuthReturn>
</ns1:postAuthResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
This method allows merchants to post authorization codes obtained offline (ie: telephone authorization) which may be required for some credit card sales depending on the policies of the card's bank of issue.
Related Methods
- runTransaction
- runQuickSale
- voidTransaction
- runCredit
- runSale
- captureTransaction
- getTransactionStatus
- runAuthOnly
Syntax
TransactionResponse postAuth ( ueSecurityToken Token, TransactionRequestObject Params )
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| RefNum | string | Unique transaction reference number assigned by the gateway. You can also use TransKey in the RefNum field. |
| %TransactionRequestObject% | Params | Transaction details from all fields of the transaction form. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| %TransactionResponse% | object | Returns a TransactionResponse object containing the results of the transaction and all relevant data. |
overrideTransaction
Example Request
string refnum;
string reason;
refnum = "46976525";
reason = "Because it is test";
//usaepay.TransactionResponse response = new usaepay.TransactionResponse();
Boolean response;
try
{
response = client.overrideTransaction(token, refnum, reason);
if (response)
{
MessageBox.Show(string.Concat("Transaction was overrided successfully"));
}
else MessageBox.Show(string.Concat("Error"));
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
Dim client As usaepay.usaepayService = New usaepay.usaepayService
Dim token As usaepay.ueSecurityToken
token = Me.CreateToken("714SSUxv1uohng2XkMJ7kLpETsu58G66", "1234")
Dim refnum As String
refnum = 47019830
Dim reason As String
reason = "Test"
Dim response As Boolean
response = client.overrideTransaction(token, refnum, reason)
If response = True Then
MsgBox("Override Successful.")
Else
MsgBox("An Error Occured.")
End If
This method can be used to override a transaction that has been flagged for manager approval.
Currently this method applies only to electronic check transactions.
Related Methods
Syntax
boolean overrideTransaction ( ueSecurityToken Token, string RefNum, string Reason )
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| RefNum | string | Unique transaction reference number assigned by the gateway. You can also use TransKey in the RefNum field. |
| Reason | string | Description of override reason. (Optional, only used with select check processors) |
Response Parameters
| Name | Type | Description |
|---|---|---|
| overrideTransactionReturn | boolean | Denotes if override was successful. |
Change Log
| Version | Description |
|---|---|
| 1.7 | TransKey can be used in RefNum field. |
Legacy API Methods
runTransaction
Example Request
<?php
try {
$Request=array(
'AccountHolder' => 'Tester Jones',
'Details' => array(
'Description' => 'Example Transaction',
'Amount' => '4.00',
'Invoice' => '44539'
),
'CreditCardData' => array(
'CardNumber' => '4444555566667779',
'CardExpiration' => '0919',
'AvsStreet' => '1234 Main Street',
'AvsZip' => '99281',
'CardCode' => '999'
)
);
$res=$client->runTransaction($token, $Request);
print_r($res);
}
catch (SoapFault $e){
echo $client->__getLastRequest();
echo $client->__getLastResponse();
die("runTransaction failed :" .$e->getMessage());
}
?>
try {
TransactionRequestObject params = new TransactionRequestObject();
// set card holder name
params.setAccountHolder("Test Joe");
params.setCommand("Sale");
// populate transaction details
TransactionDetail details = new TransactionDetail();
details.setAmount(22.34);
details.setDescription("My Test Sale");
details.setInvoice("119891");
params.setDetails(details);
// populate credit card data
CreditCardData ccdata = new CreditCardData();
ccdata.setCardNumber("4444555566667779");
ccdata.setCardExpiration("0919");
ccdata.setCardCode("999");
params.setCreditCardData(ccdata);
// Create request object
RunTransaction request = new RunTransaction();
request.setToken(token);
// Create response object
TransactionResponse response;
// run transaction
response = client.runTransaction(token, params);
System.out.println("Result: " + response.getResult());
} catch (Exception e) {
System.out.println("Soap Exception: " + e.getMessage());
}
Dim client As usaepay.usaepayService = New usaepay.usaepayService
Dim token As usaepay.ueSecurityToken
token = Me.CreateToken("714SSUxv1uohng2XkMJ7kLpETsu58G66", "1234")
Dim tran As usaepay.TransactionRequestObject = New usaepay.TransactionRequestObject
tran.CreditCardData = New usaepay.CreditCardData
tran.CreditCardData.CardNumber = "4444555566667779"
tran.CreditCardData.CardExpiration = "0919"
tran.CreditCardData.CardCode = "999"
tran.Details = New usaepay.TransactionDetail
tran.Details.Amount = 9.02
tran.Details.AmountSpecified = True
tran.Details.Invoice = "434534"
tran.Details.Description = "Example transaction"
tran.Command = "sale"
Dim response As usaepay.TransactionResponse
response = client.runTransaction(token, tran)
If response.ResultCode = "A" Then
MsgBox("Transaction Approved, Refernce Number: " & response.RefNum)
ElseIf response.ResultCode = "D" Then
MsgBox("Transaction Declined, Reason: " & response.Error)
Else
MsgBox("Transaction Error, Reason: " & response.Error)
End If
usaepay.TransactionRequestObject tran = new usaepay.TransactionRequestObject();
tran.Command = "cc:sale";
tran.Details = new usaepay.TransactionDetail();
tran.Details.Amount = 1.00;
tran.Details.AmountSpecified = true;
tran.Details.Invoice = "1234";
tran.Details.Description = "Example Transaction";
tran.CreditCardData = new usaepay.CreditCardData();
tran.CreditCardData.CardNumber = "4444555566667779";
tran.CreditCardData.CardExpiration = "0919";
usaepay.TransactionResponse response = new usaepay.TransactionResponse();
try
{
response = client.runTransaction(token, tran);
if (response.ResultCode == "A")
{
MessageBox.Show(string.Concat("Transaction Approved, RefNum: ",
response.RefNum));
}
else
{
MessageBox.Show(string.Concat("Transaction Failed: ",
response.Error));
}
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="urn:usaepay"
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:runTransaction>
<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"> 58bdbfeb7c15078fa62291bd6a4473990dd50dd8 </HashValue>
<Seed xsi:type="xsd:string"> 11139209200-test </Seed>
<Type xsi:type="xsd:string"> sha1 </Type>
</PinHash>
<SourceKey xsi:type="xsd:string"> _B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT </SourceKey>
</Token>
<Parameters xsi:type="ns1:TransactionRequestObject">
<AccountHolder xsi:type="xsd:string"> Tester Jones </AccountHolder>
<BillingAddress xsi:type="ns1:Address">
<City xsi:type="xsd:string"> Albany </City>
<Company xsi:type="xsd:string"> testing </Company>
<Country xsi:type="xsd:string"> Un </Country>
<FirstName xsi:type="xsd:string"> Timmy </FirstName>
<LastName xsi:type="xsd:string"> Rodriguez </LastName>
<Phone xsi:type="xsd:string"> -5555 </Phone>
<State xsi:type="xsd:string"> APO AE 09021 </State>
<Street xsi:type="xsd:string"> 180 State st </Street>
<Street2 xsi:type="xsd:string"> 133 Lancaster st </Street2>
<Zip xsi:type="xsd:string"> 12210 </Zip>
</BillingAddress>
<ClientIP xsi:type="xsd:string"> 123.123.123.123 </ClientIP>
<Command xsi:type="xsd:string"> sale </Command>
<CreditCardData xsi:type="ns1:CreditCardData">
<AvsStreet xsi:type="xsd:string"> 1234 Main Street </AvsStreet>
<AvsZip xsi:type="xsd:string"> 99281 </AvsZip>
<CardCode xsi:type="xsd:string"> 999 </CardCode>
<CardExpiration xsi:type="xsd:string"> 1018 </CardExpiration>
<CardNumber xsi:type="xsd:string"> 4444555566667779 </CardNumber>
</CreditCardData>
<CustomerID xsi:type="xsd:string"> 123456 </CustomerID>
<CustomFields SOAP-ENC:arrayType="ns1:FieldValue[2]" xsi:type="ns1:FieldValueArray">
<item xsi:type="ns1:FieldValue">
<Field xsi:type="xsd:string"> custom1 </Field>
<Value xsi:type="xsd:string"> Cya </Value>
</item>
<item xsi:type="ns1:FieldValue">
<Field xsi:type="xsd:string"> custom2 </Field>
<Value xsi:type="xsd:string"> Booyah </Value>
</item>
</CustomFields>
<CustReceipt xsi:type="xsd:boolean"> true </CustReceipt>
<Details xsi:type="ns1:TransactionDetail">
<Amount xsi:type="xsd:double"> 5.99 </Amount>
<Clerk xsi:type="xsd:string"> John Doe </Clerk>
<Currency xsi:type="xsd:string"> 0 </Currency>
<Description xsi:type="xsd:string"> Example Transaction </Description>
<Invoice xsi:type="xsd:string"> 44539 </Invoice>
<OrderID xsi:type="xsd:string"> 12345 </OrderID>
<PONum xsi:type="xsd:string"> 54321 </PONum>
<Shipping xsi:type="xsd:double"> 2 </Shipping>
<Table xsi:type="xsd:string"> 1 </Table>
<Terminal xsi:type="xsd:string"> 15 </Terminal>
</Details>
<LineItems SOAP-ENC:arrayType="ns1:LineItem[2]" xsi:type="ns1:LineItemArray">
<item xsi:type="ns1:LineItem">
<SKU xsi:type="xsd:string"> 1234 </SKU>
<ProductName xsi:type="xsd:string"> Boogers </ProductName>
<Description xsi:type="xsd:string"> Rock On </Description>
<UnitPrice xsi:type="xsd:string"> 19.99 </UnitPrice>
<Qty xsi:type="xsd:string"> 9 </Qty>
<Taxable xsi:type="xsd:boolean"> true </Taxable>
</item>
<item xsi:type="ns1:LineItem">
<SKU xsi:type="xsd:string"> 333 </SKU>
<ProductName xsi:type="xsd:string"> Stuff </ProductName>
<Description xsi:type="xsd:string"> Yahoo </Description>
<UnitPrice xsi:type="xsd:string"> 19.21 </UnitPrice>
<Qty xsi:type="xsd:string"> 5 </Qty>
<Taxable xsi:type="xsd:boolean"> true </Taxable>
</item>
</LineItems>
<ShippingAddress xsi:type="ns1:Address">
<City xsi:type="xsd:string"> Los Angeles </City>
<Company xsi:type="xsd:string"> SomeOtherCompany </Company>
<Country xsi:type="xsd:string"> Un </Country>
<FirstName xsi:type="xsd:string"> Ship </FirstName>
<LastName xsi:type="xsd:string"> Tome </LastName>
<Phone xsi:type="xsd:string"> 3133129163 </Phone>
<State xsi:type="xsd:string"> CA </State>
<Street xsi:type="xsd:string"> 9999 s sycamore </Street>
<Street2 xsi:type="xsd:string"> 9999 Lancaster st </Street2>
<Zip xsi:type="xsd:string"> 90036 </Zip>
</ShippingAddress>
</Parameters>
</ns1:runTransaction>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example Response
<?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="urn:usaepay"
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:runTransactionResponse>
<runTransactionReturn xsi:type="ns1:TransactionResponse">
<AcsUrl xsi:type="xsd:string"> </AcsUrl>
<AuthAmount xsi:type="xsd:double"> 5.99 </AuthAmount>
<AuthCode xsi:type="xsd:string"> 025821 </AuthCode>
<AvsResult xsi:type="xsd:string"> Address: Match & 5 Digit Zip: Match </AvsResult>
<AvsResultCode xsi:type="xsd:string"> YYY </AvsResultCode>
<BatchNum xsi:type="xsd:string"> 1 </BatchNum>
<BatchRefNum xsi:type="xsd:string"> 9597 </BatchRefNum>
<CardCodeResult xsi:type="xsd:string"> Match </CardCodeResult>
<CardCodeResultCode xsi:type="xsd:string"> M </CardCodeResultCode>
<CardLevelResult xsi:type="xsd:string"> Visa Traditional </CardLevelResult>
<CardLevelResultCode xsi:type="xsd:string"> A </CardLevelResultCode>
<ConversionRate xsi:type="xsd:double"> 0 </ConversionRate>
<ConvertedAmount xsi:type="xsd:double"> 0 </ConvertedAmount>
<ConvertedAmountCurrency xsi:type="xsd:string"> 840 </ConvertedAmountCurrency>
<CustNum xsi:type="xsd:string"> 0 </CustNum>
<Error xsi:type="xsd:string"> Approved </Error>
<ErrorCode xsi:type="xsd:integer"> 0 </ErrorCode>
<isDuplicate xsi:type="xsd:boolean"> false </isDuplicate>
<Payload xsi:type="xsd:string"> </Payload>
<RefNum xsi:type="xsd:string"> 100071480 </RefNum>
<Result xsi:type="xsd:string"> Approved </Result>
<ResultCode xsi:type="xsd:string"> A </ResultCode>
<Status xsi:type="xsd:string"> Pending </Status>
<StatusCode xsi:type="xsd:string"> P </StatusCode>
<VpasResultCode xsi:type="xsd:string"> </VpasResultCode>
</runTransactionReturn>
</ns1:runTransactionResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
This method duplicates the functionality of the gateway API. It can be used to run a wide variety of transaction types including sales, credits, authonly, void, and checks.
The parameters argument is a TransactionRequestObject containing any of the variable names supported by the Transaction API (See the docs for a list of valid field names). Make sure to remove the UM from the front of the field names. (ie: UMamount should be passed as Amount.)
Related Methods
- runSale
- runCredit
- runAuthOnly
- runQuickSale
- postAuth
- captureTransaction
- voidTransaction
- getTransactionStatus
- getTransaction
- getTransactionCustom
- searchTransactions
- searchTransactionsCustom
- getTransactionReport
Syntax
TransactionResponse runTransaction ( ueSecurityToken Token, TransactionRequestObject Params )
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| %TransactionRequestObject% | Params | Transaction details from all fields of the transaction form. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| %TransactionResponse% | object | Returns a TransactionResponse object containing the results of the transaction and all relevant data. |
runTransactionAPI
Example Request
<?php
$Request=array(
array('Field'=>'UMname', 'Value'=>'Tester Jones'),
array('Field'=>'UMdescription', 'Value'=>'runTrasactionAPI sale'),
array('Field'=>'UMamount', 'Value'=>'3.51'),
array('Field'=>'UMinvoice', 'Value'=>'12345'),
array('Field'=>'UMcard', 'Value'=>'4444555566667779'),
array('Field'=>'UMexpir', 'Value'=>'0919'),
array('Field'=>'UMstreet', 'Value'=>'1234 Main Street'),
array('Field'=>'UMzip', 'Value'=>'99281'),
array('Field'=>'UMcvv2', 'Value'=>'444')
);
$res=$client->runTransactionAPI($token, $Request);
print_r($res);
?>
Dim client As usaepay.usaepayService = New usaepay.usaepayService
Dim token As usaepay.ueSecurityToken
token = Me.CreateToken("714SSUxv1uohng2XkMJ7kLpETsu58G66", "1234")
Dim Fields(0 To 9) As usaepay.FieldValue
Dim i As Integer
For i = 0 To 9
Fields(i) = New usaepay.FieldValue
Next i
Fields(0).Field = "UMname"
Fields(0).Value = "Tester Jones"
Fields(1).Field = "UMdescription"
Fields(1).Value = "Visual Basic For Dummies"
Fields(2).Field = "UMamount"
Fields(2).Value = "1.00"
Fields(3).Field = "UMinvoice"
Fields(3).Value = "12345"
Fields(4).Field = "UMcard"
Fields(4).Value = "4444555566667779"
Fields(5).Field = "UMexpir"
Fields(5).Value = "1219"
Fields(6).Field = "UMstreet"
Fields(6).Value = "1234 Main Street"
Fields(7).Field = "UMzip"
Fields(7).Value = "90210"
Fields(8).Field = "UMcvv2"
Fields(8).Value = "999"
Dim response As usaepay.TransactionResponse
response = client.runTransactionAPI(token, Fields)
MsgBox("Reference Number: " & response.RefNum)
usaepay.FieldValue[] tran = new usaepay.FieldValue[9];
for (int i = 0; i < 9; i++)
{
tran[i] = new usaepay.FieldValue();
}
tran[0].Field = "UMname"; tran[0].Value = "Tester Jones";
tran[1].Field = "UMdescription"; tran[1].Value = "runTransactionAPI sale";
tran[2].Field = "UMamount"; tran[2].Value = "1.00";
tran[3].Field = "UMinvoice"; tran[3].Value = "12345";
tran[4].Field = "UMcard"; tran[4].Value = "4444555566667779";
tran[5].Field = "UMexpir"; tran[5].Value = "1219";
tran[6].Field = "UMstreet"; tran[6].Value = "123 Main Street";
tran[7].Field = "UMzip"; tran[7].Value = "90046";
tran[8].Field = "UMcvv2"; tran[8].Value = "999";
usaepay.TransactionResponse response = new usaepay.TransactionResponse();
try
{
response = client.runTransactionAPI(token, tran);
if (response.ResultCode == "A")
{
MessageBox.Show(string.Concat("Transaction Approved, RefNum: ",
response.RefNum));
}
else
{
MessageBox.Show(string.Concat("Transaction Failed: ",
response.Error));
}
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="urn:usaepay"
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:runTransactionAPI>
<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">439257fdca69c2b66565971fced3cc54ec5a6722</HashValue>
<Seed xsi:type="xsd:string">112970899-test</Seed>
<Type xsi:type="xsd:string">sha1</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
</Token>
<Parameters SOAP-ENC:arrayType="ns1:FieldValue[9]" xsi:type="ns1:FieldValueArray">
<item xsi:type="ns1:FieldValue">
<Field xsi:type="xsd:string">UMname</Field>
<Value xsi:type="xsd:string">Tester Jones</Value>
</item>
<item xsi:type="ns1:FieldValue">
<Field xsi:type="xsd:string">UMdescription</Field>
<Value xsi:type="xsd:string">runTrasactionAPI sale</Value>
</item>
<item xsi:type="ns1:FieldValue">
<Field xsi:type="xsd:string">UMamount</Field>
<Value xsi:type="xsd:string">3.51</Value>
</item>
<item xsi:type="ns1:FieldValue">
<Field xsi:type="xsd:string">UMinvoice</Field>
<Value xsi:type="xsd:string">12345</Value>
</item>
<item xsi:type="ns1:FieldValue">
<Field xsi:type="xsd:string">UMcard</Field>
<Value xsi:type="xsd:string">4444555566667779</Value>
</item>
<item xsi:type="ns1:FieldValue">
<Field xsi:type="xsd:string">UMexpir</Field>
<Value xsi:type="xsd:string">0919</Value>
</item>
<item xsi:type="ns1:FieldValue">
<Field xsi:type="xsd:string">UMstreet</Field>
<Value xsi:type="xsd:string">1234 Main Street</Value>
</item>
<item xsi:type="ns1:FieldValue">
<Field xsi:type="xsd:string">UMzip</Field>
<Value xsi:type="xsd:string">99281</Value>
</item>
<item xsi:type="ns1:FieldValue">
<Field xsi:type="xsd:string">UMcvv2</Field>
<Value xsi:type="xsd:string">444</Value>
</item>
</Parameters>
</ns1:runTransactionAPI>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example Response
<?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="urn:usaepay" 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:runTransactionAPIResponse>
<runTransactionAPIReturn xsi:type="ns1:TransactionResponse">
<AcsUrl xsi:type="xsd:string"></AcsUrl>
<AuthAmount xsi:type="xsd:double">3.51</AuthAmount>
<AuthCode xsi:type="xsd:string">037497</AuthCode>
<AvsResult xsi:type="xsd:string">Address: Match & 5 Digit Zip: Match</AvsResult>
<AvsResultCode xsi:type="xsd:string">YYY</AvsResultCode>
<BatchNum xsi:type="xsd:string">1</BatchNum>
<BatchRefNum xsi:type="xsd:string">9597</BatchRefNum>
<CardCodeResult xsi:type="xsd:string">No Match</CardCodeResult>
<CardCodeResultCode xsi:type="xsd:string">N</CardCodeResultCode>
<CardLevelResult xsi:type="xsd:string">Visa Traditional</CardLevelResult>
<CardLevelResultCode xsi:type="xsd:string">A</CardLevelResultCode>
<ConversionRate xsi:type="xsd:double">0</ConversionRate>
<ConvertedAmount xsi:type="xsd:double">0</ConvertedAmount>
<ConvertedAmountCurrency xsi:type="xsd:string">840</ConvertedAmountCurrency>
<CustNum xsi:type="xsd:string">0</CustNum>
<Error xsi:type="xsd:string">Approved</Error>
<ErrorCode xsi:type="xsd:integer">0</ErrorCode>
<isDuplicate xsi:type="xsd:boolean">false</isDuplicate>
<Payload xsi:type="xsd:string"></Payload>
<RefNum xsi:type="xsd:string">100106558</RefNum>
<Result xsi:type="xsd:string">Approved</Result>
<ResultCode xsi:type="xsd:string">A</ResultCode>
<Status xsi:type="xsd:string">Pending</Status>
<StatusCode xsi:type="xsd:string">P</StatusCode>
<VpasResultCode xsi:type="xsd:string"></VpasResultCode>
</runTransactionAPIReturn>
</ns1:runTransactionAPIResponse>
</SOAP-ENV:Body>
The parameters argument is an array containing any of the variable names supported by the (#transaction-api).
This method requires more work to implement than the runTransaction method, and typically should not be your first choice for processing transactions. The one benefit of using this method is that it provides a direct interface to the transaction processing engine of the gateway. As new fields are added to the system they can be used immediately via this method without having to wait for the next Soap release or generate a new WSDL link. The runTransaction method on the other hand has its Transaction Request Object tied to the Soap release (and wsdl url). To access new fields you would have to generate a new WSDL link.
NOTE: In previous releases this method was called runOldApi.
Related Methods
Syntax
TransactionResponse runTransactionAPI ( ueSecurityToken Token, FieldValue Params )
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| Params | array | Array of variables in (FieldValue)(#fieldvalue) format to pass to Transaction API. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| %TransactionResponse% | object | Returns a TransactionResponse object containing the results of the transaction and all relevant data. |
Bulk Transaction Uploads
createBatchUpload
Example Request
<?php
try {
$filename=date("ymd") . ".csv";
$autostart=true;
$format="csv";
$encoding="base64";
$fields=array('invoice','cardholder','avsstreet','avszip','ccnum', "ccexp", "amount");
$data=base64_encode(file_get_contents("./upload-mini.csv"));
$dupess=false;
print_r($client->createBatchUpload($token,$filename,$autostart, $format, $encoding,$fields, $data, $dupes));
}
catch(SoapFault $e) {
echo $e->getMessage();
echo "\n\nRequest: " . $tran->__getLastRequest();
echo "\n\nResponse: " . $tran->__getLastResponse();
}
?>
try {
// Create request object
String FileName = "ExampleFile.csv";
String Format = "csv";
String Encoding = "base64";
StringArray Fields = new StringArray();
Fields.add("invoice");
Fields.add("cardholder");
Fields.add("avsstreet");
Fields.add("avszip");
Fields.add("ccnum");
Fields.add("ccexp");
Fields.add("amount");
String RawData = "12345,John Doe,1234 Test St,54321,4000100011112224,1012,1.23\n54321,Joe Test,4321 Example St,12345,4000100111112223,0313,12.34";
BASE64Encoder encoder = new BASE64Encoder();
String Data = encoder.encodeBuffer(RawData.getBytes());
boolean AutoStart = true;
boolean OverrideDuplicates = true;
// Create response object
BatchUploadStatus response;
response = client.createBatchUpload(token, FileName,AutoStart,Format,Encoding,Fields,Data,OverrideDuplicates);
} catch (Exception e) {
System.out.println("Soap Exception: " + e.getMessage());
}
Dim service As usaepay.usaepayService = _
New usaepay.usaepayService
Dim uploaddata As String
uploaddata = "1234,4444555566667779,0909,1.56,tester joens" & _
vbLf & "1235,4444555566667779,0909,2.22,bob hope"
Dim res As usaepay.BatchUploadStatus = New usaepay.BatchUploadStatus
res = service.createBatchUpload(Me.getSecurityToken(), _
"test.csv", _
True, _
"csv", _
"base64", _
"invoice,ccnum,ccexp,amount,cardholder", _
Convert.ToBase64String(Encoding.Default.GetBytes(uploaddata)), _
False)
MsgBox("New Batch #" & res.UploadRefNum & " trans: " & res.Remaining)
usaepay.BatchUploadStatus res = new usaepay.BatchUploadStatus();
string[] fields = new string[11];
fields[0] = "command";
fields[1] = "vcrouting";
fields[2] = "vcaccount";
fields[3] = "amount";
fields[4] = "invoice";
fields[5] = "cardholder";
fields[6] = "avsstreet";
fields[7] = "avszip";
fields[8] = "description";
fields[9] = "vcdl";
fields[10] = "vcdlstate";
String fileContents;
fileContents = System.IO.File.ReadAllText(@"C:\checkexample.csv");
try
{
res = client.createBatchUpload(token, "checkexample.csv", true, "csv", "base64", fields,
Convert.ToBase64String(Encoding.Default.GetBytes(fileContents)), false);
MessageBox.Show(string.Concat("New Batch #", res.UploadRefNum, " trans:", res.Remaining));
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
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:createBatchUpload>
<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">ef9781f240de9c286f94cb3180f0a6516e9592f9</HashValue>
<Seed xsi:type="xsd:string">11015516479-test</Seed>
<Type xsi:type="xsd:string">sha1</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
</Token>
<FileName xsi:type="xsd:string">war</FileName>
<AutoStart xsi:type="xsd:boolean">true</AutoStart>
<Format xsi:type="xsd:string">csv</Format>
<Encoding xsi:type="xsd:string">base64</Encoding>
<Fields SOAP-ENC:arrayType="xsd:string[6]" xsi:type="ns1:stringArray">
<item xsi:type="xsd:string">cardholder</item>
<item xsi:type="xsd:string">ccnum</item>
<item xsi:type="xsd:string">ccexp</item>
<item xsi:type="xsd:string">avsstreet</item>
<item xsi:type="xsd:string">avszip</item>
<item xsi:type="xsd:string">amount</item>
</Fields>
<Data xsi:type="xsd:string">Ik9zY2FyIExvdW5nZSIsNDQ0NDU1NTU2NjY2Nzc3OSwwOTE5LCIxMDEwIEF2ZSBTVCIsOTAwODYsOTAK</Data>
<OverrideDuplicates xsi:type="xsd:boolean">false</OverrideDuplicates>
</ns1:createBatchUpload>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example Response
<?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
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:createBatchUploadResponse>
<createBatchUploadReturn xsi:type="ns1:BatchUploadStatus">
<Approved xsi:type="xsd:integer">0</Approved>
<UploadRefNum xsi:type="xsd:integer">28</UploadRefNum>
<Declined xsi:type="xsd:integer">0</Declined>
<Errors xsi:type="xsd:integer">0</Errors>
<Finished xsi:type="xsd:string"></Finished>
<Remaining xsi:type="xsd:string">1</Remaining>
<Started xsi:type="xsd:string">2016-01-13 15:13:59</Started>
<Status xsi:type="xsd:string">Pending</Status>
<Transactions xsi:type="xsd:integer">1</Transactions>
</createBatchUploadReturn>
</ns1:createBatchUploadResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
This method implements the same batch upload functionality as the Batch Upload screens in the merchant console. Batches uploaded via this method will be visible in the Upload Manager screen.
Once a batch has been sent to the gateway for processing, it is possible to pause the batch using the pauseBatchUpload method, and resume the upload later using the runBatchUpload method.
The following fields are available for upload:
| command | cardholder | checknum | billing_company | shipping_company |
| source | ccnum | vcrouting | billing_fname | shipping_fname |
| invoice | ccexp | vcaccount | billing_lname | shipping_lname |
| amount | avsstreet | vcssn | billing_street | shipping_street |
| tax | avszip | vcdl | billing_street2 | shipping_street2 |
| description | cvc | vcdlstate | billing_city | shipping_city |
| ponum | billing_state | shipping_state | ||
| orderid | billing_country | shipping_zip | ||
| custid | billing_zip | shipping_country | ||
| billing_phone | shipping_phone |
Related Methods
Syntax
BatchUploadStatus createBatchUpload ( ueSecurityToken Token, string, FileName, boolean, AutoStart, string Format, string Encoding, string Fields, string Data, boolean, OverrideDuplicates )
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| FileName | string | Name of upload file. Can also be used to store a reference ID. |
| AutoStart | boolean | If true, the batch will start running automatically. Otherwise the batch must be started manually, either using the runBatchUpload method or via the Merchant Console. |
| Format | string | The format of the data upload. Currently supported data formats are: csv, tab and xml. |
| Encoding | string | Data encoding method used. Supported methods include: 7bit, base64 and uuencode. |
| Fields | string | Fields being uploaded. These fields must be listed in the same order they appear in the data |
| Data | string | Transaction data being uploaded. |
| OverrideDuplicates | boolean | By default, a batch will be rejected if a certain percentage of the transactions have been uploaded before. Setting this option to true will override the duplicate check. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| %BatchUploadStatus% | object | Returns the result of the batch upload. |
getBatchUploadStatus
Example Request
<?php
try {
$uploadrefnum='127';
print_r($tran->getBatchUploadStatus($sourcekey,$uploadrefnum));
}
catch(SoapFault $e) {
echo $e->getMessage();
echo "\n\nRequest: " . $tran->__getLastRequest();
echo "\n\nResponse: " . $tran->__getLastResponse();
}
?>
Dim uploadrefnum As String
uploadrefnum = "1169"
Dim res As usaepay.BatchUploadStatus = New usaepay.BatchUploadStatus
res = client.getBatchUploadStatus(token, uploadrefnum)
MsgBox(res.Status)
string uploadrefnum = "1137";
usaepay.BatchUploadStatus res = new usaepay.BatchUploadStatus();
try
{
res = client.getBatchUploadStatus(token, uploadrefnum);
MessageBox.Show(string.Concat(res.Status));
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
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:getBatchUploadStatus>
<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">57cfe9f70f65de841995a738f57705d18c4d1e4c</HashValue>
<Seed xsi:type="xsd:string">11489158408-test</Seed>
<Type xsi:type="xsd:string">sha1</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
</Token>
<UploadRefNum xsi:type="xsd:string">79</UploadRefNum>
</ns1:getBatchUploadStatus>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example Response
<?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
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:getBatchUploadStatusResponse>
<getBatchUploadStatusReturn xsi:type="ns1:BatchUploadStatus">
<Approved xsi:type="xsd:integer">0</Approved>
<UploadRefNum xsi:type="xsd:string">79</UploadRefNum>
<Declined xsi:type="xsd:integer">0</Declined>
<Errors xsi:type="xsd:integer">0</Errors>
<Finished xsi:type="xsd:string"></Finished>
<Remaining xsi:type="xsd:integer">1</Remaining>
<Started xsi:type="xsd:string">2016-01-14 15:42:19</Started>
<Status xsi:type="xsd:string">Running</Status>
<Transactions xsi:type="xsd:integer">1</Transactions>
</getBatchUploadStatusReturn>
</ns1:getBatchUploadStatusResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
This method allows you to retrieve the status of a currently running batch.
This method is useful in determining whether a batch has been submitted to the gateway for processing, has been paused or is waiting to be uploaded.
To retrieve the status of batches other than the currently running batch, use the (#getbatchstatus) method.
Syntax
BatchUploadStatus getBatchUploadStatus ( ueSecurityToken Token, string UploadRefNum )
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| UploadRefNum | string | Upload reference number (assigned by the gateway). |
Response Parameters
| Name | Type | Description |
|---|---|---|
| %BatchUploadStatus% | object | Returns the status of the currently running batch. Possible results include: open, closing, closed. |
getBatchUploadTransactions
Example Request
<?php
try {
$uploadrefnum='127';
print_r($tran->getBatchUploadTransactions($sourcekey,$uploadrefnum));
}
catch(SoapFault $e) {
echo $e->getMessage();
echo "\n\nRequest: " . $tran->__getLastRequest();
echo "\n\nResponse: " . $tran->__getLastResponse();
}
?>
Retrieve the transaction details for a Batch Upload.
This method allows you to retrieve the transaction details for a batch upload.
Related Methods
Syntax
( ueSecurityToken Token, string UploadRefNum )
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| UploadRefNum | string | Upload reference number (assigned by the gateway). |
Response Parameters
| Name | Type | Description |
|---|---|---|
| %TransactionResponse% | array | Array of transaction objects of the transactions in the batch upload. |
Change Log
| Version | Change |
|---|---|
| 1.7 | Added Method. |
pauseBatchUpload
Example Request
<?php
try {
$uploadrefnum='127';
print_r($tran->pauseBatchUpload($token,$uploadrefnum));
}
catch(SoapFault $e) {
echo $e->getMessage();
echo "\n\nRequest: " . $tran->__getLastRequest();
echo "\n\nResponse: " . $tran->__getLastResponse();
}
?>
Dim uploadrefnum As String
uploadrefnum = "1169"
Dim res As Boolean
res = client.pauseBatchUpload(token, uploadrefnum)
MsgBox(res)
string uploadrefnum = "1137";
Boolean res;
try
{
res = client.pauseBatchUpload(token, uploadrefnum);
MessageBox.Show(string.Concat(res));
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
< <?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
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:pauseBatchUpload>
<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">7a4753dd5d3f191ce5ab702f466e9c64c05baddb</HashValue>
<Seed xsi:type="xsd:string">11269237216-test</Seed>
<Type xsi:type="xsd:string">sha1</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
</Token>
<UploadRefNum xsi:type="xsd:string">73</UploadRefNum>
</ns1:pauseBatchUpload>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example Response
<?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
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:pauseBatchUploadResponse>
<pauseBatchUploadReturn xsi:type="xsd:boolean">true</pauseBatchUploadReturn>
</ns1:pauseBatchUploadResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
This method pauses the gateway processing of a batch that is being uploaded. Pausing a currently running batch until the upload has been completed allows for time to double check transactions and confirm the gateway processing of the batch before sending it to the gateway.
Use the (#runbatchupload) method to resume gateway processing of the batch.
For more information about uploading batches to the gateway for processing, please refer to documentation of the (#createbatchupload) method.
Related Methods
Syntax
boolean pauseBatchUpload ( ueSecurityToken Token, string UploadRefNum )
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| UploadRefNum | string | Upload reference number (assigned by the gateway). |
Response Parameters
| Name | Type | Description |
|---|---|---|
| pauseBatchUploadReturn | boolean | Returns confirmation of request only if successful. If request fails, an exception will be thrown. |
runBatchUpload
Example Request
<?php
try {
$uploadrefnum='127';
print_r($tran->runBatchUpload($token,$uploadrefnum));
}
catch(SoapFault $e) {
echo $e->getMessage();
echo "\n\nRequest: " . $tran->__getLastRequest();
echo "\n\nResponse: " . $tran->__getLastResponse();
}
?>
Dim uploadrefnum As String
uploadrefnum = "1169"
Dim res As Boolean
res = client.runBatchUpload(token, uploadrefnum)
MsgBox(res)
string uploadrefnum = "1137";
Boolean res;
try
{
res = client.runBatchUpload(token, uploadrefnum);
MessageBox.Show(string.Concat(res));
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
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:runBatchUpload>
<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">fc4f9fa4f9681fde58ec6c1d92a3d221c9ffa9d3</HashValue>
<Seed xsi:type="xsd:string">1333739462-test</Seed>
<Type xsi:type="xsd:string">sha1</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
</Token>
<UploadRefNum xsi:type="xsd:string">52</UploadRefNum>
</ns1:runBatchUpload>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example Response
<?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
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:runBatchUploadResponse>
<runBatchUploadReturn xsi:type="xsd:boolean">true</runBatchUploadReturn>
</ns1:runBatchUploadResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
This method will resume uploading a batch that has been paused and send it to the gateway for processing.
For more information about uploading batches to the gateway for processing, please refer to documentation of the (#createbatchupload) method.
Related Methods
Syntax
boolean runBatchUpload ( ueSecurityToken Token, string UploadRefNum )
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| UploadRefNum | string | Upload reference number (assigned by the gateway). |
Response Parameters
| Name | Type | Description |
|---|---|---|
| runBatchUploadReturn | boolean | Returns confirmation of request only if request is successful. If request fails, an exception will be thrown. |
Change Log
| Version | Description |
|---|---|
| 1.7 | Changed UploadRefNum to type string |
| 1.2 | Renamed BatchNum parameter to UploadRefNum |
| 1.1 | Soap 1.1 Release |
Transaction Detail
getTransaction
Example Request
<?php
try {
$RefNum="1nfmkr4rsmtxhm5";
$res=$client->getTransaction($token, $RefNum);
print_r($res);
}
catch (SoapFault $e){
die("getTransaction failed :" .$e->getMessage());
}
?>
try {
//Set RefNum to the Reference Number of transaction you
//want to retrieve.
BigInteger RefNum = new BigInteger();
TransactionObject Tran = new TransactionObject();
Tran = client.getTransaction(token, refnum);
System.out.println(Tran.getResponse);
} catch (Exception e) {
System.out.println("Soap Exception: " + e.getMessage());
}
Dim client As usaepay.usaepayService = New usaepay.usaepayService
Dim token As usaepay.ueSecurityToken
token = Me.CreateToken("714SSUxv1uohng2XkMJ7kLpETsu58G66", "1234")
Dim refnum As Integer
refnum = 46993430
Dim response As usaepay.TransactionObject
response = client.getTransaction(token, refnum)
MsgBox("Transaction Type: " & response.TransactionType)
string refnum;
refnum = "46973526";
usaepay.TransactionObject tran = new usaepay.TransactionObject();
try
{
tran = client.getTransaction(token, refnum);
MessageBox.Show(string.Concat("Transaction RefNum: ",
tran.Response.RefNum));
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="urn:usaepay"
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:getTransaction>
<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">c1d4b65ab1d56024278889d6f88919dc2e1b1967</HashValue>
<Seed xsi:type="xsd:string">1255252487-test</Seed>
<Type xsi:type="xsd:string">sha1</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
</Token>
<RefNum xsi:type="xsd:string">102230299</RefNum>
</ns1:getTransaction>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example Response
<?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="urn:usaepay"
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:getTransactionResponse>
<getTransactionReturn xsi:type="ns1:TransactionObject">
<AccountHolder xsi:type="xsd:string">Tester Jones</AccountHolder>
<BillingAddress xsi:type="ns1:Address">
<City xsi:type="xsd:string"></City>
<Company xsi:type="xsd:string"></Company>
<Country xsi:type="xsd:string"></Country>
<Email xsi:type="xsd:string"></Email>
<Fax xsi:type="xsd:string"></Fax>
<FirstName xsi:type="xsd:string"></FirstName>
<LastName xsi:type="xsd:string"></LastName>
<Phone xsi:type="xsd:string"></Phone>
<State xsi:type="xsd:string"></State>
<Street xsi:type="xsd:string"></Street>
<Street2 xsi:type="xsd:string"></Street2>
<Zip xsi:type="xsd:string"></Zip>
</BillingAddress>
<CheckData xsi:type="ns1:CheckData">
<Account xsi:nil="true" />
<Routing xsi:nil="true" />
</CheckData>
<CheckTrace xsi:type="ns1:CheckTrace" />
<ClientIP xsi:type="xsd:string"></ClientIP>
<CreditCardData xsi:type="ns1:CreditCardData">
<AvsStreet xsi:type="xsd:string">1234 Main Street</AvsStreet>
<AvsZip xsi:type="xsd:string">99281</AvsZip>
<CardCode xsi:type="xsd:string">XXX</CardCode>
<CardExpiration xsi:type="xsd:string">XXXX</CardExpiration>
<CardNumber xsi:type="xsd:string">XXXXXXXXXXXX7779</CardNumber>
<CardPresent xsi:type="xsd:boolean">false</CardPresent>
<CardType xsi:type="xsd:string">V</CardType>
<InternalCardAuth xsi:type="xsd:boolean">false</InternalCardAuth>
<MagStripe xsi:type="xsd:string"></MagStripe>
<MagSupport xsi:type="xsd:string"></MagSupport>
<Pares xsi:type="xsd:string"></Pares>
<TermType xsi:type="xsd:string"></TermType>
</CreditCardData>
<CustomerID xsi:type="xsd:string"></CustomerID>
<CustomFields SOAP-ENC:arrayType="ns1:FieldValue[0]" xsi:type="ns1:FieldValueArray" />
<DateTime xsi:type="xsd:string">2015-11-19 16:20:13</DateTime>
<Details xsi:type="ns1:TransactionDetail">
<Amount xsi:type="xsd:double">4</Amount>
<Clerk xsi:type="xsd:string"></Clerk>
<Currency xsi:type="xsd:string"></Currency>
<Description xsi:type="xsd:string">Example Transaction</Description>
<Comments xsi:type="xsd:string"></Comments>
<Discount xsi:type="xsd:double">0</Discount>
<Invoice xsi:type="xsd:string">520009908</Invoice>
<NonTax xsi:type="xsd:boolean">false</NonTax>
<OrderID xsi:type="xsd:string"></OrderID>
<PONum xsi:type="xsd:string"></PONum>
<Shipping xsi:type="xsd:double">0</Shipping>
<Subtotal xsi:type="xsd:double">0</Subtotal>
<Table xsi:type="xsd:string"></Table>
<Tax xsi:type="xsd:double">0</Tax>
<Terminal xsi:type="xsd:string"></Terminal>
<Tip xsi:type="xsd:double">0</Tip>
</Details>
<LineItems SOAP-ENC:arrayType="ns1:LineItem[0]" xsi:type="ns1:LineItemArray" />
<Response xsi:type="ns1:TransactionResponse">
<AcsUrl xsi:nil="true" />
<AuthAmount xsi:type="xsd:double">4</AuthAmount>
<AuthCode xsi:type="xsd:string">071044</AuthCode>
<AvsResult xsi:type="xsd:string">Address: Match & 5 Digit Zip: Match</AvsResult>
<AvsResultCode xsi:type="xsd:string">YYY</AvsResultCode>
<BatchNum xsi:type="xsd:string">1911</BatchNum>
<BatchRefNum xsi:type="xsd:string">198442</BatchRefNum>
<CardCodeResult xsi:type="xsd:string">Match</CardCodeResult>
<CardCodeResultCode xsi:type="xsd:string">M</CardCodeResultCode>
<CardLevelResult xsi:nil="true" />
<CardLevelResultCode xsi:nil="true" />
<ConversionRate xsi:type="xsd:double">0</ConversionRate>
<ConvertedAmount xsi:type="xsd:double">0</ConvertedAmount>
<ConvertedAmountCurrency xsi:type="xsd:string"></ConvertedAmountCurrency>
<CustNum xsi:type="xsd:string">0</CustNum>
<Error xsi:type="xsd:string">Approved</Error>
<ErrorCode xsi:type="xsd:integer">0</ErrorCode>
<isDuplicate xsi:type="xsd:boolean">false</isDuplicate>
<Payload xsi:nil="true" />
<RefNum xsi:type="xsd:string">102230299</RefNum>
<Result xsi:type="xsd:string">Approved</Result>
<ResultCode xsi:type="xsd:string">A</ResultCode>
<Status xsi:type="xsd:string">Pending</Status>
<StatusCode xsi:type="xsd:string">P</StatusCode>
<VpasResultCode xsi:nil="true" />
</Response>
<ServerIP xsi:type="xsd:string">209.37.25.121</ServerIP>
<ShippingAddress xsi:type="ns1:Address">
<City xsi:type="xsd:string"></City>
<Company xsi:type="xsd:string"></Company>
<Country xsi:type="xsd:string"></Country>
<Email xsi:type="xsd:string"></Email>
<Fax xsi:type="xsd:string"></Fax>
<FirstName xsi:type="xsd:string"></FirstName>
<LastName xsi:type="xsd:string"></LastName>
<Phone xsi:type="xsd:string"></Phone>
<State xsi:type="xsd:string"></State>
<Street xsi:type="xsd:string"></Street>
<Street2 xsi:type="xsd:string"></Street2>
<Zip xsi:type="xsd:string"></Zip>
</ShippingAddress>
<Source xsi:type="xsd:string">XML Trace Key</Source>
<Status xsi:type="xsd:string">Authorized (Pending Settlement)</Status>
<TransactionType xsi:type="xsd:string">Sale</TransactionType>
<User xsi:type="xsd:string">auto</User>
</getTransactionReturn>
</ns1:getTransactionResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Retrieves all details of a specified transaction. Use this method to view all of the details relating to a particular transaction including transaction status, type, and gateway response.
To specify the transaction you would like to view, you must retrieve it using the reference number (RefNum) assigned to the transaction by the gateway. The RefNum is assigned by the gateway and returned when a transaction is processed. To find a missing RefNum, use the searchTransactions method.
Related Methods
- getTransactionStatus
- getTransactionCustom
- searchTransactions
- searchTransactionsCustom
- getTransactionReport
Syntax
TransactionObject getTransaction ( ueSecurityToken Token, string RefNum)
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| RefNum | string | Unique transaction reference number assigned by the gateway. You can also use TransKey in the RefNum field. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| %TransactionResponse% | object | Returns a TransactionResponse object containing the results of the transaction and all relevant data. |
Change Log
| Version | Change |
|---|---|
| 1.7 | TransKey can be used in RefNum field. |
getTransactionStatus
Example Request
<?php
try {
$refnum='1005312';
print_r($client->getTransactionStatus($token,$refnum));
}
catch(SoapFault $e) {
echo $e->getMessage();
}
echo "\n\nRequest: " . $tran->__getLastRequest();
echo "\n\nResponse: " . $tran->__getLastResponse();
?>
try {
//Set RefNum to the Reference Number of transaction you
//want to retrieve.
BigInteger refnum = new BigInteger();
TransactionResponse response = new TransactionResponse();
response = client.getTransactionStatus(token, refnum);
System.out.println(response.getStatus());
} catch (Exception e) {
System.out.println("Soap Exception: " + e.getMessage());
}
Dim client As usaepay.usaepayService = New usaepay.usaepayService
Dim token As usaepay.ueSecurityToken
token = Me.CreateToken("982lz9VsLm87MA54Sv8E582h8OZMArL6", "443311")
Dim transaction As usaepay.TransactionRequestObject = New usaepay.TransactionRequestObject
Dim refnum As Integer
refnum = "46405618"
Dim response As usaepay.TransactionResponse = New usaepay.TransactionResponse
response = client.getTransactionStatus(token, refnum)
If response.StatusCode = "P" Then
MsgBox("Status: Pending")
ElseIf response.StatusCode = "B" Then
MsgBox("Status: Submitted")
ElseIf response.StatusCode = "E" Then
MsgBox("Status: Error, Reason: " & response.Error)
ElseIf response.StatusCode = "N" Then
MsgBox("Status: New Transaction")
ElseIf response.StatusCode = "F" Then
MsgBox("Status: Funded")
ElseIf response.StatusCode = "S" Then
MsgBox("Status: Settled")
ElseIf response.StatusCode = "V" Then
MsgBox("Status: Voided")
ElseIf response.StatusCode = "T" Then
MsgBox("Status: Timed Out (no response in 5 days)")
ElseIf response.StatusCode = "R" Then
MsgBox("Status: Returned")
ElseIf response.StatusCode = "M" Then
MsgBox("Status: On Hold")
End If
string refnum;
refnum = "46973526";
usaepay.TransactionResponse response = new usaepay.TransactionResponse();
try
{
response = client.getTransactionStatus(token, refnum);
if (response.StatusCode == "V") { MessageBox.Show(string.Concat("Status: Voided")); }
if (response.StatusCode == "B") {MessageBox.Show(string.Concat("Status: Submitted"));}
if (response.StatusCode == "E") {MessageBox.Show(string.Concat("Status: Error, Reason: " + response.Error));}
if (response.StatusCode == "N") {MessageBox.Show(string.Concat("Status: New transaction"));}
if (response.StatusCode == "F") {MessageBox.Show(string.Concat("Status: Funded"));}
if (response.StatusCode == "S") {MessageBox.Show(string.Concat("Status: Settled"));}
if (response.StatusCode == "P") {MessageBox.Show(string.Concat("Status: Pending"));}
if (response.StatusCode == "T") {MessageBox.Show(string.Concat("Status: Timed Out (no response in 5 days)"));}
if (response.StatusCode == "R") {MessageBox.Show(string.Concat("Status: Returned"));}
if (response.StatusCode == "M") { MessageBox.Show(string.Concat("Status: On hold")); }
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
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:getTransactionStatus>
<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">f000ea7855ed35226b1d1cb2b96a288d1069ddec</HashValue>
<Seed xsi:type="xsd:string">11587574150-test</Seed>
<Type xsi:type="xsd:string">sha1</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
</Token>
<RefNum xsi:type="xsd:string">102229960</RefNum>
</ns1:getTransactionStatus>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example Response
<?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="urn:usaepay"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body>
<ns1:getTransactionStatusResponse>
<getTransactionStatusReturn xsi:type="ns1:TransactionResponse">
<AcsUrl xsi:nil="true" />
<AuthAmount xsi:type="xsd:double">4</AuthAmount>
<AuthCode xsi:type="xsd:string">070963</AuthCode>
<AvsResult xsi:type="xsd:string">Address: Match & 5 Digit Zip: Match</AvsResult>
<AvsResultCode xsi:type="xsd:string">YYY</AvsResultCode>
<BatchNum xsi:type="xsd:string">1911</BatchNum>
<BatchRefNum xsi:type="xsd:string">198442</BatchRefNum>
<CardCodeResult xsi:type="xsd:string">Match</CardCodeResult>
<CardCodeResultCode xsi:type="xsd:string">M</CardCodeResultCode>
<CardLevelResult xsi:nil="true" />
<CardLevelResultCode xsi:nil="true" />
<ConversionRate xsi:type="xsd:double">0</ConversionRate>
<ConvertedAmount xsi:type="xsd:double">0</ConvertedAmount>
<ConvertedAmountCurrency xsi:type="xsd:string"></ConvertedAmountCurrency>
<CustNum xsi:type="xsd:string">0</CustNum>
<Error xsi:type="xsd:string">Approved</Error>
<ErrorCode xsi:type="xsd:integer">0</ErrorCode>
<isDuplicate xsi:type="xsd:boolean">false</isDuplicate>
<Payload xsi:nil="true" />
<RefNum xsi:type="xsd:string">102229960</RefNum>
<Result xsi:type="xsd:string">Approved</Result>
<ResultCode xsi:type="xsd:string">A</ResultCode>
<Status xsi:type="xsd:string">Pending</Status>
<StatusCode xsi:type="xsd:string">P</StatusCode>
<VpasResultCode xsi:nil="true" />
</getTransactionStatusReturn>
</ns1:getTransactionStatusResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Retrieve the current status of a specific transaction. This method allows you to check the status of a completed transaction.
Use this method to determine if a transaction has been authorized, processed, or settled.
To specify the transaction you would like to view, you must retrieve it using the reference number (RefNum) assigned to the transaction by the gateway. The RefNum is assigned by the gateway and returned when a transaction is processed. To find a missing RefNum, use the getTransactionStatus method.
Related Methods
Syntax
TransactionResponse getTransactionStatus( ueSecurityToken Token, string RefNum )
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| RefNum | string | Unique transaction reference number assigned by the gateway. You can also use TransKey in the RefNum field. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| %TransactionResponse% | object | Returns a TransactionResponse object containing the results of the transaction and all relevant data. |
Change Log
| Version | Description |
|---|---|
| 1.7 | TransKey can be used in RefNum field. |
getTransactionCustom
Example Request
<?php
try {
$RefNum=1009411;
$Fields = array(
'Details.Amount',
'AccountHolder',
'CheckTrace.TrackingNum'
);
$res=$client->getTransactionCustom($token, $RefNum, $Fields);
print_r($res);
}
catch (SoapFault $e) {
echo $client->__getLastResponse();
die("Get Transaction failed :" .$e->getMessage());
}
?>
try {
//Set RefNum to the Reference Number of transaction you
//want to retrieve fields from.
BigInteger RefNum = new BigInteger();
StringArray fields = new StringArray();
fields.add(new String("Details.Amount"));
FieldValueArray Response;
Response = client.getTransactionCustom(token, refnum, fields);
} catch (Exception e) {
System.out.println("Soap Exception: " + e.getMessage());
}
Dim refnum As String
refnum = 46976537
Dim fields(0 To 2) As String
fields(0) = "Details.Amount"
fields(1) = "AccountHolder"
fields(2) = "CreditCardData.AvsStreet"
Dim tran(0 To 2) As usaepay.FieldValue
For i As Integer = 0 To 2
tran(i) = New usaepay.FieldValue()
Next i
tran = client.getTransactionCustom(token, refnum, fields)
MsgBox(tran(0).Value & " " & tran(1).Value & " " & tran(2).Value)
string refnum;
string[] fields = new string[3];
fields[0] = "Details.Amount";
fields[1] = "AccountHolder";
fields[2] = "CreditCardData.AvsStreet";
refnum = "46976537";
usaepay.FieldValue[] tran = new usaepay.FieldValue[3];
for (int i = 0; i < 3; i++)
{
tran[i] = new usaepay.FieldValue();
}
try
{
tran = client.getTransactionCustom(token, refnum,fields);
MessageBox.Show(string.Concat("Transaction Approved, RefNum: ",
tran[0].Field," = ",tran[0].Value, " ",
tran[0].Field," = ",tran[1].Value, " ",
tran[0].Field," = ",tran[2].Value));
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="urn:usaepay"
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:getTransactionCustom>
<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">21013136958b134b14ddd66a3be80049e70625ea</HashValue>
<Seed xsi:type="xsd:string">1967295471-test</Seed>
<Type xsi:type="xsd:string">sha1</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
</Token>
<RefNum xsi:type="xsd:string">102284059</RefNum>
<Fields SOAP-ENC:arrayType="xsd:string[5]" xsi:type="ns1:stringArray">
<item xsi:type="xsd:string">Response.AvsResult</item>
<item xsi:type="xsd:string">Response.BatchNum</item>
<item xsi:type="xsd:string">Response.RefNum</item>
<item xsi:type="xsd:string">Response.Status</item>
<item xsi:type="xsd:string">Details.Amount</item>
</Fields>
</ns1:getTransactionCustom>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example Response
<?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="urn:usaepay"
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body>
<ns1:getTransactionCustomResponse>
<getTransactionCustomReturn SOAP-ENC:arrayType="ns1:FieldValue[5]" xsi:type="ns1:FieldValueArray">
<item xsi:type="ns1:FieldValue">
<Field xsi:type="xsd:string">Response.AvsResult</Field>
<Value xsi:type="xsd:string">Address: Match & 5 Digit Zip: Match</Value>
</item>
<item xsi:type="ns1:FieldValue">
<Field xsi:type="xsd:string">Response.BatchNum</Field>
<Value xsi:type="xsd:string">1911</Value>
</item>
<item xsi:type="ns1:FieldValue">
<Field xsi:type="xsd:string">Response.RefNum</Field>
<Value xsi:type="xsd:string">102284059</Value>
</item>
<item xsi:type="ns1:FieldValue">
<Field xsi:type="xsd:string">Response.Status</Field>
<Value xsi:type="xsd:string">Pending</Value>
</item>
<item xsi:type="ns1:FieldValue">
<Field xsi:type="xsd:string">Details.Amount</Field>
<Value xsi:type="xsd:string">4.00</Value>
</item>
</getTransactionCustomReturn>
</ns1:getTransactionCustomResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Retrieves only selected details of a specified transaction. If only a small subset of the transaction data is needed, use this method instead of the broader getTransaction retrieval method. This method returns only the data requested in the Fields parameters and is therefore more efficient than the getTransaction method.
To specify the transaction you would like to view, you must retrieve it using the reference number (RefNum) assigned to the transaction by the gateway. The RefNum is assigned by the gateway and returned when a transaction is processed. To find a missing RefNum, use the searchTransactions method.
Specify which transaction fields you would like to retrieve data from by entering one or more of the following:
| DateTime | CreditCardData.CardType | BillingAddress.FirstName | Response.AuthCode |
| AccountHolder | CreditCardData.CardNumber | BillingAddress.LastName | Response.AvsResult |
| User | CreditCardData.CardExpiration | BillingAddress.Company | Response.AvsResultCode |
| Source | CreditCardData.CardCode | BillingAddress.Street | Response.BatchNum |
| ServerIP | CreditCardData.AvsStreet | BillingAddress.Street2 | Response.CardCodeResult |
| ClientIP | CreditCardData.AvsZip | BillingAddress.City | Response.CardCodeResultCode |
| CustomerID | CreditCardData.CardPresent | BillingAddress.State | Response.ConversionRate |
| Details.Invoice | CheckData.CheckNumber | BillingAddress.Zip | Response.ConvertedAmount |
| Details.PoNum | CheckData.Routing | BillingAddress.Country | Response.ConvertedAmountCurrency |
| Details.OrderID | CheckData.Account | BillingAddress.Phone | Response.Error |
| Details.Clerk | CheckData.SSN | BillingAddress.Fax | Response.ErrorCode |
| Details.Terminal | CheckData.DriversLicense | BillingAddress.Email | Response.RefNum |
| Details.Table | CheckData.DriversLicenseState | ShippingAddress.FirstName | Response.Result |
| Details.Description | CheckData.RecordType | ShippingAddress.LastName | Response.ResultCode |
| Details.Amount | CheckTrace.TrackingNum | ShippingAddress.Company | Response.Status |
| Details.Currency | CheckTrace.Effective | ShippingAddress.Street | Response.StatusCode |
| Details.Tax | CheckTrace.Processed | ShippingAddress.Street2 | |
| Details.Tip | CheckTrace.Settled | ShippingAddress.City | |
| Details.NonTax | CheckTrace.Returned | ShippingAddress.State | |
| Details.Shipping | CheckTrace.BankNote | ShippingAddress.Zip | |
| Details.Discount | ShippingAddress.Country | ||
| Details.Subtotal | ShippingAddress.Fax | ||
| ShippingAddress.Email |
Related Methods
- getTransactionStatus
- getTransaction
- searchTransactions
- searchTransactionsCustom
- getTransactionReport
Syntax
FieldValue getTransactionCustom ( ueSecurityToken Token, string RefNum, string Fields)
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| RefNum | string | Unique transaction reference number assigned by the gateway. You can also use TransKey in the RefNum field. |
| Fields | array | An array listing the fields to be retrieved. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| %FieldValue% | array | Returns requested data from specified transaction. Possible values include transaction status, gateway response, date and time of transaction, credit card specific data, transaction amount, cardholder name and address, and any other transaction details entered in the request. |
Change Log
| Version | Description |
|---|---|
| 1.7 | TransKey can be used in RefNum field. |
getCheckTrace
Example Request
<?php
try {
$RefNum=1119999999;
$res = $client->getCheckTrace($token, $RefNum);
print_r($res);
}
catch(SoapFault $e) {
echo $e->getMessage();
}
?>
Dim client As usaepay.usaepayService = New usaepay.usaepayService
Dim token As usaepay.ueSecurityToken
token = Me.CreateToken("714SSUxv1uohng2XkMJ7kLpETsu58G66", "1234")
Dim refnum As Integer
refnum = 46999316
Dim trace As usaepay.CheckTrace = New usaepay.CheckTrace
trace = client.getCheckTrace(token, refnum)
MsgBox("Tracking Number: " & trace.TrackingNum)
string refnum;
refnum = "46973419";
usaepay.CheckTrace trace = new usaepay.CheckTrace();
try
{
trace = client.getCheckTrace(token,refnum);
MessageBox.Show(string.Concat(trace.TrackingNum));
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
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:getCheckTrace>
<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">c194ee3e3c2ee652a8a197cd86a8a7ec5279f2fd</HashValue>
<Seed xsi:type="xsd:string">1845463236-test</Seed>
<Type xsi:type="xsd:string">sha1</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
</Token>
<RefNum xsi:type="xsd:string">102284362</RefNum>
</ns1:getCheckTrace>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example Response
<?xml version="1.0" encoding="utf-8"?><SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
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:getCheckTraceResponse>
<getCheckTraceReturn xsi:type="ns1:CheckTrace">
<Status xsi:type="xsd:string">Pending</Status>
<StatusCode xsi:type="xsd:string">P</StatusCode>
<Effective xsi:type="xsd:string">2015-11-24</Effective>
<TrackingNum xsi:type="xsd:string">15112348321864</TrackingNum>
</getCheckTraceReturn>
</ns1:getCheckTraceResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Retrieve the current status and tracking data for a specific electronic check transaction. This method allows you to check the status and tracking data on an electronic check transaction.
Use this method to determine what state a check transaction is in.
To specify the transaction you would like to view, you must retrieve it using the reference number (RefNum) assigned to the transaction by the gateway. The RefNum is assigned by the gateway and returned when a transaction is processed. To find a missing RefNum, use the searchTransactions method.
Related Methods
Syntax
CheckTrace CheckTrace ( ueSecurityToken Token, string RefNum )
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| RefNum | string | Unique transaction reference number assigned by the gateway. You can also use TransKey in the RefNum field. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| %CheckTrace% | object | Returns a CheckTrace object containing the check specific status and tracking information |
Exceptions
| Code | Message | Advice |
|---|---|---|
| 20001 | Specified transactions was not found. | RefNum provided was not found by the system. Make sure the RefNum was not truncated and belongs to this merchant (identified by Token) on this server (Sandbox RefNum cannot be looked up in production and vice versa). |
| 40201 | Incorrect transaction type | getCheckTrace will only work for electronic check transactions. This exception will be thrown if RefNum refers to a credit card transaction |
Transaction Search
searchTransactions
Example Request
<?php
//php5
try {
// Create search parameter list
$search=array(
array(
'Field'=>'amount',
'Type'=>'eq',
'Value'=>'4.00'),
array(
'Field'=>'created',
'Type'=>'gt',
'Value'=>'2007-03-21'),
array(
'Field'=>'created',
'Type'=>'lt',
'Value'=>'2007-03-22'),
array(
'Field'=>'response',
'Type'=>'eq',
'Value'=>'A')
);
$start=0;
$limit=100;
$matchall=true;
$sort='created';
$res=$client->searchTransactions($token,$search,$matchall,$start,$limit,$sort);
print_r($res);
}
catch(SoapFault $e) {
echo $client->__getLastResponse();
die("Search Transaction Failed :".$e->getMessage());
}
?>
<?php
//php4
include './nusoap.php';
// Create Soap Client
$s=new soapclient("./usaepay.wsdl",'wsdl');
$tran=$s->getProxy();
// Source Key Setting
$sourcekey='yQbOFkjD8wwlkZ3AhY248k3Lc9PH1l14';
$pin='1234';
// Prep source key
$seed=mktime() . rand();
$tmp=$sourcekey . $seed . $pin;
$hash=sha1($tmp);
$token=array('SourceKey'=>$sourcekey, 'PinHash'=>array('Type'=>'sha1', 'Seed'=>$seed,'HashValue'=>$hash));
// Prep Request data
$search=array(
array('Field'=>'amount', 'Type'=>'gt','Value'=>'5.00'),
array('Field'=>'created', 'Type'=>'gt', 'Value'=>'2005-01-01'),
array('Field'=>'response', 'Type'=>'eq', 'Value'=>'A')
);
$start=0;
$limit=10;
$matchall=true;
$sort='created';
$res=$tran->searchTransactions($token,$search,$matchall,$start,$limit,$sort);
if(!$err=$tran->getError()) {
print_r($res);
} else {
echo "Error: $err\n";
echo $tran->request;
}
?>
Dim client As usaepay.usaepayService = New usaepay.usaepayService
Dim token As usaepay.ueSecurityToken
token = Me.CreateToken("714SSUxv1uohng2XkMJ7kLpETsu58G66", "1234")
Dim MatchAll As Boolean
MatchAll = False
Dim searchParams(1) As usaepay.SearchParam
searchParams(0) = New usaepay.SearchParam
searchParams(0).Field = "Created"
searchParams(0).Type = "eq"
searchParams(0).Value = "2009-02-19"
Dim start As Integer
start = 1
Dim limit As Integer
limit = "999999"
Dim SearchResults As usaepay.TransactionSearchResult = New usaepay.TransactionSearchResult
SearchResults = client.searchTransactions(token, searchParams, MatchAll, 0, 1000, "")
MsgBox(SearchResults.TransactionsMatched)
Boolean matchAll;
matchAll = true;
String startTransID = "1234";
usaepay.SearchParam[] search = new usaepay.SearchParam[2];
search[0] = new usaepay.SearchParam();
search[1] = new usaepay.SearchParam();
search[0].Field = "Response";
search[0].Type = "eq";
search[0].Value = "A";
search[1].Field = "TransID";
search[1].Type = "gt";
search[1].Value = startTransID;
usaepay.TransactionSearchResult result = new usaepay.TransactionSearchResult();
int pos = 0;
int limit = 10; // size of result set
int totalFound =0;
try
{
// loop through result sets
do
{
result = client.searchTransactions(token, search, matchAll,
pos.ToString(), limit.ToString(), "TransID");
// Perform operations on returned data
MessageBox.Show(string.Concat("Retrieved ", pos, " to ",
pos + Convert.ToInt32(result.TransactionsReturned),
" of ", result.TransactionsMatched));
pos += limit;
if (totalFound == 0) totalFound = Convert.ToInt32(result.TransactionsMatched);
} while (pos< totalFound);
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay" 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:searchTransactions>
<Token xsi:type="ns1:ueSecurityToken">
<ClientIP xsi:type="xsd:string">192.168.0.1</ClientIP>
<PinHash xsi:type="ns1:ueHash">
<HashValue xsi:type="xsd:string">11ac55b0a0b59f8f028dbf85bc32266fa973dd0e</HashValue>
<Seed xsi:type="xsd:string">12678150211876663375</Seed>
<Type xsi:type="xsd:string">sha1</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">HB4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
</Token>
<Search SOAP-ENC:arrayType="ns1:SearchParam[1]" xsi:type="ns1:SearchParamArray">
<item xsi:type="ns1:SearchParam">
<Field xsi:type="xsd:string">amount</Field>
<Type xsi:type="xsd:string">eq</Type>
<Value xsi:type="xsd:string">29.00</Value>
</item>
</Search>
<MatchAll xsi:type="xsd:boolean">true</MatchAll>
<Start xsi:type="xsd:integer">0</Start>
<Limit xsi:type="xsd:integer">10</Limit>
<Sort xsi:type="xsd:string">created</Sort>
</ns1:searchTransactions>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
This method allows you to find transactions even if you have misplaced or can't remember the transaction's RefNum (a unique number assigned to each transaction by the gateway).
Please Note: When merchant is configured for merchant scoped Transactions IDs, system scoped transactions will not be returned by the searchTransactions method.
The following fields may be used to search the database and return transaction details:
| TransID | Created | Billing_FName |
| BatchID | CreateTime | Billing_LName |
| Type | Invoice | Billing_Company |
| Status | OrderID | Billing_Street |
| Response | PoNum | Billing_Street2 |
| AuthCode | CustID | Billing_City |
| AvsResult | RecCustID | Billing_State |
| CvcResult | Description | Billing_Country |
| Reason | Amount | Billing_Phone |
| ErrorCode | Currency | Shipping_FName |
| Cardholder | RawAmount | Shipping_LName |
| CCNum | Tax | Shipping_Company |
| CCNum4First | Tip | Shipping_Street |
| AvsStreet | Shipping | Shipping_Street2 |
| AvsZip | Discount | Shipping_City |
| CheckNum | Subtotal | Shipping_State |
| VCAccount | User | Shipping_Zip |
| VCRouting | Clerk | Shipping_Country |
| VCChecks.Settled | TranTerm | Shipping_Phone |
| VCChecks.Processed | Rest_Table | |
| Returned | Sources.Name | |
| VCChecks.Banknote | ServerIP | |
| ClientIP |
Related Methods
Syntax
TransactionSearchResult searchTransactions ( ueSecurityToken Token, SearchParam Search, boolean MatchAll, integer Start, integer Limit, string Sort )
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| %SearchParam% | array | Array of search parameters. |
| MatchAll | boolean | If set to "true," only results matching all search criteria will be returned, if set to "false," results matching any of the search criteria will be returned. |
| Start | integer | Record number to start returning from (ie if 1,000 were found and you only want to receive the last 200 you would set Start=800 and Limit=200) |
| Limit | integer | Maximum number of transactions to return in result set. Largest limit allowed is 1000. |
| Sort | string | Comma separated list of fields to sort by. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| %TransactionSearchResult% | array | Returns the full transaction records for all transactions matching the specified search parameters. |
Change Log
| Version | Description |
|---|---|
| 1.4 - 1.7 | Added the ability to search by a cards payment method |
| 1.4 - 1.7 | Corrected Parameter name from VCChecks.Returned to Returned. |
searchTransactionsCount
Example Request
//php5
<?php
try {
// Create search parameter list
$search=array(
array(
'Field'=>'amount',
'Type'=>'eq',
'Value'=>'4.00'),
array(
'Field'=>'created',
'Type'=>'gt',
'Value'=>'2007-03-21'),
array(
'Field'=>'created',
'Type'=>'lt',
'Value'=>'2007-03-22'),
array(
'Field'=>'response',
'Type'=>'eq',
'Value'=>'A')
);
$start=0;
$limit=100;
$matchall=true;
$sort='created';
$res=$client->searchTransactionsCount($token,$search,$matchall,$start,$limit,$sort);
print_r($res);
}
catch(SoapFault $e) {
echo $client->__getLastResponse();
die("Search Transaction Failed :".$e->getMessage());
}
?>
//php4
<?php
include './nusoap.php';
// Create Soap Client
$s=new soapclient("./usaepay.wsdl",'wsdl');
$tran=$s->getProxy();
// Source Key Setting
$sourcekey='yQbOFkjD8wwlkZ3AhY248k3Lc9PH1l14';
$pin='1234';
// Prep source key
$seed=mktime() . rand();
$tmp=$sourcekey . $seed . $pin;
$hash=sha1($tmp);
$token=array('SourceKey'=>$sourcekey, 'PinHash'=>array('Type'=>'sha1', 'Seed'=>$seed,'HashValue'=>$hash));
// Prep Request data
$search=array(
array('Field'=>'amount', 'Type'=>'gt','Value'=>'5.00'),
array('Field'=>'created', 'Type'=>'gt', 'Value'=>'2005-01-01'),
array('Field'=>'response', 'Type'=>'eq', 'Value'=>'A')
);
$start=0;
$limit=10;
$matchall=true;
$sort='created';
$res=$tran->searchTransactionsCount($token,$search,$matchall,$start,$limit,$sort);
if(!$err=$tran->getError()) {
print_r($res);
} else {
echo "Error: $err\n";
echo $tran->request;
}
?>
Dim client As usaepay.usaepayService = New usaepay.usaepayService
Dim token As usaepay.ueSecurityToken
token = Me.CreateToken("982lz9VsLm87MA54Sv8E582h8OZMArL6", "443311")
Dim MatchAll As Boolean
MatchAll = False
Dim searchParams(1) As usaepay.SearchParam
searchParams(0) = New usaepay.SearchParam
searchParams(0).Field = "Created"
searchParams(0).Type = "eq"
searchParams(0).Value = "2009-02-19"
Dim SearchResults As usaepay.TransactionSearchResult = New usaepay.TransactionSearchResult
SearchResults = client.searchTransactionsCount(token, searchParams, MatchAll, 0, 1000, "created")
MsgBox(SearchResults.TransactionsMatched)
Boolean matchAll;
matchAll = true;
string[] fields = new string[3];
usaepay.SearchParam[] search = new usaepay.SearchParam[2];
search[0] = new usaepay.SearchParam();
search[0].Field = "Created";
search[0].Type = "gt";
search[0].Value = "2010-08-08";
usaepay.TransactionSearchResult result = new usaepay.TransactionSearchResult();
try
{
result = client.searchTransactionsCount(token, search, matchAll, "0", "10", "created");
MessageBox.Show(string.Concat(result.TransactionsMatched));
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay" 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:searchTransactionsCount>
<Token xsi:type="ns1:ueSecurityToken">
<ClientIP xsi:type="xsd:string">192.168.0.1</ClientIP>
<PinHash xsi:type="ns1:ueHash">
<HashValue xsi:type="xsd:string">11ac55b0a0b59f8f028dbf85bc32266fa973dd0e</HashValue>
<Seed xsi:type="xsd:string">12678150211876663375</Seed>
<Type xsi:type="xsd:string">sha1</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">HB4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
</Token>
<Search SOAP-ENC:arrayType="ns1:SearchParam[1]" xsi:type="ns1:SearchParamArray">
<item xsi:type="ns1:SearchParam">
<Field xsi:type="xsd:string">amount</Field>
<Type xsi:type="xsd:string">eq</Type>
<Value xsi:type="xsd:string">29.00</Value>
</item>
</Search>
<MatchAll xsi:type="xsd:boolean">true</MatchAll>
<Start xsi:type="xsd:integer">0</Start>
<Limit xsi:type="xsd:integer">10</Limit>
<Sort xsi:type="xsd:string">created</Sort>
</ns1:searchTransactionsCount>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Identical to the searchTransactions method except only the transaction counts are returned. Like searchTransactions, this method returns TransactionSearchResult. The only difference is that TransactionSearchResult.Transactions is left empty. This method provides a quicker way to determine the size of the result set before starting to retrieve the full search results.
Related Methods
Syntax
TransactionSearchResult searchTransactionsCount ( SearchParam Search, boolean MatchAll, integer Start, integer Limit, string Sort )
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| %SearchParam% | array | Array of search parameters. |
| MatchAll | boolean | If set to "true," only results matching all search criteria will be returned, if set to "false," results matching any of the search criteria will be returned. |
| Start | integer | Record number to start returning from (ie if 1,000 were found and you only want to receive the last 200 you would set Start=800 and Limit=200) |
| Limit | integer | Maximum number of records to return in result set. |
| Sort | string | Comma separated list of fields to sort by. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| %TransactionSearchResult% | object | Returns the full transaction records for all transactions matching the specified search parameters. |
searchTransactionsCustom
Example Request
<?php
try {
// make sure you prep data to search on
$search=array(
array(
'Field'=>'amount',
'Type'=>'eq',
'Value'=>'3.83'),
array(
'Field'=>'created',
'Type'=>'gt',
'Value'=>'2007-05-09'),
array(
'Field'=>'created',
'Type'=>'lt',
'Value'=>'2007-05-22'),
array(
'Field'=>'response',
'Type'=>'eq',
'Value'=>'A')
);
$start=0;
$limit=100;
$matchall=true;
$fieldList=array(
'Details.Amount',
'AccountHolder',
'CheckTrace.TrackingNum');
$format ='csv';
$sort = 'invoice';
$res=$client->searchTransactionsCustom($token,$search,$matchall,$start,$limit,$fieldList,$format,$sort);
$res=base64_decode($res);
print_r($res);
}
catch(SoapFault $e) {
echo $client->__getLastResponse();
die("Serach Transaction Failed :".$e->getMessage());
}
?>
' instantiate client
Dim client As usaepay.usaepayService = New usaepay.usaepayService
' build security token using sourcekey and pin
Dim token As usaepay.ueSecurityToken
token = Me.CreateToken("982lz9VsLm87MA54Sv8E582h8OZMArL6", "443311")
' Search type is AND (all search parameters must be matched)
Dim MatchAll As Boolean
MatchAll = True
' List of search parameters
Dim searchParams(1) As usaepay.SearchParam
searchParams(0) = New usaepay.SearchParam
searchParams(0).Field = "Created"
searchParams(0).Type = "gt"
searchParams(0).Value = "2009-05-13 00:00:00"
searchParams(1) = New usaepay.SearchParam
searchParams(1).Field = "reccustid"
searchParams(1).Type = "gt"
searchParams(1).Value = "0"
' Result Record to start on
Dim start As Integer
start = 1
' List of fields to return
Dim FieldList(2) As String
FieldList(0) = "Response.RefNum"
FieldList(1) = "Response.ResultCode"
FieldList(2) = "CustomerID"
' limit to 10 results
Dim limit As Integer
limit = "10"
Dim SearchResults As String
SearchResults = client.searchTransactionsCustom(token, searchParams, MatchAll, 0, 1000, FieldList, "csv", "invoice")
' results are base64 encode
Dim binaryData() As Byte
binaryData = Convert.FromBase64String(SearchResults)
MsgBox(Encoding.UTF8.GetString(binaryData))
Boolean matchAll;
matchAll = true;
string[] fields = new string[3];
usaepay.SearchParam[] search = new usaepay.SearchParam[2];
search[0] = new usaepay.SearchParam();
search[0].Field = "Created";
search[0].Type = "Contains";
search[0].Value = "2010-08-09";
int start = 1;
int limit = 10;
string[] FieldList = new string[3];
FieldList[0] = "Response.RefNum";
FieldList[1] = "Response.ResultCode";
FieldList[2] = "CustomerID";
string result;
try
{
result = client.searchTransactionsCustom(token, search, matchAll, "0", "10", FieldList,"csv", "invoice");
Byte[] binaryData = new Byte[3];
binaryData = Convert.FromBase64String(result);
MessageBox.Show(Encoding.UTF8.GetString(binaryData));
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay" 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:searchTransactionsCustom>
<Token xsi:type="ns1:ueSecurityToken">
<ClientIP xsi:type="xsd:string">192.168.0.1</ClientIP>
<PinHash xsi:type="ns1:ueHash">
<HashValue xsi:type="xsd:string">11ac55b0a0b59f8f028dbf85bc32266fa973dd0e</HashValue>
<Seed xsi:type="xsd:string">12678150211876663375</Seed>
<Type xsi:type="xsd:string">sha1</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">HB4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
</Token>
<Search SOAP-ENC:arrayType="ns1:SearchParam[1]" xsi:type="ns1:SearchParamArray">
<item xsi:type="ns1:SearchParam">
<Field xsi:type="xsd:string">amount</Field>
<Type xsi:type="xsd:string">eq</Type>
<Value xsi:type="xsd:string">29.00</Value>
</item>
</Search>
<MatchAll xsi:type="xsd:boolean">true</MatchAll>
<Start xsi:type="xsd:integer">0</Start>
<Limit xsi:type="xsd:integer">10</Limit>
<FieldList SOAP-ENC:arrayType="xsd:string[5]" xsi:type="ns1:stringArray">
<item xsi:type="xsd:string">Response.AvsResult</item>
<item xsi:type="xsd:string">Response.AvsResultCode</item>
<item xsi:type="xsd:string">DateTime</item>
<item xsi:type="xsd:string">Response.Error</item>
<item xsi:type="xsd:string">Details.Invoice</item>
</FieldList>
<Format xsi:type="xsd:string">xml</Format>
<Sort xsi:type="xsd:string">Details.Invoice</Sort>
</ns1:searchTransactionsCustom>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Use this method if you only need to view a few select fields of the transactions you are searching for. Since it will only return the fields you specify, it is more efficient than the searchTransactions method. Search, Sort and Return Fields The following fields may be used in the SearchParam, Sort and FieldList parameters:
| transactiontype | creditcarddata.cardtype | billingaddress.firstname | response.authcode |
| datetime | creditcarddata.cardnumber | billingaddress.lastname | response.avsresult |
| accountholder | creditcarddata.cardexpiration | billingaddress.company | response.avsresultcode |
| details.invoice | creditcarddata.cardcode | billingaddress.street | response.batchnum |
| details.ponum | creditcarddata.avsstreet | billingaddress.street2 | response.batchrefnum |
| details.orderid | creditcarddata.avszip | billingaddress.city | response.cardcoderesult |
| details.clerk | creditcarddata.cardpresent | billingaddress.state | response.cardcoderesultcode |
| details.terminal | checkdata.checknumber | billingaddress.zip | response.conversionrate |
| details.table | checkdata.routing | billingaddress.country | response.convertedamount |
| details.description | checkdata.account | billingaddress.phone | response.convertedamountcurrency |
| details.amount | checkdata.ssn | billingaddress.fax | response.custnum |
| details.currency | checkdata.driverslicense | billingaddress.email | response.error |
| details.tax | checkdata.driverslicensestate | shippingaddress.firstname | response.errorcode |
| details.tip | checkdata.recordtype | shippingaddress.lastname | response.refnum |
| details.nontax | shippingaddress.company | response.result | |
| details.shipping | shippingaddress.street | response.resultcode | |
| details.discount | shippingaddress.street2 | response.status | |
| details.subtotal | shippingaddress.city | response.statuscode | |
| user | shippingaddress.state | checktrace.trackingnum | |
| source | shippingaddress.zip | checktrace.effective | |
| serverip | shippingaddress.country | checktrace.processed | |
| clientip | shippingaddress.phone | checktrace.settled | |
| customerid | shippingaddress.fax | checktrace.returned | |
| shippingaddress.email | checktrace.banknote |
Related Methods
Syntax
string searchTransactionsCustom ( ueSecurityToken Token, SearchParam Search, boolean MatchAll, integer Start, integer Limit, string FieldList, string Format, string Sort )
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| %SearchParam% | array | Array of search parameters. |
| MatchAll | boolean | If set to "true," only results matching all search criteria will be returned, if set to "false," results matching any of the search criteria will be returned. |
| Start | integer | Sequence number to start returning on. |
| Limit | integer | Maximum number of transactions to return in result set. |
| FieldList | list | List of fields to return in search. |
| Format | string | Specify format of return data. Possible formats include: csv, tab, xml. |
| Sort | string | Field name to sort the results by. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| searchTransactionsCustomReturn | string | Base64 encode result set. Returns all of the fields from any transactions matching your search parameters. |
Token Methods
Create Token
saveCard
Example Request
<?php
try {
$CreditCardData => array(
'CardNumber' => '4444555566667779',
'CardExpiration' => '0909',
'CardCode' => '999'
)
);
$token=$client->saveCard($token, $CreditCardData);
}
catch (SoapFault $e) {
die("saveCard failed :" .$e->getMessage());
}
?>
private void btnruntransaction_Click(object sender, EventArgs e)
{
usaepay.usaepayService client = getClient();
usaepay.ueSecurityToken token = getToken();
usaepay.CreditCardData card = new usaepay.CreditCardData();
card.CardNumber = "4444555566667779";
card.CardExpiration = "0914";
usaepay.CreditCardToken cctoken = new usaepay.CreditCardToken();
try
{
cctoken = client.saveCard(token, card);
MessageBox.Show(string.Concat("Card Saved: ",cctoken.CardRef));
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
}
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
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:saveCard>
<Token xsi:type="ns1:ueSecurityToken">
<ClientIP xsi:type="xsd:string">192.168.0.1</ClientIP>
<PinHash xsi:type="ns1:ueHash">
<HashValue xsi:type="xsd:string">da4f177fb82a516da7b93cd725c0ac0fbead2ef4</HashValue>
<Seed xsi:type="xsd:string">13413324111907933573</Seed>
<Type xsi:type="xsd:string">sha1</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">_Ss7g8t6UW9b1Py6474F5Z1A8fmo22x2</SourceKey>
</Token>
<CreditCardData xsi:type="ns1:CreditCardData">
<CardExpiration xsi:type="xsd:string">2013-02</CardExpiration>
<CardNumber xsi:type="xsd:string">4444-5555-6666-7779</CardNumber>
</CreditCardData>
</ns1:saveCard>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Save a card
Syntax
CreditCardToken saveCard ( ueSecurityToken Token, CreditCardData CreditCardData )
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| %CreditCardData% | object | CreditCardData. Required for credit card transactions. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| %CreditCardToken% | object | Returns object containing card token data (including card ref) |
Change Log
| Version | Description |
|---|---|
| 1.6 | Method added in soap-1.6 |
saveCards
Example Request
<?php
try {
$Cards = array();
$Cards[] = array(
'CardNumber' => '4444555566667779',
'CardExpiration' => '1015',
);
$Cards[] = array(
'CardNumber' => '5555444433332226',
'CardExpiration' => '0216',
);
$tokens=$client->saveCards($token, $Cards);
}
catch (SoapFault $e) {
die("saveCards failed :" .$e->getMessage());
}
?>
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay" 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:saveCards>
<Token xsi:type="ns1:ueSecurityToken">
<ClientIP xsi:type="xsd:string">192.168.0.1</ClientIP>
<PinHash xsi:type="ns1:ueHash">
<HashValue xsi:type="xsd:string">30253a800ca37f11c46df86be585b1d882887120</HashValue>
<Seed xsi:type="xsd:string">13656302101510261731</Seed>
<Type xsi:type="xsd:string">sha1</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">_Ss7g8t6UW9b1Py6474F5Z1A8fmo22x2</SourceKey>
</Token>
<CreditCards SOAP-ENC:arrayType="ns1:CreditCardData[3]" xsi:type="ns1:CreditCardDataArray">
<item xsi:type="ns1:CreditCardData">
<AvsStreet xsi:type="xsd:string">298 State st</AvsStreet>
<AvsZip xsi:type="xsd:string">12210</AvsZip>
<CardExpiration xsi:type="xsd:string">0214</CardExpiration>
<CardNumber xsi:type="xsd:string">4444555566667779</CardNumber>
</item>
<item xsi:type="ns1:CreditCardData">
<AvsStreet xsi:type="xsd:string">298 State st</AvsStreet>
<AvsZip xsi:type="xsd:string">12210</AvsZip>
<CardExpiration xsi:type="xsd:string">0216</CardExpiration>
<CardNumber xsi:type="xsd:string">5555444433332226</CardNumber>
</item>
<item xsi:type="ns1:CreditCardData">
<AvsStreet xsi:type="xsd:string">298 State st</AvsStreet>
<AvsZip xsi:type="xsd:string">12210</AvsZip>
<CardExpiration xsi:type="xsd:string">1015</CardExpiration>
<CardNumber xsi:type="xsd:string">371122223332225</CardNumber>
</item>
</CreditCards>
</ns1:saveCards>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example Response
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body>
<ns1:saveCardsResponse>
<saveCardsReturn SOAP-ENC:arrayType="ns1:CreditCardToken[3]" xsi:type="ns1:CreditCardTokenArray">
<item xsi:type="ns1:CreditCardToken">
<CardRef xsi:type="xsd:string">o58j-duhc-57nk-jlc3</CardRef>
<CardExpiration xsi:type="xsd:string">2014-02</CardExpiration>
<CardNumber xsi:type="xsd:string">XXXXXXXXXXXX7779</CardNumber>
<CardType xsi:type="xsd:string">Visa</CardType>
</item>
<item xsi:type="ns1:CreditCardToken">
<CardRef xsi:type="xsd:string">lu8p-ftcm-foxs-ehw7</CardRef>
<CardExpiration xsi:type="xsd:string">2016-02</CardExpiration>
<CardNumber xsi:type="xsd:string">XXXXXXXXXXXX2226</CardNumber>
<CardType xsi:type="xsd:string">Master</CardType>
</item>
<item xsi:type="ns1:CreditCardToken">
<CardRef xsi:type="xsd:string">29lz-vz21-fk5c-93t7</CardRef>
<CardExpiration xsi:type="xsd:string">2015-10</CardExpiration>
<CardNumber xsi:type="xsd:string">XXXXXXXXXXX2225</CardNumber>
<CardType xsi:type="xsd:string">AmEx</CardType>
</item>
</saveCardsReturn>
</ns1:saveCardsResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Save a collection cards
Syntax
CreditCardToken saveCards ( ueSecurityToken Token, CreditCardData CreditCards)
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| %CreditCardData% | array | Array of credit card data objects. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| %CreditCardToken% | array | Returns an array of card token objects |
convertPaymentMethodToToken
Example Request
<?php
try {
// Set CustNum to the customer of payment method attached to the payment method
$CustNum="78129790";
// Set Method ID to the Reference Method ID
$MethodID="2399";
$Result = $client->convertPaymentMethodToToken($token,$CustNum,$MethodID);
}
catch(SoapFault $e) {
echo "SoapFault: " .$e->getMessage(); print_r($e);
echo "\n\nRequest: " . $tran->__getLastRequest();
echo "\n\nResponse: " . $tran->__getLastResponse();
}
?>
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="urn:usaepay" 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:convertPaymentMethodToToken>
<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">56c5a10ea6e3de7c39752aea69978d8f2aa558ddbc250d74e45ea5d3d18e6067</HashValue>
<Seed xsi:type="xsd:string">15390142301755682699sadfpouhasodf8uh</Seed>
<Type xsi:type="xsd:string">sha256</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">chwl7EPgI56G8X76a0ME509Vc2z3BGge</SourceKey>
</Token>
<CustNum xsi:type="xsd:string">78129790</CustNum>
<MethodID xsi:type="xsd:string">2399</MethodID>
</ns1:convertPaymentMethodToToken>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example Response
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="urn:usaepay" 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:convertPaymentMethodToTokenResponse>
<convertPaymentMethodToTokenReturn xsi:type="ns1:CreditCardToken">
<CardRef xsi:type="xsd:string">aqj5-lx82-hbsw-7kb6</CardRef>
<CardExpiration xsi:type="xsd:string">2020-12</CardExpiration>
<CardNumber xsi:type="xsd:string">XXXXXXXXXXXX7779</CardNumber>
<CardType xsi:type="xsd:string">VI</CardType>
</convertPaymentMethodToTokenReturn>
</ns1:convertPaymentMethodToTokenResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Tokenize a customer payment method.
Syntax
(ueSecurityToken Token, string CustNum, string MethodID
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| CustNum | string | System assigned CustNum of stored customer record. |
| MethodID | string | System assigned id of stored customer payment method. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| %CreditCardToken% | object | Returns object containing card token data (including card ref) |
Change Log
| Version | Change |
|---|---|
| 1.7 | Added Method. |
Retrieve Token
getCreditCardToken
Example Request
<?php
try {
$CardRef="ifhvz42iz6kg49qi";
$res=$client->getCreditCardToken($token, $CardRef);
print_r($res);
}
catch (SoapFault $e){
die("getTransaction failed :" .$e->getMessage());
}
?>
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="urn:usaepay" 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:getCreditCardToken>
<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">31a3b09805e0f55e210dc5bf0e978a3456b8d121fdfbbfd30d02a6610ddcb31e</HashValue>
<Seed xsi:type="xsd:string">15390164391550852671sadfpouhasodf8uh</Seed>
<Type xsi:type="xsd:string">sha256</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">chwl7EPgI56G8X76a0ME509Vc2z3BGge</SourceKey>
</Token>
<CardRef xsi:type="xsd:string">ifhvz42iz6kg49qi</CardRef>
</ns1:getCreditCardToken>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example Response
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="urn:usaepay" 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:getCreditCardTokenResponse>
<getCreditCardTokenReturn xsi:type="ns1:CreditCardToken">
<CardRef xsi:type="xsd:string">ifhv-z42i-z6kg-49qi</CardRef>
<CardExpiration xsi:type="xsd:string">2020-09</CardExpiration>
<CardNumber xsi:type="xsd:string">XXXXXXXXXXXX7779</CardNumber>
<CardType xsi:type="xsd:string">Visa</CardType>
</getCreditCardTokenReturn>
</ns1:getCreditCardTokenResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Retrieve card info using token.
Syntax
TransactionObject getTransaction ( ueSecurityToken Token, string CardRef )
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| CardRef | string | Unique token representing card |
Response Parameters
| Name | Type | Description |
|---|---|---|
| %CreditCardToken% | object | Returns object containing card token data (including card ref) |
Change Log
| Version | Description |
|---|---|
| 1.7 | Added Method |
lookupCardToken
Example Request
<?php
try {
$Lookup = "vu8ls884kys7674s";
$token=$client->lookupCardToken($token, $Lookup);
}
catch (SoapFault $e) {
die("lookupCardToken failed :" .$e->getMessage());
}
?>
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="urn:usaepay" 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:lookupCardToken>
<Token xsi:type="ns1:ueSecurityToken">
<ClientIP xsi:type="xsd:string">192.168.0.1</ClientIP>
<PinHash xsi:type="ns1:ueHash">
<HashValue xsi:type="xsd:string">f2f5838082462468fc9ab65cffde0c112c34870d</HashValue>
<Seed xsi:type="xsd:string">13430765681990835866</Seed>
<Type xsi:type="xsd:string">sha1</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">_Ss7g8t6UW9b1Py6474F5Z1A8fmo22x2</SourceKey>
</Token>
<Lookup xsi:type="xsd:string">19217415721343076568.727</Lookup>
</ns1:lookupCardToken>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Retrieve a card reference token by a developer assigned lookup key.
Typically when generating a card token, the end user is presented with a browser form by the gateway. Once the user completes the form, the user is redirected back to the developers software with the generated token. In scenarios where the developers software is not able to handle a browser redirection (or javascript hook), the developer can use the lookupCardToken method to retrieve the token after the fact.
To implement this method of retrieving the token, the developer must generate a random lookup key. When presenting the tokenization form this random lookup key should be set in the UMcardLookup variable. The same card lookup value should then be passed to the lookupCardToken method in the Lookup parameter.
If the lookup value matches multiple tokens, the most recent one will be returned. The lookupCardToken method will only match tokens created under the same merchant account.
Syntax
CreditCardToken lookupCardToken ( ueSecurityToken Token, string Lookup )
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| Lookup | string | Lookup key that was assigned during the token creation |
Response Parameters
| Name | Type | Description |
|---|---|---|
| %CreditCardToken% | object | Returns object containing card token data (including card ref) |
Receipt Methods
Receipt Templates
addReceipt
Example Request
<?php
try {
$Receipt = array(
"Name" => "CartReceipt1",
"Subject" => "Sample Cart Order # [Transaction.OrderID]",
"TemplateHTML"=>base64_encode('Yippe skippy [Transaction.Created]'),
"TemplateText"=>base64_encode('Yippe skippy [Transaction.Created]'),
"ContentType" => 'both',
"Target" => 'email',
"FromEmail" => 'noreply@mysamplecart.com'
);
$refnum = $client->addReceipt($token, $Receipt);
}
catch(SoapFault $e) {
echo $e->getMessage();
}
?>
Dim receipt As usaepay.Receipt = New usaepay.Receipt
receipt.Name = "test receipt_VB"
receipt.Target = "email"
receipt.Subject = "test receipt"
receipt.FromEmail = "devsupport@usaepay.com"
receipt.ContentType = "text"
Dim message As String
message = "Yippy skippy"
Dim toencode As Byte() = System.Text.ASCIIEncoding.ASCII.GetBytes(message)
Dim returnValue As String
returnValue = System.Convert.ToBase64String(toencode)
receipt.TemplateText = returnValue
Dim receiptNum As String
receiptNum = client.addReceipt(token, receipt)
MsgBox(receiptNum)
usaepay.Receipt receipt = new usaepay.Receipt();
receipt.Name = "test receipt";
receipt.Target = "email";
receipt.Subject = "test receipt";
receipt.FromEmail = "devsupport@usaepay.com";
receipt.ContentType = "text";
string message = "Yippy Skippy";
byte[] toencodeAsBytes = System.Text.ASCIIEncoding.ASCII.GetBytes(message);
string returnValue = System.Convert.ToBase64String(toencodeAsBytes);
receipt.TemplateText = returnValue;
string receiptRefNum;
try
{
receiptRefNum = client.addReceipt(token, receipt);
MessageBox.Show(string.Concat(receiptRefNum));
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"xmlns:ns1="urn:usaepay"
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:addReceipt>
<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">f6cc4dddf3ee69bb27c4852fdb7393f7a65d5e27</HashValue>
<Seed xsi:type="xsd:string">1477767556-test</Seed>
<Type xsi:type="xsd:string">sha1</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
</Token>
<Receipt xsi:type="ns1:Receipt">
<Name xsi:type="xsd:string">Receipt26</Name>
<Subject xsi:type="xsd:string">Example Order # [Transaction.OrderID]</Subject>
<FromEmail xsi:type="xsd:string">new@example.com</FromEmail>
<Target xsi:type="xsd:string">email</Target>
<ContentType xsi:type="xsd:string">both</ContentType>
<TemplateHTML xsi:type="xsd:string">ZXhhbXBsZSByZWNlaXB0ICBbVHJhbnNhY3Rpb24uQ3JlYXRlZF0=</TemplateHTML>
<TemplateText xsi:type="xsd:string">ZXhhbXBsZSByZWNlaXB0ICBbVHJhbnNhY3Rpb24uQ3JlYXRlZF0=</TemplateText>
</Receipt>
</ns1:addReceipt>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example Response
<?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
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:addReceiptResponse>
<addReceiptResponseReturn xsi:type="xsd:string">28</addReceiptResponseReturn>
</ns1:addReceiptResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Creates a new receipt template
This method allows you to create a new custom receipt template. Once a template has been created it can be selected when running a transaction via one of the transaction methods such as runSale or a receipt can be rendered manually for a transaction using renderReceipt.
For security reasons, the default templates can not be modified via this method.
If the receipt is created successfully a ReceiptRefNum will be returned. This ID is used to uniquely identify the receipt. If an error occurs, an exception will be thrown.
See also updateReceipt, getReceipt, deleteReceipt, emailTransactionReceipt, emailTransactionReceiptByName
Related Methods
Syntax
string addReceipt ( ueSecurityToken, Receipt )
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| %Receipt% | object | Receipt object containing receipt template data |
Response Parameters
| Name | Type | Description |
|---|---|---|
| addReceiptResponseReturn | string | Returns the gateway assigned ReceiptRefNum |
Exceptions
| Code | Message | Advice |
|---|---|---|
| 20031 | Invalid content type | ContentType must be either Text, HTML or Both |
| 20032 | Invalid receipt target | Receipt Target must be either Email or Print |
| 20033 | Receipt name already used | Receipt template names must be unique |
deleteReceipt
Example Request
<?php
try {
$ReceiptRefNum = 2;
$res = $client->deleteReceipt($token, $ReceiptRefNum);
}
catch(SoapFault $e) {
echo $e->getMessage();
}
?>
string receiptRefNum = "5";
Boolean response;
try
{
response = client.deleteReceipt(token, receiptRefNum);
MessageBox.Show(string.Concat(response));
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
?>
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
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:deleteReceipt>
<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">e4b00f3f04b7671059cda8568d339f4d8d1f7dcd</HashValue>
<Seed xsi:type="xsd:string">11104024317-test</Seed>
<Type xsi:type="xsd:string">sha1</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
</Token>
<ReceiptRefNum xsi:type="xsd:string">16</ReceiptRefNum>
</ns1:deleteReceipt>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example Response
<?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
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:deleteReceiptResponse>
<deleteReceiptReturn xsi:type="xsd:boolean">true</deleteReceiptReturn>
</ns1:deleteReceiptResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Delete receipt template
This method allows you to delete an existing custom receipt template.
Related Methods
Syntax
deleteReceipt token ueSecurityToken, string ReceiptRefNum
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| ReceiptRefNum | string | Gateway assigned receipt ID |
Response Parameters
| Name | Type | Description |
|---|---|---|
| deleteReceiptReturn | boolean | Returns true if receipt is deleted |
Exceptions
| Code | Message | Advise |
|---|---|---|
| 20030 | Requested receipt not found | ReceiptRefNum must match an existing receipt. |
Change Log
| Version | Change |
|---|---|
| 1.7 | Changed ReceiptRefNum to type string |
getReceipt
Example Request
<?php
try {
$ReceiptRefNum = 1;
$res = $client->getReceipt($token, $ReceiptRefNum);
echo base64_decode($res->TemplateText);
}
catch(SoapFault $e) {
echo $e->getMessage();
}
?>
Dim receipt As usaepay.Receipt
Dim receiptNum As String
receiptNum = "2"
receipt = client.getReceipt(token, receiptNum)
MsgBox(receipt.Name)
string receiptNumber = "5";
usaepay.Receipt receipt = new usaepay.Receipt();
try
{
receipt = client.getReceipt(token, receiptNumber);
MessageBox.Show(string.Concat(receipt.Name));}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay" 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:getReceipt>
<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">1787075eece01c89dc06a962580e2719bd92c78d</HashValue>
<Seed xsi:type="xsd:string">1172863218-test</Seed>
<Type xsi:type="xsd:string">sha1</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
</Token>
<ReceiptRefNum xsi:type="xsd:string">4</ReceiptRefNum>
</ns1:getReceipt>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example Response
<?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
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:getReceiptResponse>
<getReceiptReturn xsi:type="ns1:Receipt">
<ReceiptRefNum xsi:type="xsd:string">4</ReceiptRefNum>
<Name xsi:type="xsd:string">tranapi</Name>
<Subject xsi:type="xsd:string">Transaction[result.response]-Invoice#
[post.UMinvoice]</Subject>
<FromEmail xsi:type="xsd:string">test@tmcode.com</FromEmail>
<Target xsi:type="xsd:string">email</Target>
<ContentType xsi:type="xsd:string">text</ContentType>
<TemplateHTML xsi:type="xsd:string"></TemplateHTML>
<TemplateText xsi:type="xsd:string">VHJhbnNhY3Rpb24gUmVzdWx0DQotLS0tL
S0tLS0tLS0tLS0tLS0tLS0tLQ0KRGF0ZTogICAgICAgICAgW3Jlc3VsdC5kYXRlXQ0KW2
lmIHJlc3VsdC5yZXNwb25zZUNvZGU9QV1SZWZlcmVuY2UgIzogICBbcmVzdWx0LnRyYW5
zaWRdDQpBdXRob3JpemF0aW9uOiBbcmVzdWx0LmF1dGhjb2RlXQ0KQVZTIFJlc3VsdDog
ICAgW3Jlc3VsdC5hdnNyZXN1bHRdDQpDVlYyIFJlc3VsdDogICBbcmVzdWx0LmN2djJyZ
XN1bHRdDQpbL2lmXVtpZiByZXN1bHQucmVzcG9uc2VDb2RlIT1BXVJlc3VsdDogICAgIC
BbcmVzdWx0LnJlc3BvbnNlXQ0KUmVhc29uOiAgICAgICAgW3Jlc3VsdC5yZWFzb25dDQp
bL2lmXQ0KDQpUcmFuc2FjdGlvbiBEZXRhaWxzDQotLS0tLS0tLS0tLS0tLS0tLS0tLS0t
LQ0KTWVyY2hhbnRzOiAgICBbbWVyY2hhbnQuY29tcGFueV0NClR5cGU6ICAgICAgICBbd
HJhbnNhY3Rpb24udHlwZV0NClNvdXJjZTogICAgICBbcmVzdWx0LnNvdXJjZV0NCkludm
9pY2UgIzogICBbcG9zdC5VTWludm9pY2VdDQpBbW91bnQ6ICAgICAgJFtwb3N0LlVNYW1
vdW50XQ0KRGVzY3JpcHRpb246IFtwb3N0LlVNZGVzY3JpcHRpb25dDQpbaWYgcmVzdWx0
LmlzY2hlY2s9WV1DdXN0b21lcjogW3Bvc3QuVU1uYW1lXQ0KUm91dGluZyAjOiAgICAgW
3Bvc3QuVU1yb3V0aW5nXQ0KQ2hlY2tpbmcgQWNjdDogW3Bvc3QuVU1hY2NvdW50XVsvaW
ZdW2lmIHJlc3VsdC5pc2NyZWRpdGNhcmQ9WV1DYXJkIEhvbGRlcjogW3Bvc3QuVU1uYW1
lXQ0KQ2FyZCBOdW1iZXI6ICBbcG9zdC5VTWNhcmRdDQpbL2lmXQ0KDQpCaWxsaW5nIElu
Zm9ybWF0aW9uDQotLS0tLS0tLS0tLS0tLS0tLS0tDQpDdXN0b21lciBJRDogW3Bvc3QuV
U1jdXN0aWRdDQpGaXJzdCBOYW1lOiBbcG9zdC5VTWJpbGxmbmFtZV0NCkxhc3QgTmFtZT
ogIFtwb3N0LlVNYmlsbGxuYW1lXQ0KQ29tcGFueTogICAgW3Bvc3QuVU1iaWxsY29tcGF
ueV0NClN0cmVldDogICAgIFtwb3N0LlVNYmlsbHN0cmVldF0NClN0cmVldDI6ICAgIFtw
b3N0LlVNYmlsbHN0cmVldDJdDQpDaXR5OiAgICAgICBbcG9zdC5VTWJpbGxjaXR5XQ0KU
3RhdGU6ICAgICAgW3Bvc3QuVU1iaWxsc3RhdGVdDQpaaXA6ICAgICAgICBbcG9zdC5VTW
JpbGx6aXBdDQpDb3VudHJ5OiAgICBbcG9zdC5VTWJpbGxjb3VudHJ5XQ0KUGhvbmU6ICA
gICAgW3Bvc3QuVU1iaWxscGhvbmVdDQpFbWFpbDogICAgICBbcG9zdC5VTWVtYWlsXQ0K
DQpTaGlwcGluZyBJbmZvcm1hdGlvbg0KLS0tLS0tLS0tLS0tLS0tLS0tLS0NCkZpcnN0I
E5hbWU6IFtwb3N0LlVNc2hpcGZuYW1lXQ0KTGFzdCBOYW1lOiAgW3Bvc3QuVU1zaGlwbG
5hbWVdDQpDb21wYW55OiAgICBbcG9zdC5VTXNoaXBjb21wYW55XQ0KU3RyZWV0OiAgICA
gW3Bvc3QuVU1zaGlwc3RyZWV0XQ0KU3RyZWV0MjogICAgW3Bvc3QuVU1zaGlwc3RyZWV0
Ml0NCkNpdHk6ICAgICAgIFtwb3N0LlVNc2hpcGNpdHldDQpTdGF0ZTogICAgICBbcG9zd
C5VTXNoaXBzdGF0ZV0NClppcDogICAgICAgIFtwb3N0LlVNc2hpcHppcF0NCkNvdW50cn
k6ICAgIFtwb3N0LlVNc2hpcGNvdW50cnldDQpQaG9uZTogICAgICBbcG9zdC5VTXNoaXB
waG9uZV0NCg0KW2lmIHBvc3QuaGFzZXh0cmFmaWVsZHM9WV0gDQpBZGRpdGlvbmFsIEZp
ZWxkcw0KLS0tLS0tLS0tLS0tLS0tLS0tLS0NCltwb3N0LmV4dHJhZmllbGRzXQ0KWy9pZ
l0NCg0KW2lmIHRyYW5zYWN0aW9uLmhhc2xpbmVpdGVtcz1ZXQ0KT3JkZXIgRGV0YWlscw
0KLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0NClt0cmFuc2FjdGlvbi5saW5laXRlbXNdDQp
bL2lmXQ0KDQoNCnY4LjItdWUtZy1t</TemplateText>
</getReceiptReturn>
</ns1:getReceiptResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
This method allows you to retrieve the receipt template identified by ReceiptRefNum. The ReceiptRefNum is the ID assigned by the gateway when the receipt template was added.
If successful this method will return a Receipt object. If receipt is not found and exception will be thrown.
Related Methods
Syntax
Receipt getReceipt ( ueSecurityToken, string ReceiptRefNum)
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| ReceiptRefNum | string | Gateway assigned receipt ID |
Response Parameters
| Name | Type | Description |
|---|---|---|
| %Receipt% | object | Receipt object containing receipt template data |
Exceptions
| Code | Message | Advise |
|---|---|---|
| 20030 | Requested receipt not found | No receipts were matched using ReceiptRefNum. |
Change Log
| Version | Change |
|---|---|
| 1.7 | Changed ReceiptRefNum to type string |
getReceiptByName
Example Request
<?php
try {
$Name = 'vterm';
$res = $client->getReceiptByName($token, $Name);
echo base64_decode($res->TemplateText);
catch(SoapFault $e) {
echo $e->getMessage();
}
}
?>
Dim receipt As usaepay.Receipt
Dim receiptName As String
receiptName = "recurring"
receipt = client.getReceiptByName(token, receiptName)
MsgBox(receipt.ReceiptRefNum)
string name = "test receipt";
try {
usaepay.Receipt receipt = client.getReceiptByName(token, name);
MessageBox.Show(string.Concat(receipt.ReceiptRefNum));
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
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:getReceiptByName>
<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">49f57933fafb0b9724c501973a864fb65c46c312</HashValue>
<Seed xsi:type="xsd:string">11888875680-test</Seed>
<Type xsi:type="xsd:string">sha1</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
</Token>
<Name xsi:type="xsd:string">ExampleReceipt</Name>
</ns1:getReceiptByName>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example Response
<?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
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:getReceiptByNameResponse>
<getReceiptByNameReturn xsi:type="ns1:Receipt">
<ReceiptRefNum xsi:type="xsd:string">16</ReceiptRefNum>
<Name xsi:type="xsd:string">ExampleReceipt</Name>
<Subject xsi:type="xsd:string">Sample Cart Order # [Transaction.OrderID]</Subject>
<FromEmail xsi:type="xsd:string">noreply@mysamplecart.com</FromEmail>
<Target xsi:type="xsd:string">email</Target>
<ContentType xsi:type="xsd:string">both</ContentType>
<TemplateHTML xsi:type="xsd:string">ZXhhbXBsZSByZWNlaXB0ICBbVHJhbnNhY3Rpb24uQ3JlYXRlZF0=</TemplateHTML>
<TemplateText xsi:type="xsd:string">cmVjZWlwdCBleGFtcGxlICBbVHJhbnNhY3Rpb24uQ3JlYXRlZF0=</TemplateText>
</getReceiptByNameReturn>
</ns1:getReceiptByNameResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
This method allows you to retrieve the receipt template identified by Name. This method will return the merchant's receipt template if it exists. Otherwise, if a system default template exists for "Name" it will be returned. If a system default is returned, the ReceiptRefNum in the resulting object will be "0".
If successful this method will return a Receipt object. If receipt is not found and exception will be thrown.
Related Methods
Syntax
Receipt getReceiptByName ( ueSecurityToken, Name)
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| Name | string | Name of receipt |
Response Parameters
| Name | Type | Description |
|---|---|---|
| %Receipt% | object | Receipt object containing receipt template data |
Exceptions
| Code | Message | Advise |
|---|---|---|
| 20030 | Requested receipt not found | ReceiptRefNum must match an existing receipt |
Change Log
| Version | Change |
|---|---|
| 1.3 | Method added in this release |
getReceipts
Example Request
<?php
try {
$templates = $client->getReceipts($token, "Email");
}
catch(SoapFault $e) {
echo $e->getMessage();
}
?>
Dim target As String
target = "email"
Dim receipt() As usaepay.Receipt
receipt = client.getReceipts(token, target)
MsgBox(receipt.Length)
string target = "email";
try
{
usaepay.Receipt[] receipt = client.getReceipts(token, target);
MessageBox.Show(string.Concat(receipt.Length));
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
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:getReceipts>
<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">0435eeb0fd2e419e6fdb136d16f5338fd61012c6</HashValue>
<Seed xsi:type="xsd:string">11422802808-test</Seed>
<Type xsi:type="xsd:string">sha1</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
</Token>
<Target xsi:type="xsd:string">Both</Target>
</ns1:getReceipts>
</SOAP-ENV:Body>
Example Response
<?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body>
<ns1:getReceiptsResponse>
<getReceiptsReturn SOAP-ENC:arrayType="ns1:Receipt[3]" xsi:type="ns1:ReceiptArray">
<item xsi:type="ns1:Receipt">
<ReceiptRefNum xsi:type="xsd:string">1</ReceiptRefNum>
<Name xsi:type="xsd:string">addReceipt1909111717</Name>
<Subject xsi:type="xsd:string">1561375697</Subject>
<FromEmail xsi:type="xsd:string">test@test22.com</FromEmail>
<Target xsi:type="xsd:string">email</Target>
<ContentType xsi:type="xsd:string">both</ContentType>
</item>
<item xsi:type="ns1:Receipt">
<ReceiptRefNum xsi:type="xsd:string">4</ReceiptRefNum>
<Name xsi:type="xsd:string">tranapi</Name>
<Subject xsi:type="xsd:string">Transaction[result.response]-Invoice#[post.UMinvoice]
</Subject>
<FromEmail xsi:type="xsd:string">test@tmcode.com</FromEmail>
<Target xsi:type="xsd:string">email</Target>
<ContentType xsi:type="xsd:string">text</ContentType>
</item>
<item xsi:type="ns1:Receipt">
<ReceiptRefNum xsi:type="xsd:string">7</ReceiptRefNum>
<Name xsi:type="xsd:string">tranapi_customer</Name>
<Subject xsi:type="xsd:string">Customer Receipt</Subject>
<FromEmail xsi:type="xsd:string">support@usaepay.com</FromEmail>
<Target xsi:type="xsd:string">email</Target>
<ContentType xsi:type="xsd:string">text</ContentType>
</item>
</getReceiptsReturn>
</ns1:getReceiptsResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Retrieve list of custom receipt templates
This method allows you pull a list of the receipt templates based on the target receipt type. This type can be "Email", "Print" or "Both".
An array of Receipt objects is returned. For efficiency reasons, the actual templates (Receipt.TemplateHTML and Receipt.TemplateText) are not returned by this method. Use getReceipt to pull the full Receipt object including the templates.
If an error occurs, an exception will be thrown.
Related Methods
Syntax
Receipts getReceipts ( ueSecurityToken, Target)
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| Target | string | Type of receipts to retrieve. Possible values are: Print, Email or Both |
Response Parameters
| Name | Type | Description |
|---|---|---|
| %Receipt% | array | Returns an array of Receipt objects |
Exceptions
| Code | Message | Advice |
|---|---|---|
| 20034 | Error pulling receipt templates | Internal server error pulling list of receipts, wait and try again or contact support |
updateReceipt
Example Request
<?php
try {
$ReceiptRefNum = 2;
$Receipt = array(
"Name" => "CartReceipt1",
"Subject" => "Sample Cart Order # [Transaction.OrderID]",
"TemplateHTML"=>base64_encode('Yippe skippy [Transaction.Created]'),
"TemplateText"=>base64_encode('Yippe skippy [Transaction.Created]'),
"ContentType" => 'both',
"Target" => 'email',
"FromEmail" => 'noreply@mysamplecart.com'
);
$refnum = $client->updateReceipt($token, $ReceiptRefNum, $Receipt);
}
catch(SoapFault $e) {
echo $e->getMessage();
}
?>
Dim receiptNum As String
receiptNum = "9"
Dim receipt As usaepay.Receipt = New usaepay.Receipt
receipt.Name = "test VB_receipt"
receipt.Target = "email"
receipt.Subject = "receipt"
receipt.FromEmail = "devsupport@usaepay.com"
receipt.ContentType = "text"
Dim message As String
message = "Yippy skippy"
Dim toencode As Byte() = System.Text.ASCIIEncoding.ASCII.GetBytes(message)
Dim returnValue As String
returnValue = System.Convert.ToBase64String(toencode)
receipt.TemplateText = returnValue
Dim response As String
response = client.updateReceipt(token, receiptNum, receipt)
MsgBox(response)
string receiptRefNum = "5";
usaepay.Receipt receipt = new usaepay.Receipt();
receipt.Name = "test two";
receipt.FromEmail = "test@test.com";
receipt.ContentType = "both";
receipt.Target = "email";
string message = "Yippy Skippy";
byte[] toencodeAsBytes = System.Text.ASCIIEncoding.ASCII.GetBytes(message);
string returnValue = System.Convert.ToBase64String(toencodeAsBytes);
receipt.TemplateText = returnValue;
string response;
try
{
response = client.updateReceipt(token, receiptRefNum, receipt);
MessageBox.Show(string.Concat(response));
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
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:updateReceipt>
<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">b724babb0aa5d2be383af4c8c24ab0f33ebe14c9</HashValue>
<Seed xsi:type="xsd:string">1278607173-test</Seed>
<Type xsi:type="xsd:string">sha1</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
</Token>
<ReceiptRefNum xsi:type="xsd:string">4</ReceiptRefNum>
<Receipt xsi:type="ns1:Receipt">
<Name xsi:type="xsd:string">Receipt58</Name>
<Subject xsi:type="xsd:string">Example Order # [Transaction.OrderID]</Subject>
<FromEmail xsi:type="xsd:string">new@example.com</FromEmail>
<Target xsi:type="xsd:string">email</Target>
<ContentType xsi:type="xsd:string">both</ContentType>
<TemplateHTML xsi:type="xsd:string">ZXhhbXBsZSByZWNlaXB0ICBbVHJhbnNhY3Rpb24uQ3JlYXRlZF0=</TemplateHTML>
<TemplateText xsi:type="xsd:string">ZXhhbXBsZSByZWNlaXB0ICBbVHJhbnNhY3Rpb24uQ3JlYXRlZF0=</TemplateText>
</Receipt>
</ns1:updateReceipt>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example Response
<?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
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:updateReceiptResponse>
<updateReceiptResponseReturn xsi:type="xsd:string">4</updateReceiptResponseReturn>
</ns1:updateReceiptResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Update receipt template This method allows you to update an existing custom receipt template.
For more information about the template syntax and available fields, see the template documentation.
For security reasons, the default templates can not be modified via this method.
If the receipt is updated successfully the ReceiptRefNum will be returned. If an error occurs, an exception will be thrown.
Related Methods
Syntax
string updateReceipt ( ueSecurityToken, ReceiptRefNum, Receipt)
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| %Receipt% | object | Receipt object containing receipt template data |
| ReceiptRefNum | string | Gateway assigned receipt ID |
Response Parameters
| Name | Type | Description |
|---|---|---|
| ReceiptRefNum | string | Gateway assigned receipt ID |
Exceptions
| Code | Message | Advice |
|---|---|---|
| 20030 | Requested receipt not found | ReceiptRefNum must match an existing receipt. |
| 20031 | Invalid content type | ContentType must be either Text, HTML or Both |
| 20032 | Invalid receipt target | Receipt Target must be either Email or Print |
| 20033 | Receipt name already used | Receipt template names must be unique |
Response Parameters
| Version | Change |
|---|---|
| 1.7 | Changed ReceiptRefNum and ReturnValue to type string |
Email Receipts
emailTransactionReceipt
Example Request
<?php
try {
$TransactionRefNum=123456789;
$ReceiptRefNum=12;
$sent = $this->client->emailTransactionReceipt($this->token, $TransactionRefNum, $ReceiptRefNum,'email@address.com');
}
catch(SoapFault $e) {
echo $e->getMessage();
}
?>
Dim refnum As String
refnum = "46973419"
Dim receipt As String
receipt = "2"
Dim result As Boolean
result = client.emailTransactionReceipt(token, refnum, receipt, "email@mycompany.com")
MsgBox(result)
string refnum;
refnum = "46973419";
string receipt = "2";
Boolean result;
try
{
result = client.emailTransactionReceipt(token, refnum, receipt, "email@mycompany.com");
if (result)
{
MessageBox.Show(string.Concat("Email is sent"));
}
else MessageBox.Show("Error");
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
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:emailTransactionReceiptByName>
<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">18c29d3187820add5a29f486986c890e26c42f2b</HashValue>
<Seed xsi:type="xsd:string">194943674-test</Seed>
<Type xsi:type="xsd:string">sha1</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
</Token>
<RefNum xsi:type="xsd:string">102299266</RefNum>
<ReceiptName xsi:type="xsd:string">vterm</ReceiptName>
<Email xsi:type="xsd:string">bbb11@yahoo.com</Email>
</ns1:emailTransactionReceiptByName>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example Response
<?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
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:emailTransactionReceiptByNameResponse>
<emailTransactionReceiptByNameReturn
xsi:type="xsd:boolean">true</emailTransactionReceiptByNameReturn>
</ns1:emailTransactionReceiptByNameResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Emails a new receipt for an existing customer. Requires a custom receipt to be selected by id
This method allows you to email a new receipt for a existing transaction. This requires a receipt reference number, a transaction reference number and a valid email address. Receipt reference numbers are returned by addReceipt, getReceipts and can be found in the merchant console on the receipts edit page. Transaction reference numbers can be found in the transactionResponse or retrieved with searchTransactionsCustom.
Related Methods
Syntax
boolean emailTransactionReceipt ( ueSecurityToken, TransactionRefNum, integer Start, ReceiptRefNum, EmailAddress)
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| RefNum | string | Unique transaction reference number assigned by the gateway. You can also use TransKey in the RefNum field. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| emailTransactionReceiptByNameReturn | boolean | Indicates if the receipt sent successfully |
Exceptions
| Code | Message | Advice |
|---|---|---|
| 20001 | Specified transactions was not found | TransactionRefNum did not match a Transaction in the merchants account |
| 20030 | Requested receipt not found | ReceiptRefNum did not match any of the merchants receipts |
Change Log
| Version | Change |
|---|---|
| 1.7 | Changed RefNum to type string |
emailTransactionReceiptByName
Example Request
<?php
try {
$TransactionRefNum=123456789;
$sent = $this->client->emailTransactionReceiptByName($this->token, $RefNum, 'tranapi', 'email@address.com');;
}
catch(SoapFault $e) {
echo $e->getMessage();
}
?>
Dim refnum As String
refnum = "46973419"
Dim result As Boolean
result = client.emailTransactionReceiptByName(token, refnum, "recurring", "email@mycompany.com")
MsgBox(result)
string refnum;
refnum = "46973419";
Boolean result;
try
{
result = client.emailTransactionReceiptByName(token, refnum, "recurring", "email@yourdomain.com");
if (result)
{
MessageBox.Show(string.Concat("Email is sent"));
}
else MessageBox.Show("Error");
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
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:emailTransactionReceiptByName>
<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">a2cebc4ded4b4ef9f39176d99d0d5611b11b955b</HashValue>
<Seed xsi:type="xsd:string">11623995976-test</Seed>
<Type xsi:type="xsd:string">sha1</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
</Token>
<RefNum xsi:type="xsd:string">102301396</RefNum>
<ReceiptName xsi:type="xsd:string">tranapi_customer</ReceiptName>
<Email xsi:type="xsd:string">email@address.com</Email>
</ns1:emailTransactionReceiptByName>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example Response
<?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
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:emailTransactionReceiptByNameResponse>
<emailTransactionReceiptByNameReturn
xsi:type="xsd:boolean">true</emailTransactionReceiptByNameReturn>
</ns1:emailTransactionReceiptByNameResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Emails a new receipt for an existing transaction. Selects receipt by name.
This method allows you to email a new receipt for a existing transaction. This requires a receipt reference name, a transaction reference number and a valid email address. Transaction reference numbers can be found in the transactionResponse or retrieved with searchTransactionsCustom. The receipt name is assigned by the user when a custom receipt is created. Here are the receipt names for the system default receipts:
- vterm -Virtual Terminal (Printed)
- vterm_merchant -Virtual Terminal (Merchant Email)
- vterm_customer -Virtual Terminal (Customer Email)
- saleform_merchant -Sale Form (Merchant Email)
- saleform_customer -Sale Form (Customer Email)
- tranapi -Transaction API and Payment Form (Merchant)
- tranapi_customer -Transaction API and Payment Form (Customer)
Related Methods
Syntax
boolean emailTransactionReceiptByName ( ueSecurityToken, TransactionRefNum, integer Start, ReceiptName, EmailAddress)
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| RefNum | string | Unique transaction reference number assigned by the gateway. You can also use TransKey in the RefNum field. |
| ReceiptName | string | Name of the receipt template you want to send, assigned by user when the template is created. |
| EmailAddress | string | The email address you want to send the receipt to. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| emailTransactionReceiptByNameReturn | boolean | Indicates if the receipt sent successfully |
Exceptions
| Code | Message | Advice |
|---|---|---|
| 20001 | Specified transactions was not found | TransactionRefNum did not match a Transaction in the merchants account |
| 20030 | TrasnactionRefNum | Receipt did not match any of the merchants receipts |
Render Receipts
renderReceipt
Example Request
<?php
try {
$ReceiptRefNum = 2;
$RefNum = 1102910;
$receipt = $client->renderReceipt($token, $RefNum, $ReceiptRefNum, "HTML");
$receipt = base64_decode($receipt);
}
catch(SoapFault $e) {
echo $e->getMessage();
}
?>
Dim receiptNum As String
receiptNum = "6"
Dim refNum As String
refNum = "46981789"
Dim contentType As String
contentType = "text"
Dim response As String
response = client.renderReceipt(token, refNum, receiptNum, contentType)
Dim todecode As Byte()
todecode = Convert.FromBase64String(response)
MsgBox(System.Text.Encoding.UTF8.GetString(todecode))
string refNum = "46981789";
string receiptRefNum = "6";
string ContentType = "text";
string response;
try
{
response = client.renderReceipt(token, refNum, receiptRefNum, ContentType);
byte[] todecode = Convert.FromBase64String(response);
MessageBox.Show(string.Concat(System.Text.Encoding.UTF8.GetString(todecode)));
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
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:renderReceipt>
<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">166e37336e1c74e7e2ee9743d172b0e12c430e25</HashValue>
<Seed xsi:type="xsd:string">11110502024-test</Seed>
<Type xsi:type="xsd:string">sha1</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
</Token>
<RefNum xsi:type="xsd:string">102303382</RefNum>
<ReceiptRefNum xsi:type="xsd:string">4</ReceiptRefNum>
<ContentType xsi:type="xsd:string">Text</ContentType>
</ns1:renderReceipt>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example Response
<?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
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:renderReceiptResponse>
<renderReceiptReturn xsi:type="xsd:string">VHJhbnNhY3Rpb24gUmVzdWx0DQotLS0tLS0t
LS0tLS0tLS0tLS0tLS0tLQ0KRGF0ZTogICAgICAgICAgDQpSZXN1bHQ6ICAgICAgDQpSZWFzb246ICA
gICAgICANCg0KDQpUcmFuc2FjdGlvbiBEZXRhaWxzDQotLS0tLS0tLS0tLS0tLS0tLS0tLS0tLQ0KTW
VyY2hhbnRzOiAgICBYTUwgZXhhbXBsZSBnZW5lcmF0b3INClR5cGU6ICAgICAgICBDcmVkaXQgQ2FyZ
CBTYWxlDQpTb3VyY2U6ICAgICAgDQpJbnZvaWNlICM6ICAgDQpBbW91bnQ6ICAgICAgJA0KRGVzY3J
pcHRpb246IA0KDQoNCkJpbGxpbmcgSW5mb3JtYXRpb24NCi0tLS0tLS0tLS0tLS0tLS0tLS0NCkN1c3
RvbWVyIElEOiANCkZpcnN0IE5hbWU6IA0KTGFzdCBOYW1lOiAgDQpDb21wYW55OiAgICANClN0cmVld
DogICAgIA0KU3RyZWV0MjogICAgDQpDaXR5OiAgICAgICANClN0YXRlOiAgICAgIA0KWmlwOiAgICAg
ICAgDQpDb3VudHJ5OiAgICANClBob25lOiAgICAgIA0KRW1haWw6ICAgICAgDQoNClNoaXBwaW5nIEl
uZm9ybWF0aW9uDQotLS0tLS0tLS0tLS0tLS0tLS0tLQ0KRmlyc3QgTmFtZTogDQpMYXN0IE5hbWU6IC
ANCkNvbXBhbnk6ICAgIA0KU3RyZWV0OiAgICAgDQpTdHJlZXQyOiAgICANCkNpdHk6ICAgICAgIA0KU
3RhdGU6ICAgICAgDQpaaXA6ICAgICAgICANCkNvdW50cnk6ICAgIA0KUGhvbmU6ICAgICAgDQoNCg0K
DQoNCg0KDQp2OC4yLXVlLWctbQ==</renderReceiptReturn>
</ns1:renderReceiptResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Retrieve a receipt for a transaction
This method allows you to render a receipt template for a given transaction.
RefNum refers to the gateway assigned transaction identifier. ReceiptRefNum refers to the gateway assigned ID for the receipt. ContentType refers to the type of receipt requested.
Returns base64 encode receipt. If an error occurs, an exception will be thrown.
Related Methods
Syntax
string renderReceipt ( ueSecurityToken, RefNum, ReceiptRefNum, ContentType)
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| RefNum | string | Unique transaction reference number assigned by the gateway. You can also use TransKey in the RefNum field. |
| ReceiptRefNum | string | Gateway assigned receipt ID |
| ContentType | string | Format of receipt (HTML or Text) |
Response Parameters
| Name | Type | Description |
|---|---|---|
| renderReceiptReturn | string | Returns base64 encoded receipt |
Exceptions
| Code | Message | Advise |
|---|---|---|
| 20001 | Specified transactions was not found | Specified RefNum does not match a transaction for this merchant |
| 20030 | Requested receipt not found | ReceiptRefNum must match an existing receipt |
| 20031 | Invalid content type | ContentType must be either Text, HTML or Both |
Change Log
| Version | Change |
|---|---|
| 1.7 | Changed ReceiptRefNum to type string |
renderReceiptByName
Example Request
<?php
try {
$ReceiptName = "mycartreceipt";
$RefNum = 1102910;
$receipt = $client->renderReceiptByName($token, $RefNum, $ReceiptName, "HTML");
$receipt = base64_decode($receipt);
}
catch(SoapFault $e) {
echo $e->getMessage();
}
?>
Dim receiptName As String
receiptName = "test receipt"
Dim refNum As String
refNum = "46981789"
Dim contentType As String
contentType = "text"
Dim response As String
response = client.renderReceiptByName(token, refNum, receiptName, contentType)
Dim todecode As Byte()
todecode = Convert.FromBase64String(response)
MsgBox(System.Text.Encoding.UTF8.GetString(todecode))
string refNum = "46981789";
string receiptName = "test receipt";
string ContentType = "text";
string response;
try
{
response = client.renderReceiptByName(token, refNum, receiptName, ContentType);
byte[] todecode = Convert.FromBase64String(response);
MessageBox.Show(string.Concat(System.Text.Encoding.UTF8.GetString(todecode)));
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
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:renderReceiptByName>
<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">f5210bf4381989eb937519891cacfa0afecde107</HashValue>
<Seed xsi:type="xsd:string">11233279528-test</Seed>
<Type xsi:type="xsd:string">sha1</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
</Token>
<RefNum xsi:type="xsd:string">102302062</RefNum>
<ReceiptName xsi:type="xsd:string">tranapi_customer</ReceiptName>
<ContentType xsi:type="xsd:string">Text</ContentType>
</ns1:renderReceiptByName>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example Response
xml <?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
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:renderReceiptByNameResponse>
<renderReceiptByNameReturn xsi:type="xsd:string">WW91ciBjcmVkaXQgY2FyZCBwYXlt ZW50IGhhcyBiZWVuIHJlY2VpdmVkIGJ5IFhNTCBleGFtcGxlIGdlbmVyYXRvci4gQmVsb3cgaXMgD Qp5b3VyIHJlY2VpcHQgb2YgcGF5bWVudC4/DQoNClRyYW5zYWN0aW9uIERldGFpbHMNCi0tLS0tLS 0tLS0tLS0tLS0tLS0tLS0tDQpNZXJjaGFudDogICAgWE1MIGV4YW1wbGUgZ2VuZXJhdG9yDQpUeXB lOiAgICAgICAgQ3JlZGl0IENhcmQgU2FsZQ0KSW52b2ljZSAjOiAgIDEzMzY4MDg4MjMNCkFtb3Vu dDogICAgICAxMzIuODUNCkRlc2NyaXB0aW9uOiBFeGFtcGxlIFRyYW5zYWN0aW9uDQpDYXJkIEhvb GRlcjogVGVzdGVyIEpvbmVzDQpDYXJkIE51bWJlcjogeHh4eHh4eHh4eHh4eHg3Nzc5DQoNCg0KDQ oNCg0KDQp2OC4wMS11ZWdy
</renderReceiptByNameReturn>
</ns1:renderReceiptByNameResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Retrieve a receipt for a transaction
This method allows you to render a receipt template for a given transaction.
RefNum refers to the gateway assigned transaction identifier. ReceiptName refers to the name of the receipt. ContentType refers to the type of receipt requested.
Returns base64 encode receipt. If an error occurs, an exception will be thrown.
Related Methods
Syntax
string renderReceiptByName ( ueSecurityToken, RefNum, ReceiptRefNum, ContentType)
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| RefNum | string | Unique transaction reference number assigned by the gateway. You can also use TransKey in the RefNum field. |
| ReceiptRefNum | string | Gateway assigned receipt ID |
| ContentType | string | Format of receipt (HTML or Text) |
Response Parameters
| Name | Type | Description |
|---|---|---|
| renderReceiptByName | string | Returns base64 encoded receipt |
Exceptions
| Code | Message | Advise |
|---|---|---|
| 20001 | Specified transactions was not found | Specified RefNum does not match a transaction for this merchant |
| 20030 | Requested receipt not found | ReceiptRefNum must match an existing receipt |
| 20031 | Invalid content type | ContentType must be either Text, HTML or Both |
Change Log
| Version | Change |
|---|---|
| 1.3 | Method added in this release |
Batch Methods
Close Batch
closeBatch
Example Request
<?php
try {
// To close a specific batch use the gateway assigned batchrefnum:
$batchrefnum='1234567';
// To close the current batch use '0':
$batchrefnum='0';
$res=$tran->closeBatch($sourcekey,$batchrefnum);
}
catch (SoapFault $e) {
echo $e->getMessage();
echo "\n\nRequest: " . $tran->__getLastRequest();
echo "\n\nResponse: " . $tran->__getLastResponse();
}
?>
try {
//Creating Close Batch Request object
CloseBatchRequest Request = new CloseBatchRequest();
Request.setToken(token);
//Setting batchRefNum to 0 for current batch, for a different batch set to the Batch Ref Num
Request.setBatchRefNum(BigInteger.ZERO);
CloseBatchResponse Result = client.closeBatch(Request);
} catch (Exception e) {
System.out.println("Soap Exception: " + e.getMessage());
}
Try
client.closeBatch(token, "0")
MsgBox("Your batch has closed.")
Catch ex As Exception
MsgBox(ex.Message)
End Try
Boolean result;
// close current batch
try
{
result = client.closeBatch(token, "0");
if (result) MessageBox.Show("Batch closed successfully");
else MessageBox.Show("Batch failed to close");
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
<!--Example Request-->
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
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:closeBatch>
<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">3add5373db23ce3407500635de721d83a7c900b9</HashValue>
<Seed xsi:type="xsd:string">11177496803-test</Seed>
<Type xsi:type="xsd:string">sha1</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
</Token>
<BatchRefNum xsi:type="xsd:string">201943</BatchRefNum>
</ns1:closeBatch>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example Request
<?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
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:closeBatchResponse>
<closeBatchReturn xsi:type="xsd:boolean">true</closeBatchReturn>
</ns1:closeBatchResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
This method will close or settle an open batch. Upon settlement the funds will be transferred to the merchant's bank account.
To check the status of a batch and determine whether it has already been settled, is still open, or awaiting settlement, use the getBatchStatus method.
Related Methods
Syntax
boolean closeBatch (ueSecurityToken Token, string BatchRefNum)
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| BatchRefNum | string | A unique batch reference number assigned by the gateway. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| closeBatchReturn | boolean | Returns confirmation of the close batch request only if successful. If request fails, an exception will be thrown. |
Retrieve Batches
getBatchStatus
Example Request
<?php
try {
$BatchRefNum=0;
$Result=$client->getBatchStatus($token, $BatchRefNum);
}
catch (SoapFault $e) {
echo "get Batch Upload status failed :" .$e->getMessage();
}
?>
try {
//Set BatchNum to the Batch Reference Number of the batch
//you want to retrieve. 0 is always the current batch
BigInteger BatchNum = new BigInteger("0");
BatchStatus batchstat = new BatchStatus();
batchstat = client.getBatchStatus(token, BigInteger.ZERO);
} catch (Exception e) {
System.out.println("Soap Exception: " + e.getMessage());
}
Dim BatchRefNum As String
BatchRefNum = "9581"
Dim result as usaepay.BatchStatus = New usaepay.BatchStatus
result = client.getBatchStatus(token, BatchRefNum)
MsgBox(result.Status)
string BatchRefNum;
BatchRefNum = "9581";
usaepay.BatchStatus result = new usaepay.BatchStatus();
try
{
result = client.getBatchStatus(token, BatchRefNum);
MessageBox.Show(string.Concat(result.Status));
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
}
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
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:getBatchStatus>
<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">35aa99bcb731c2eabde8c722dcda648ca49014ed</HashValue>
<Seed xsi:type="xsd:string">11441581678-test</Seed>
<Type xsi:type="xsd:string">sha1</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
</Token>
<BatchRefNum xsi:type="xsd:string">201940</BatchRefNum>
</ns1:getBatchStatus>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example Response
<?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
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:getBatchStatusResponse>
<getBatchStatusReturn xsi:type="ns1:BatchStatus">
<BatchRefNum xsi:type="xsd:string">201940</BatchRefNum>
<Closed xsi:type="xsd:string"></Closed>
<CreditsAmount xsi:type="xsd:double">0</CreditsAmount>
<CreditsCount xsi:type="xsd:integer">0</CreditsCount>
<NetAmount xsi:type="xsd:double">1594.2</NetAmount>
<Opened xsi:type="xsd:string">01/26/2016T15:51:06</Opened>
<SalesAmount xsi:type="xsd:double">1594.2</SalesAmount>
<SalesCount xsi:type="xsd:integer">12</SalesCount>
<Scheduled xsi:type="xsd:string"></Scheduled>
<Sequence xsi:type="xsd:integer">1</Sequence>
<Status xsi:type="xsd:string">Open</Status>
<TransactionCount xsi:type="xsd:integer">12</TransactionCount>
<VoidsAmount xsi:type="xsd:double">0</VoidsAmount>
<VoidsCount xsi:type="xsd:integer">0</VoidsCount>
</getBatchStatusReturn>
</ns1:getBatchStatusResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Retrieves the status of a batch specified by its BatchRefNum.
This method will check on the status of any batch within the merchant console. Enter the BatchRefNum (a unique batch reference number assigned by the gateway) into the search field and the method will return the status of the requested batch.
To pull the status of the currently open batch (which has not yet passed to the gateway), use 0 for the the BatchRefNum.
Related Methods
Syntax
BatchStatus getBatchStatus ( ueSecurityToken Token, string BatchRefNum )
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| BatchRefNum | string | A unique batch reference number assigned by the gateway. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| %BatchStatus% | object | Returns confirmation of the close batch request only if successful. If request fails, an exception will be thrown. |
Change Log
| Version | Description |
|---|---|
| 1.7 | Changed BatchRefNum to type string |
getBatchTransactions
Example Request
<?php
try {
//Set BatchRefNum to the Batch Reference Number of the batch you want
//to retrieve transactions from. 0 is always the current batch
$BatchRefNum=0;
$Result=$client->getBatchTransactions($token, $BatchRefNum);
}
catch (SoapFault $e) {
die("get Batch Transactions failed :" .$e->getMessage());
}
?>
try {
//Set BatchNum to the Batch Reference Number of the batch you want
//to retrieve transactions from. 0 is always the current batch
BigInteger BatchNum = new BigInteger("0");
TransactionObjectArray ResultSet = new TransactionObjectArray();
ResultSet = client.getBatchTransactions(token, BatchNum);
} catch (Exception e) {
System.out.println("Soap Exception: " + e.getMessage());
}
Dim BatchRefNum As String
' Set BatchRefNum to 0 to get the current batch.
' Otherwise use batch reference num (can be found in Transaction.Details.BatchRefNum)
BatchRefNum = "0"
Dim transactions() As usaepay.TransactionObject = client.getBatchTransactions(token, BatchRefNum)
MsgBox("Found " & transactions.Length & " transactions in current batch")
string BatchRefNum = "9581";
try
{
usaepay.TransactionObject[] tran = client.getBatchTransactions(token, BatchRefNum);
MessageBox.Show(string.Concat("Found ",tran.Length));
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay" 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:getBatchTransactions>
<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">58ee8a7a846f692af341e187f06d47ffc75658f3</HashValue>
<Seed xsi:type="xsd:string">11580947680-test</Seed>
<Type xsi:type="xsd:string">sha1</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
</Token>
<BatchRefNum xsi:type="xsd:string">201949</BatchRefNum>
</ns1:getBatchTransactions>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>e>
Example Response
<?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body>
<ns1:getBatchTransactionsResponse>
<getBatchTransactionsReturn
SOAP-ENC:arrayType="ns1:TransactionObject[1]
"xsi:type="ns1:TransactionObjectArray">
<item xsi:type="ns1:TransactionObject">
<AccountHolder xsi:type="xsd:string">Tester Jones</AccountHolder>
<BillingAddress xsi:type="ns1:Address">
<City xsi:type="xsd:string"></City>
<Company xsi:type="xsd:string"></Company>
<Country xsi:type="xsd:string"></Country>
<Email xsi:type="xsd:string"></Email>
<Fax xsi:type="xsd:string"></Fax>
<FirstName xsi:type="xsd:string"></FirstName>
<LastName xsi:type="xsd:string"></LastName>
<Phone xsi:type="xsd:string"></Phone>
<State xsi:type="xsd:string"></State>
<Street xsi:type="xsd:string"></Street>
<Street2 xsi:type="xsd:string"></Street2>
<Zip xsi:type="xsd:string"></Zip>
</BillingAddress>
<CheckData xsi:type="ns1:CheckData">
<Account xsi:nil="true" />
<Routing xsi:nil="true" />
</CheckData>
<CheckTrace xsi:type="ns1:CheckTrace" />
<ClientIP xsi:type="xsd:string"></ClientIP>
<CreditCardData xsi:type="ns1:CreditCardData">
<AvsStreet xsi:type="xsd:string">1234 Main Street</AvsStreet>
<AvsZip xsi:type="xsd:string">99281</AvsZip>
<CardCode xsi:type="xsd:string">XXX</CardCode>
<CardExpiration xsi:type="xsd:string">XXXX</CardExpiration>
<CardNumber xsi:type="xsd:string">XXXXXXXXXXXX7779</CardNumber>
<CardPresent xsi:type="xsd:boolean">false</CardPresent>
<CardType xsi:type="xsd:string">V</CardType>
<InternalCardAuth xsi:type="xsd:boolean">false</InternalCardAuth>
<MagStripe xsi:type="xsd:string"></MagStripe>
<MagSupport xsi:type="xsd:string"></MagSupport>
<Pares xsi:type="xsd:string"></Pares>
<TermType xsi:type="xsd:string"></TermType>
</CreditCardData>
<CustomerID xsi:type="xsd:string"></CustomerID>
<CustomFields SOAP-ENC:arrayType="ns1:FieldValue[0]"
xsi:type="ns1:FieldValueArray" />
<DateTime xsi:type="xsd:string">2016-01-26 16:51:35</DateTime>
<Details xsi:type="ns1:TransactionDetail">
<Amount xsi:type="xsd:double">132.85</Amount>
<Clerk xsi:type="xsd:string"></Clerk>
<Currency xsi:type="xsd:string"></Currency>
<Description xsi:type="xsd:string">Example Transaction</Description>
<Comments xsi:type="xsd:string"></Comments>
<Discount xsi:type="xsd:double">0</Discount>
<Invoice xsi:type="xsd:string">1692861458</Invoice>
<NonTax xsi:type="xsd:boolean">false</NonTax>
<OrderID xsi:type="xsd:string"></OrderID>
<PONum xsi:type="xsd:string"></PONum>
<Shipping xsi:type="xsd:double">0</Shipping>
<Subtotal xsi:type="xsd:double">0</Subtotal>
<Table xsi:type="xsd:string"></Table>
<Tax xsi:type="xsd:double">0</Tax>
<Terminal xsi:type="xsd:string"></Terminal>
<Tip xsi:type="xsd:double">0</Tip>
</Details>
<LineItems SOAP-ENC:arrayType="ns1:LineItem[0]"
xsi:type="ns1:LineItemArray" />
<Response xsi:type="ns1:TransactionResponse">
<AcsUrl xsi:nil="true" />
<AuthAmount xsi:type="xsd:double">132.85</AuthAmount>
<AuthCode xsi:type="xsd:string">320781</AuthCode>
<AvsResult xsi:type="xsd:string">Address:Match & 5 Digit Zip: Match
</AvsResult>
<AvsResultCode xsi:type="xsd:string">YYY</AvsResultCode>
<BatchNum xsi:type="xsd:string">1</BatchNum>
<BatchRefNum xsi:type="xsd:string">201949</BatchRefNum>
<CardCodeResult xsi:type="xsd:string">Match</CardCodeResult>
<CardCodeResultCode xsi:type="xsd:string">M</CardCodeResultCode>
<CardLevelResult xsi:nil="true" />
<CardLevelResultCode xsi:nil="true" />
<ConversionRate xsi:type="xsd:double">0</ConversionRate>
<ConvertedAmount xsi:type="xsd:double">0</ConvertedAmount>
<ConvertedAmountCurrency xsi:type="xsd:string"></ConvertedAmountCurrency>
<CustNum xsi:type="xsd:string">0</CustNum>
<Error xsi:type="xsd:string">Approved</Error>
<ErrorCode xsi:type="xsd:integer">0</ErrorCode>
<isDuplicate xsi:type="xsd:boolean">false</isDuplicate>
<Payload xsi:nil="true" />
<RefNum xsi:type="xsd:string">103962985</RefNum>
<Result xsi:type="xsd:string">Approved</Result>
<ResultCode xsi:type="xsd:string">A</ResultCode>
<Status xsi:type="xsd:string">Pending</Status>
<StatusCode xsi:type="xsd:string">P</StatusCode>
<VpasResultCode xsi:nil="true" />
</Response>
<ServerIP xsi:type="xsd:string">209.37.25.121</ServerIP>
<ShippingAddress xsi:type="ns1:Address">
<City xsi:type="xsd:string"></City>
<Company xsi:type="xsd:string"></Company>
<Country xsi:type="xsd:string"></Country>
<Email xsi:type="xsd:string"></Email>
<Fax xsi:type="xsd:string"></Fax>
<FirstName xsi:type="xsd:string"></FirstName>
<LastName xsi:type="xsd:string"></LastName>
<Phone xsi:type="xsd:string"></Phone>
<State xsi:type="xsd:string"></State>
<Street xsi:type="xsd:string"></Street>
<Street2 xsi:type="xsd:string"></Street2>
<Zip xsi:type="xsd:string"></Zip>
</ShippingAddress>
<Source xsi:type="xsd:string">XML Trace Key</Source>
<Status xsi:type="xsd:string">Authorized (Pending Settlement)</Status>
<TransactionType xsi:type="xsd:string">Sale</TransactionType>
<User xsi:type="xsd:string">auto</User>
</item>
</getBatchTransactionsReturn>
</ns1:getBatchTransactionsResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Retrieve transactions in the batch specified by BatchRefNum
This method will return all of the transactions contained within the specified batch. Use this method to retrieve all transaction data including status, type, amount, response and customer information. Please Note: This method can pull a maximum of 1000 transactions at a time. To pull more than 1000 batch transactions, use the searchTransactions method with the BatchID as a filter. Use the limit and start to break the batch into smaller segments so search will not time out..
Related Methods
Syntax
TransactionObject getBatchTransactions ( ueSecurityToken Token, string BatchRefNum )
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| BatchRefNum | string | A unique batch reference number assigned by the gateway. |
Response Parameters
| Type | Description |
|---|---|
| %TransactionObject% | Returns an array of TransactionObjects for all transactions in the specified batch |
Change Log
| Version | Description |
|---|---|
| 1.7 | Changed BatchRefNum to type string |
searchBatches
Example Request
<?php
try {
// make sure you have prepared data to search on
$search=array(
array(
'Field'=>'closed',
'Type'=>'gt',
'Value'=>'2007-04-01'),
);
$start=0;
$limit=100;
$matchall=true;
$sort='closed';
$res=$client->searchBatches($token,$search,$matchall,$start,$limit,$sort);
print_r($res);
}
catch (SoapFault $e) {
echo $client->__getLastRequest();
echo $client->__getLastResponse();
die("Search batches failed failed :" .$e->getMessage());
}
?>
try {
SearchParamArray searchParams = new SearchParamArray();
searchParams.add(new SearchParam("Sequence","eq", "123456"));
BigInteger start = new BigInteger("0");
BigInteger limit = new BigInteger("9999999");
BatchSearchResult BatchResult = new BatchSearchResult();
BatchResult = client.searchBatches(token, searchParams, true, start, limit, "Sequence");
System.out.println(BatchResult.getBatchesMatched());
} catch (Exception e) {
System.out.println("Soap Exception: " + e.getMessage());
}
Dim matchAll As Boolean
matchAll = True
Dim start As String
Dim limit As String
Dim sort As String
start = "0"
limit = "10"
sort = "closed"
Dim search(0 To 1) As usaepay.SearchParam
search(0) = New usaepay.SearchParam
search(0).Field = "closed"
search(0).Type = "gt"
search(0).Value = "2010-08-05"
Dim result As usaepay.BatchSearchResult = New usaepay.BatchSearchResult
result = client.searchBatches(token, search, matchAll, start, limit, sort)
MsgBox(result.BatchesMatched)
Boolean matchAll;
matchAll = true;
string start = "0";
string limit = "10";
string sort = "closed";
usaepay.SearchParam[] search = new usaepay.SearchParam[2];
search[0] = new usaepay.SearchParam();
search[0].Field = "Closed";
search[0].Type = "gt";
search[0].Value = "2010-08-05";
usaepay.BatchSearchResult result = new usaepay.BatchSearchResult();
try
{
result = client.searchBatches(token, search, matchAll, start, limit, sort);
MessageBox.Show(string.Concat(result.BatchesMatched));
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
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:searchBatches>
<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">e64020497009e46cec2da75a7b92d749df748521</HashValue>
<Seed xsi:type="xsd:string">1278362198-test</Seed>
<Type xsi:type="xsd:string">sha1</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
</Token>
<Search SOAP-ENC:arrayType="ns1:SearchParam[1]" xsi:type="ns1:SearchParamArray">
<item xsi:type="ns1:SearchParam">
<Field xsi:type="xsd:string">BatchRefNum</Field>
<Type xsi:type="xsd:string">eq</Type>
<Value xsi:type="xsd:string">198907</Value>
</item>
</Search>
<MatchAll xsi:type="xsd:boolean">true</MatchAll>
<Start xsi:type="xsd:integer">0</Start>
<Limit xsi:type="xsd:integer">100</Limit>
<Sort xsi:type="xsd:string">closed</Sort>
</ns1:searchBatches>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example Response
<?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body>
<ns1:searchBatchesResponse>
<searchBatchesReturn xsi:type="ns1:BatchSearchResult">
<Batches SOAP-ENC:arrayType="ns1:BatchStatus[1]" xsi:type="ns1:BatchStatusArray">
<item xsi:type="ns1:BatchStatus">
<BatchRefNum xsi:type="xsd:string">198907</BatchRefNum>
<Closed xsi:type="xsd:string">01/26/2016T11:45:33</Closed>
<CreditsAmount xsi:type="xsd:double">3</CreditsAmount>
<CreditsCount xsi:type="xsd:integer">1</CreditsCount>
<NetAmount xsi:type="xsd:double">4766.17</NetAmount>
<Opened xsi:type="xsd:string">12/02/2015T11:48:43</Opened>
<SalesAmount xsi:type="xsd:double">4769.17</SalesAmount>
<SalesCount xsi:type="xsd:integer">87</SalesCount>
<Scheduled xsi:type="xsd:string"></Scheduled>
<Sequence xsi:type="xsd:integer">2611</Sequence>
<Status xsi:type="xsd:string">Closed</Status>
<TransactionCount xsi:type="xsd:integer">88</TransactionCount>
<VoidsAmount xsi:type="xsd:double">0</VoidsAmount>
<VoidsCount xsi:type="xsd:integer">0</VoidsCount>
</item>
</Batches>
<BatchesMatched xsi:type="xsd:integer">1</BatchesMatched>
<BatchesReturned xsi:type="xsd:integer">1</BatchesReturned>
<Limit xsi:type="xsd:integer">100</Limit>
<StartIndex xsi:type="xsd:integer">0</StartIndex>
</searchBatchesReturn>
</ns1:searchBatchesResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Use this method to search batches that you have already settled. This method allows the following fields to be used in the search: - Sequence - Platform reference number. - Opened - Date batch was opened. - Closed - Date batch was closed.
Use as many or as few search terms as you like. With MatchAll set to "true," all terms must match to return a result. If the search does not yield the desired result, try broadening your search by eliminating terms, or change MatchAll to "false."
Related Methods
Syntax
BatchSearchResult SearchBatches( ueSecurityToken Token, SearchParam Search, boolean MatchAll, integer Start, integer Limit, string Sort)
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| %SearchParam% | array | Array of search parameters. |
| MatchAll | boolean | If set to "true," only results matching all search criteria will be returned, if set to "false," results matching any of the search criteria will be returned. |
| Start | integer | Record number to start returning from (ie if 1,000 were found and you only want to receive the last 200 you would set Start=800 and Limit=200) |
| Limit | integer | Maximum number of records to return in result set. |
| Sort | string | Comma separated list of fields to sort by. |
Response Parameters
| Type | Description |
|---|---|
| %BatchSearchResult% | object |
searchBatchesCount
Example Request
<?php
try {
// make sure you have prepared data to search on
$search=array(
array(
'Field'=>'closed',
'Type'=>'gt',
'Value'=>'2007-04-01'),
);
$start=0;
$limit=100;
$matchall=true;
$sort='closed';
$res=$client->searchBatchesCount($token,$search,$matchall,$start,$limit,$sort);
print_r($res);
}
catch (SoapFault $e) {
echo $client->__getLastRequest();
echo $client->__getLastResponse();
die("Search batches failed failed :" .$e->getMessage());
}
?>
try {
SearchParamArray searchParams = new SearchParamArray();
searchParams.add(new SearchParam("Sequence","eq", "123456"));
BigInteger start = new BigInteger("0");
BigInteger limit = new BigInteger("9999999");
BatchSearchResult BatchResult = new BatchSearchResult();
BatchResult = client.searchBatchesCount(token, searchParams, true, start, limit, "Sequence");
System.out.println(BatchResult.getBatchesMatched());
} catch (Exception e) {
System.out.println("Soap Exception: " + e.getMessage());
}
Dim client As usaepay.usaepayService = New usaepay.usaepayService
Dim token As usaepay.ueSecurityToken
token = Me.CreateToken("O79erw1433ZBIE0O4Pv25aVDnw3qDVc8", "1234")
Dim matchAll As Boolean
matchAll = True
Dim start As String
Dim limit As String
Dim sort As String
start = "0"
limit = "10"
sort = "closed"
Dim search(0 To 1) As usaepay.SearchParam
search(0) = New usaepay.SearchParam
search(0).Field = "closed"
search(0).Type = "gt"
search(0).Value = "2010-08-05"
Dim result As usaepay.BatchSearchResult = New usaepay.BatchSearchResult
result = client.searchBatchesCount(token, search, matchAll, start, limit, sort)
MsgBox(result.BatchesMatched)
Boolean matchAll;
matchAll = true;
string start = "0";
string limit = "10";
string sort = "closed";
string[] fields = new string[3];
usaepay.SearchParam[] search = new usaepay.SearchParam[2];
search[0] = new usaepay.SearchParam();
search[0].Field = "Closed";
search[0].Type = "gt";
search[0].Value = "2010-08-05";
usaepay.BatchSearchResult result = new usaepay.BatchSearchResult();
try
{
result = client.searchBatchesCount(token, search, matchAll, start, limit, sort);
MessageBox.Show(string.Concat(result.BatchesMatched));
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
}
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
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:searchBatchesCount>
<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">b9f7bc3619181e72c13560322851d7994f638fe5</HashValue>
<Seed xsi:type="xsd:string">12002583462-test</Seed>
<Type xsi:type="xsd:string">sha1</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
</Token>
<Search SOAP-ENC:arrayType="ns1:SearchParam[1]" xsi:type="ns1:SearchParamArray">
<item xsi:type="ns1:SearchParam">
<Field xsi:type="xsd:string">Sequence</Field>
<Type xsi:type="xsd:string">eq</Type>
<Value xsi:type="xsd:string">2611</Value>
</item>
</Search>
<MatchAll xsi:type="xsd:boolean">true</MatchAll>
<Start xsi:type="xsd:integer">0</Start>
<Limit xsi:type="xsd:integer">100</Limit>
<Sort xsi:type="xsd:string">sequence</Sort>
</ns1:searchBatchesCount>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example Response
<?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body>
<ns1:searchBatchesCountResponse>
<searchBatchesCountReturn xsi:type="ns1:BatchSearchResult">
<Batches SOAP-ENC:arrayType="ns1:BatchStatus[0]" xsi:type="ns1:BatchStatusArray" />
<BatchesMatched xsi:type="xsd:integer">1</BatchesMatched>
<BatchesReturned xsi:type="xsd:integer">1</BatchesReturned>
<Limit xsi:type="xsd:integer">100</Limit>
<StartIndex xsi:type="xsd:integer">0</StartIndex>
</searchBatchesCountReturn>
</ns1:searchBatchesCountResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Search previously settled batches, return only counts Identical to the searchBatches method except only the batch counts are returned. Like searchBatches, this method returns BatchSearchResult. The only difference is that BatchSearchResult.Batches is left empty. This method provides a quicker way to determine the size of the result set before starting to retrieve the full search results.
Related Methods
Syntax
BatchSearchResult( ueSecurityToken Token, SearchParam Search, boolean MatchAll, integer Start, integer Limit, string Sort)
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| %SearchParam% | array | Array of search parameters. |
| MatchAll | boolean | If set to "true," only results matching all search criteria will be returned, if set to "false," results matching any of the search criteria will be returned. |
| Start | integer | Record number to start returning from (ie if 1,000 were found and you only want to receive the last 200 you would set Start=800 and Limit=200) |
| Limit | integer | Maximum number of records to return in result set. |
| Sort | string | Comma separated list of fields to sort by. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| %BatchSearchResult% | object | Returns the result of the batch search based on the search parameters set. |
Customer Methods
Customers
addCustomer
Example Request
<?php
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@usaepay.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'=>'',
);
$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();
}
?>
try {
// instantiate client connection object, select www.usaepay.com
// as the endpoint. Use sandbox.usaepay.com if connecting to
// the sandbox server.
UeSoapServerPortType client = usaepay.getClient("sandbox.usaepay.com");
// Instantiate security token object (need by all soap methods)
UeSecurityToken token = usaepay.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.getItem().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();
}
}
Dim customer As usaepay.CustomerObject = New usaepay.CustomerObject
Dim address As usaepay.Address = New usaepay.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 usaepay.PaymentMethod
payMethod(0) = New usaepay.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))
usaepay.CustomerObject customer = new usaepay.CustomerObject();
usaepay.Address address = new usaepay.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";
usaepay.PaymentMethod[] payMethod = new usaepay.PaymentMethod[1];
payMethod[0] = new usaepay.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 version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="urn:usaepay"
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>
Example Response
<?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"xmlns:ns1="urn:usaepay"
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>
This method adds a customer to your stored customer database so that their information can be recalled at a later date.
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.
Related Methods
- runCustomerTransaction
- enableCustomer
- disableCustomer
- deleteCustomer
- searchCustomerID
- getCustomer
- searchCustomers
- getCustomerHistory
- addCustomerPaymentMethod
- deleteCustomerPaymentMethod
- updateCustomer
- quickUpdateCustomer
Syntax
string addCustomer ( ueSecurityToken Token, CustomerObject CustomerData )
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| %CustomerObject% | object | Includes customer information such as customer number, merchant assigned customer ID, billing address, receipt settings, recurring billing settings, and other pertinent information. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| addCustomerReturn | string | Returns result of add customer request |
Change Log
| Version | Change |
|---|---|
| 1.7 | Changed ReturnValue to type string |
enableCustomer
Example Request
<?php
try {
$custnum="12345678";
$res=$client->enableCustomer($token, $custnum);
}
catch(SoapFault $e) {
echo "soap fault: " .$e->getMessage();
}
?>
try {
//Set CustNum for the Customer that you want to enable
BigInteger CustNum = new BigInteger("12345678");
client.enableCustomer(token, CustNum);
} catch (Exception e) {
System.out.println("Soap Exception: " + e.getMessage());
}
Dim custNum As String
custNum = "103125"
Dim response As Boolean
response = client.enableCustomer(token, custNum)
MsgBox(response)
string custNum = "89147";
Boolean response;
try
{
response = client.enableCustomer(token, custNum);
if (response)
{
MessageBox.Show(string.Concat("Succesfull"));
}
else MessageBox.Show(string.Concat("Error!"));
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
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:enableCustomer>
<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">850e5f0b4fcc4fe4dc6a4db54ddeb7b78bb2c951</HashValue>
<Seed xsi:type="xsd:string">1396230635-test</Seed>
<Type xsi:type="xsd:string">sha1</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
</Token>
<CustNum xsi:type="xsd:string">4603318</CustNum>
</ns1:enableCustomer>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example Response
<?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
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:enableCustomerResponse>
<enableCustomerReturn xsi:type="xsd:boolean">true</enableCustomerReturn>
</ns1:enableCustomerResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Enable recurring billing for a customer specified by CustNum.
This method allows you to begin a recurring billing cycle for an individual customer using their CustNum (unique customer number assigned by the gateway) as a reference. If you have lost or cannot remember the customer's CustNum, use the searchCustomerID method to retrieve it.
The recurring billing cycle can begin on any date you choose and can be set to any of the following cycles: Daily, Weekly, Bi-Weekly (every 2 weeks), Monthly, Bi-Monthly (every 2 months), Quarterly, Bi-Annually (every 6 months), and Annually.
You can also set the start and end dates, amount to be charged, and the total number of transactions for the recurring billing cycle.
Once a customer has been added to a recurring billing cycle, you can monitor and change the recurring billing settings from within the merchant console.
You can disable a customer's recurring billing cycle at any time using the disableCustomer method.
For more information about recurring billing, please refer to the support documentation in the merchant console.
Related Methods
- runCustomerTransaction
- disableCustomer
- deleteCustomer
- searchCustomerID
- getCustomer
- searchCustomers
- getCustomerHistory
- addCustomer
- addCustomerPaymentMethod
- deleteCustomerPaymentMethod
- updateCustomer
- quickUpdateCustomer
Syntax
boolean enableCustomer ( ueSecurityToken Token, string CustNum )
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| CustNum | string | A unique customer number assigned by the gateway |
Response Parameters
| Name | Type | Description |
|---|---|---|
| enableCustomerReturn | boolean | Returns result of recurring billing request. Possible values are: Approved, Error, or Declined. |
Change Log
| Version | Change |
|---|---|
| 1.7 | Changed CustNum to type string |
disableCustomer
Example Request
<?php
try {
$custnum='56805';
print_r($client->disableCustomer($token,$custnum));
}
catch(SoapFault $e) {
echo $e->getMessage();
}
?>
try {
//Set CustNum for the Customer that you want to disable
BigInteger CustNum = new BigInteger("12345678");
client.disableCustomer(token, CustNum);
} catch (Exception e) {
System.out.println("Soap Exception: " + e.getMessage());
}
Dim custNum As String
custNum = "103125"
Dim response As Boolean
response = client.disableCustomer(token, custNum)
MsgBox(response)
string custNum = "89147";
Boolean response;
try
{
response = client.deleteCustomer(token, custNum);
if (response)
{
MessageBox.Show(string.Concat("Succesfull"));
}
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
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:disableCustomer>
<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">029f32e4a817c9a0f307fa3a50ef126d79177409</HashValue>
<Seed xsi:type="xsd:string">11652288220-test</Seed>
<Type xsi:type="xsd:string">sha1</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
</Token>
<CustNum xsi:type="xsd:string">4603339</CustNum>
</ns1:disableCustomer>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example Response
<?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
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:disableCustomerResponse>
<disableCustomerReturn xsi:type="xsd:boolean">true</disableCustomerReturn>
</ns1:disableCustomerResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Disable the recurring billing for a customer specified by CustNum.
This method allows you to stop a customer's recurring billing cycle using the CustNum (unique customer number assigned by the gateway) as a reference. If you have lost or cannot remember the customer's CustNum, use the searchCustomerID method to retrieve it.
You can resume a customer's recurring billing cycle at any time using the enableCustomer method.
Related Methods
- runCustomerTransaction
- enableCustomer
- deleteCustomer
- searchCustomerID
- getCustomer
- searchCustomers
- getCustomerHistory
- addCustomer
- addCustomerPaymentMethod
- deleteCustomerPaymentMethod
- updateCustomer
- quickUpdateCustomer
Syntax
boolean disableCustomer ( ueSecurityToken Token, string CustNum )
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| CustNum | string | A unique customer number assigned by the gateway |
Response Parameters
| Name | Type | Description |
|---|---|---|
| disableCustomerReturn | boolean | Returns confirmation of the disable recurring billing request only if request is successful. If request fails, an exception will be thrown |
Change Log
| Version | Change |
|---|---|
| 1.7 | Changed CustNum to type string |
deleteCustomer
Example Request
<?php
try {
$custnum=$this->createCustomer();
$res=$client->deleteCustomer($token, $custnum);
$this->assertTrue($res);
}
catch(SoapFault $e) {
die("soap fault: " .$e->getMessage());
}
?>
try {
//Set CustNum for Customer you want to delete
BigInteger CustNum = BigInteger("12345678");
//Delete Customer
client.deleteCustomer(token, CustNum);
} catch (Exception e) {
System.out.println("Soap Exception: " + e.getMessage());
}
Dim custNum As String
custNum = "103125"
Dim response As Boolean
response = client.deleteCustomer(token, custNum)
MsgBox(response)
string custNum = "89792";
Boolean response;
try
{
response = client.deleteCustomer(token, custNum);
if (response)
{
MessageBox.Show(string.Concat("Succesfull"));
}
else MessageBox.Show(string.Concat("Error!"));
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
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:deleteCustomer>
<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">18abc8b8381259e9aea49d5e89a39521ff8a2666</HashValue>
<Seed xsi:type="xsd:string">12130139400-test</Seed>
<Type xsi:type="xsd:string">sha1</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
</Token>
<CustNum xsi:type="xsd:string">4600537</CustNum>
</ns1:deleteCustomer>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example Response
<?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
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:deleteCustomerResponse>
<deleteCustomerReturn xsi:type="xsd:boolean">true</deleteCustomerReturn>
</ns1:deleteCustomerResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Delete the customer specified by CustNum.
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.
Related Methods
- runCustomerTransaction
- enableCustomer
- disableCustomer
- searchCustomerID
- getCustomer
- searchCustomers
- getCustomerHistory
- addCustomer
- addCustomerPaymentMethod
- deleteCustomerPaymentMethod
- updateCustomer
- quickUpdateCustomer
Syntax
boolean deleteCustomer ( ueSecurityToken Token, string CustNum )
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| CustNum | string | A unique customer number assigned by the gateway |
Response Parameters
| Name | Type | Description |
|---|---|---|
| deleteCustomerReturn | boolean | Returns confirmation of request only if successful. If request fails, an exception will be thrown. |
getCustomer
Example Request
<?php
try {
$custnum='532';
print_r($client->getCustomer($token,$custnum));
}
catch(SoapFault $e) {
echo $e->getMessage();
echo "\n\nRequest: " . $client->__getLastRequest();
echo "\n\nResponse: " . $client->__getLastResponse();
}
?>
try {
//Set custnum to the Customer Number of customer you want to retrieve.
BigInteger custnum = new BigInteger("12345678");
CustomerObject customer = new CustomerObject();
customer = client.getCustomer(token, custnum);
} catch (Exception e) {
System.out.println("Soap Exception: " + e.getMessage());
}
Dim custNum As String
custNum = "103125"
Dim customer As usaepay.CustomerObject
customer = New usaepay.CustomerObject()
customer = client.getCustomer(token, custNum)
MsgBox(customer.CustomerID)
string custNum = "89147";
string response;
usaepay.CustomerObject customer = new usaepay.CustomerObject();
try
{
customer = client.getCustomer(token, custNum);
MessageBox.Show(string.Concat("CustNum: ", customer.CustomerID));
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
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:getCustomer>
<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">0a8ac70263392c59f63476aa13a97cc7e8672a5d</HashValue>
<Seed xsi:type="xsd:string">1176474488-test</Seed>
<Type xsi:type="xsd:string">sha1</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
</Token>
<CustNum xsi:type="xsd:string">4606615</CustNum>
</ns1:getCustomer>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example Response
<?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
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:getCustomerResponse>
<getCustomerReturn 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">John</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>
<Created xsi:type="xsd:dateTime">2015-12-07T15:45:32+08:00</Created>
<Currency xsi:type="xsd:string">0</Currency>
<CustNum xsi:type="xsd:string">4606615</CustNum>
<CustomData xsi:type="xsd:string"></CustomData>
<CustomFields SOAP-ENC:arrayType="ns1:FieldValue[0]"
xsi:type="ns1:FieldValueArray" />
<CustomerID xsi:type="xsd:string">711099247</CustomerID>
<Description xsi:type="xsd:string">Weekly Bill</Description>
<Enabled xsi:type="xsd:boolean">true</Enabled>
<Failures xsi:type="xsd:int">0</Failures>
<LookupCode xsi:type="xsd:string"></LookupCode>
<Modified xsi:type="xsd:dateTime">2015-12-07T15:45:32+08:00</Modified>
<Next xsi:type="xsd:string">2016-12-01T12:00:00</Next>
<Notes xsi:type="xsd:string">Testing the soap addCustomer Function</Notes>
<NumLeft xsi:type="xsd:integer">50</NumLeft>
<OrderID xsi:type="xsd:string">2073065117</OrderID>
<PaymentMethods SOAP-ENC:arrayType="ns1:PaymentMethod[1]"
xsi:type="ns1:PaymentMethodArray">
<item xsi:type="ns1:PaymentMethod">
<MethodType xsi:type="xsd:string">cc</MethodType>
<MethodID xsi:type="xsd:string">112</MethodID>
<MethodName xsi:type="xsd:string">CreditCard</MethodName>
<SecondarySort xsi:type="xsd:integer">8</SecondarySort>
<Created xsi:type="xsd:dateTime">2015-12-07T15:45:32+08:00</Created>
<Modified xsi:type="xsd:dateTime">2015-12-07T15:45:32+08:00</Modified>
<CardExpiration xsi:type="xsd:string">2018-12</CardExpiration>
<CardNumber xsi:type="xsd:string">XXXXXXXXXXXX7779</CardNumber>
<CardType xsi:type="xsd:string">V</CardType>
</item>
</PaymentMethods>
<PriceTier xsi:type="xsd:string"></PriceTier>
<ReceiptNote xsi:type="xsd:string">addCustomertestCreatedCharge</ReceiptNote>
<Schedule xsi:type="xsd:string">Weekly</Schedule>
<SendReceipt xsi:type="xsd:boolean">true</SendReceipt>
<Source xsi:type="xsd:string">Recurring</Source>
<Tax xsi:type="xsd:double">0</Tax>
<TaxClass xsi:type="xsd:string"></TaxClass>
<User xsi:type="xsd:string">(Auto)</User>
<URL xsi:type="xsd:string"></URL>
</getCustomerReturn>
</ns1:getCustomerResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Retrieve the customer details for a given CustNum.
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.
Customer details include CustNum (the gateway assigned customer number), CustID (merchant assigned customer ID), billing address, receipt settings, recurring billing settings, and other pertinent information.
Related Methods
- runCustomerTransaction
- enableCustomer
- disableCustomer
- deleteCustomer
- searchCustomerID
- searchCustomers
- getCustomerHistory
- addCustomer
- addCustomerPaymentMethod
- deleteCustomerPaymentMethod
- updateCustomer
- quickUpdateCustomer
Syntax
boolean getCustomer ( ueSecurityToken Token, string CustNum )
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| CustNum | string | A unique customer number assigned by the gateway |
Response Parameters
| Name | Type | Description |
|---|---|---|
| %CustomerObject% | object | Returns customer information such as customer number, merchant assigned customer ID, billing address, receipt settings, recurring billing settings, and other pertinent information. Customers will only show up to 1000 payment methods per customer. |
Change Log
| Version | Change |
|---|---|
| 1.7 | Changed CustNum to type string |
updateCustomer
Example Request
<?php
try {
$customer=$tran->getCustomer($token, 1309);
$customer->Amount=29.99;
$customer->Description='New Description';
$res=$client->updateCustomer($token, 1309, $customer);
print_r($res);
}
catch(SoapFault $e) {
echo "SoapFault: " .$e->getMessage();
print_r($e);
echo "\n\nRequest: " . $client->__getLastRequest();
echo "\n\nResponse: " . $client->__getLastResponse();
}
?>
Dim CustNum As String
CustNum = "103125"
Dim customer As usaepay.CustomerObject = New usaepay.CustomerObject
customer = client.getCustomer(token, CustNum)
customer.Amount = 29.99
Dim response As Boolean
response = client.updateCustomer(token, CustNum, customer)
MsgBox(response)
string CustNum = "89147";
usaepay.CustomerObject customer = new usaepay.CustomerObject();
customer = client.getCustomer(token, CustNum);
customer.Amount = 29.99;
Boolean response;
try
{
response = client.updateCustomer(token, CustNum, customer);
MessageBox.Show(string.Concat(response));
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
Replace all data for customer specified by CustNum.
This method completely replaces all existing customer data for a specific customer. If you leave any of the fields blank or do not include them in the request, it will delete those fields on the customer record.
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.
Depending on your programming language, you should be able to retrieve the customer object using the getCustomer method, alter any fields you want and then submit it back using the updateCustomer method.
To update only a few specific fields, use the quickUpdateCustomer method.
Related Methods
- runCustomerTransaction
- enableCustomer
- disableCustomer
- deleteCustomer
- searchCustomerID
- getCustomer
- searchCustomers
- getCustomerHistory
- addCustomer
- addCustomerPaymentMethod
- deleteCustomerPaymentMethod
- quickUpdateCustomer
Syntax
boolean updateCustomer ( ueSecurityToken Token, string CustNum, CustomerObject CustomerData)
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| CustNum | string | A unique customer number assigned by the gateway |
| %CustomerObject% | CustomerData | Includes customer information such as customer number, merchant assigned customer ID, billing address, receipt settings, recurring billing settings, and other pertinent information |
Response Parameters
| Name | Type | Description |
|---|---|---|
| updateCustomerReturn | boolean | Returns confirmation of customer update only if data revision was successful. If update fails, an exception will be thrown |
Change Log
| Version | Change |
|---|---|
| 1.7 | Changed CustNum to type string |
quickUpdateCustomer
Example Request
<?php
try {
$custnum='532';
$update=array(
array('Field'=>'CardExp' , 'Value'=>'0913'),
array('Field'=>'CardNumber', 'Value'=>'4444555566667779'),
array('Field'=>'Amount' , 'Value'=>'1.34'),
array('Field'=>'Address' , 'Value'=>'Time: ' . mktime()),
array('Field'=>'CustomData', 'Value'=> serialize(array("MyField" => "myval"))),
);
print_r($client->quickUpdateCustomer($token,$custnum, $update));
}
catch(SoapFault $e) {
echo "Error: " . $e->faultstring;
echo "\n\nRequest: " . $client->__getLastRequest();
echo "\n\nResponse: " . $client->__getLastResponse();
}
catch(Exception $e) {
echo 'Error: ' . $e->getMessage();
}
?>
try {
BigInteger custnum = new BigInteger("1235");
// Create array of fields to update
FieldValueArray updateData = new FieldValueArray();
updateData.add(new FieldValue("Schedule", "daily"));
updateData.add(new FieldValue("Amount", "5.00"));
// run quick update
boolean response = client.quickUpdateCustomer(token, custnum, updateData);
} catch (Exception e) {
System.out.println("Soap Exception: " + e.getMessage());
}
Dim custNum As String
custNum = "103125"
Dim fields(0 To 1) As usaepay.FieldValue
For i As Integer = 0 To 1
fields(i) = New usaepay.FieldValue
Next i
fields(0).Field = "Schedule"
fields(0).Value = "monthly"
fields(1).Field = "Amount"
fields(1).Value = "5.00"
Dim response As Boolean
response = client.quickUpdateCustomer(token, custNum, fields)
MsgBox(response)
string custNum = "89147";
usaepay.FieldValue[] fields = new usaepay.FieldValue[2];
for (int i = 0; i < 2; i++) {
fields[i] = new usaepay.FieldValue();
}
fields[0].Field = "Schedule"; fields[0].Value = "monthly";
fields[1].Field = "Amount"; fields[1].Value = "5.00";
Boolean response;
try
{
response = client.quickUpdateCustomer(token, custNum, fields);
MessageBox.Show(string.Concat(response));
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"xmlns:ns1="urn:usaepay"
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:quickUpdateCustomer>
<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">aad4e875fdc4ff508e7b426e0bd5f2f322946b75</HashValue>
<Seed xsi:type="xsd:string">1425719194-test</Seed>
<Type xsi:type="xsd:string">sha1</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
</Token>
<CustNum xsi:type="xsd:string">4610866</CustNum>
<UpdateData SOAP-ENC:arrayType="ns1:FieldValue[4]" xsi:type="ns1:FieldValueArray">
<item xsi:type="ns1:FieldValue">
<Field xsi:type="xsd:string">CustomerID</Field>
<Value xsi:type="xsd:string">55555</Value>
</item>
<item xsi:type="ns1:FieldValue">
<Field xsi:type="xsd:string">CardExp</Field>
<Value xsi:type="xsd:string">0919</Value>
</item>
<item xsi:type="ns1:FieldValue">
<Field xsi:type="xsd:string">CardNumber</Field>
<Value xsi:type="xsd:string">4000100911112225</Value>
</item>
<item xsi:type="ns1:FieldValue">
<Field xsi:type="xsd:string">Amount</Field>
<Value xsi:type="xsd:string">80.50</Value>
</item>
</UpdateData>
</ns1:quickUpdateCustomer>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example Response
<?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"xmlns:ns1="urn:usaepay"
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:quickUpdateCustomerResponse>
<quickUpdateCustomerReturn xsi:type="xsd:boolean">true</quickUpdateCustomerReturn>
</ns1:quickUpdateCustomerResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Update customer data in selected fields only.
This method allows you to update only specified data for a customer record, rather than replacing all existing data. Fields that can be changed using this method include a customer's contact information, as well as customized notes on their account and information regarding any recurring billing cycle that they have been enabled for, such as the amount to be billed, and the number of transactions remaining.
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.
This method uses the UpdateData array containing the fields that you would like to update. The "key" of each element is the name of the field you wish to change and the "value" of the element is the new value that you would like to assign.
The following fields may be updated using this method:
| FirstName | Address | Enabled |
| CustomerID | City | Schedule |
| Card Number | State | Next |
| CardExp | Zip | NumLeft |
| Account | Country | Amount |
| Routing | Phone | ReceiptNote |
| CheckFormat | fax | SendReceipt |
| CustomData | Notes | |
| Source | URL | Description |
| User | OrderID |
Related Methods
- runCustomerTransaction
- enableCustomer
- disableCustomer
- deleteCustomer
- searchCustomerID
- getCustomer
- searchCustomers
- getCustomerHistory
- addCustomer
- addCustomerPaymentMethod
- deleteCustomerPaymentMethod
- updateCustomer
Syntax
boolean quickUpdateCustomer ( ueSecurityToken Token, string CustNum, FieldValue UpdateData )
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| CustNum | string | A unique customer number assigned by the gateway |
| UpdateData | array | Array of FieldValue objects to be updated. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| quickUpdateCustomerReturn | boolean | Returns confirmation of request only if successful. If request fails, an exception will be thrown |
Change Log
| Version | Change |
|---|---|
| 1.7 | Changed CustNum to type string |
| 1.1 | Method added prior to v1.1 |
copyCustomer
Example Request
<?php
try {
// CustNum for Customer to Copy
$CustNum="12345678";
// $toMerchToken is setup with sourcekey
// for merchant being copied to
$NewCustNum=$client->copyCustomer($token, $CustNum,$toMerchToken);
} catch(Exception $e) {
echo 'Error: ' . $e->getMessage();
}
?>
try {
//CusNum From Customer to copy
BigInteger CustNum = BigInteger("12345678");
// toMerchToken is the token setup with a source key
// for the merchant being copied to.
BigInteger NewCustNum = client.copyCustomer(token, CustNum, toMerchToken);
} catch (Exception e) {
System.out.println("Soap Exception: " + e.getMessage());
}
Dim token1 As usaepay.ueSecurityToken
Dim token2 As usaepay.ueSecurityToken
token1 = Me.CreateToken("source key of the merchant1", "1234")
token2 = Me.CreateToken("source key of the merchant2", "1234")
Dim custNum As String
custNum = "103125"
Dim NewCust As String
NewCust = client.copyCustomer(token1, custNum, token2)
MsgBox(NewCust)
usaepay.ueSecurityToken totoken = new usaepay.ueSecurityToken();
usaepay.ueHash hash = new usaepay.ueHash();
string sourcekey = "NEW SOURCE KEY";
string pin = "new pin";
totoken.SourceKey = sourcekey;
hash.Type = "md5";
hash.Seed = Guid.NewGuid().ToString();
string prehashvalue = string.Concat(token.SourceKey, hash.Seed, pin);
hash.HashValue = GenerateHash(prehashvalue);
totoken.PinHash = hash;
string CustNum = "89147";
string NewCust;
try
{
NewCust = client.copyCustomer(token, CustNum, totoken);
MessageBox.Show(string.Concat(NewCust));
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
This method allows you to copy a customer record from one merchant to another. This method is only available to merchants who have a master user setup to access both accounts.
Syntax
CustNum copyCustomer ( ueSecurityToken Token, string CustNum )
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| CustNum | string | A unique customer number assigned by the gateway |
| %ueSecurityToken% | object | Merchant security token: used to identify the merchant that the customer is being copied to. |
Return Value
| Name | Type | Description |
|---|---|---|
| CustNum | string | Returns gateway assigned Customer Number of the new customer. |
Change Log
| Version | Description |
|---|---|
| 1.7 | Changed ReturnValue to type string |
moveCustomer
Example Request
try {
//Set CustNum to the customer number that you want to move. "merch2token"
//represents a token set up under the merchant the customer is being moved to.
BigInteger CustNum = new BigInteger("123456");
BigInteger NewCustNum = client.moveCustomer(token, CustNum, merch2token);
System.out.println(NewCustNum);
} catch (Exception e) {
System.out.println("Soap Exception: " + e.getMessage());
}
Dim client As usaepay.usaepayService = New usaepay.usaepayService
Dim token1 As usaepay.ueSecurityToken
Dim token2 As usaepay.ueSecurityToken
token1 = Me.CreateToken("source key of the merchant1", "1234")
token2 = Me.CreateToken("source key of the merchant2", "1234")
Dim custNum As String
custNum = "103125"
Dim NewCust As String
NewCust = client.moveCustomer(token1, custNum, token2)
MsgBox(NewCust)
usaepay.ueSecurityToken totoken = new usaepay.ueSecurityToken();
usaepay.ueHash hash = new usaepay.ueHash();
string sourcekey = "NEW SOURCE KEY";
string pin = "new pin";
totoken.SourceKey = sourcekey;
hash.Type = "md5";
hash.Seed = Guid.NewGuid().ToString();
string prehashvalue = string.Concat(token.SourceKey, hash.Seed, pin);
hash.HashValue = GenerateHash(prehashvalue);
totoken.PinHash = hash;
string CustNum = "89147";
string NewCust;
try
{
NewCust = client.moveCustomer(token, CustNum, totoken);
MessageBox.Show(string.Concat(NewCust));
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
This method allows you to move a customer record from one merchant to another. This method is only available to merchants who have a master user setup to access both accounts. The move method copies the customer to new merchant and then deletes the original customer. A new CustNum is assigned.
Syntax
CustNum moveCustomer ( ueSecurityToken FromToken, string CustNum, ueSecurityToken ToToken)
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| CustNum | string | A unique customer number assigned by the gateway |
| %ueSecurityToken% | object | Merchant security token: used to identify the merchant that the customer is being migrated to. |
Return Value
| Name | Type | Description |
|---|---|---|
| CustNum | string | Returns gateway assigned Customer Number of the new customer. |
Change Log
| Version | Description |
|---|---|
| 1.7 | Changed CustNum and ReturnValue to type string |
Pay Methods
addCustomerPaymentMethod
Example Request
<?php
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();
}
?>
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());
}
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)
MsgBox(response)
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;
try
{
response = client.addCustomerPaymentMethod(token, CustNum,payMethod,false,true);
MessageBox.Show(string.Concat(response));
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"xmlns:ns1="urn:usaepay"
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>
Example Response
<?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
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>
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.
Related Methods
- runCustomerTransaction
- enableCustomer
- disableCustomer
- deleteCustomer
- searchCustomerID
- getCustomer
- searchCustomers
- getCustomerHistory
- addCustomer
- deleteCustomerPaymentMethod
- updateCustomer
- quickUpdateCustomer
Syntax
string runSale ( ueSecurityToken Token, string CustNum, PaymentMethod Payment Method, boolean MakeDefault, boolean Verify )
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| CustNum | string | A unique customer number assigned by the gateway |
| %PaymentMethod% | object | Includes method name, description, ID, and expiration date. |
| MakeDefault | boolean | Determines default payment method for specified customer. If set to true, payment method will be marked as default. |
| Verify | boolean | If set to true, an AuthOnly verification of the credit card validity will be run. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| addCustomerPaymentMethodReturn | string | The ID of the new payment method. |
setDefaultPaymentMethod
Example Request
<?php
try {
//Set CustNum for the Customer that you
//want to delete a payment method from
$CustNum="12345678"
//Set PayID for the Payment Method ID
//that you want to delete
$PayID="7654321"
// Delete the payment method
$Result=$client->setDefaultPaymentMethod($token, $CustNum, $PayID);
}
catch(Exception $e) {
echo 'Error: ' . $e->getMessage();
}
?>
This method makes a specific payment method the default for a customer.
Each customer record may contain multiple payment methods. (Exception: see Beta6 note below.) This option allows you to remove expired or unused payment methods from your customer's records.
New payment methods may be added by using addCustomerPaymentMethod.
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.
Related Methods
- runCustomerTransaction
- enableCustomer
- disableCustomer
- enableCustomer
- deleteCustomer
- searchCustomerID
- getCustomer
- searchCustomers
- getCustomerHistory
- addCustomer
- addCustomerPaymentMethod
- updateCustomer
- quickUpdateCustomer
Syntax
boolean setDefaultPaymentMethod ( ueSecurityToken Token, string Custnum, string PaymentMethodID)
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| CustNum | string | System assigned CustNum of stored customer record. |
| PaymentMethodID | string | System assigned id of stored customer payment method. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| setDefaultPaymentMethodReturn | boolean | Returns confirmation of that payment method was set to default. If this fails, an exception will be thrown. |
deleteCustomerPaymentMethod
Example Request
<?php
try {
//Set CustNum for the Customer that you
//want to delete a payment method from
$CustNum="12345678"
//Set PayID for the Payment Method ID
//that you want to delete
$PayID="7654321"
// Delete the payment method
$Result=$client->deleteCustomerPaymentMethod($token, $CustNum, $PayID);
} catch(Exception $e) {
echo 'Error: ' . $e->getMessage();
}
?>
try {
//Set CustNum for the Customer that you
//want to delete a payment method from
BigInteger custnum = new BigInteger("12345678");
//Set PayID for the Payment Method ID
//that you want to delete
BigInteger PayID = new BigInteger("7654321");
boolean Result = client.deleteCustomerPaymentMethod(token, CustNum, PayID);
} catch (Exception e) {
System.out.println("Soap Exception: " + e.getMessage());
}
Dim CustNum As String
CustNum = "103125"
Dim PaymentID As String
PaymentID = "41"
Dim response As Boolean
response = client.deleteCustomerPaymentMethod(token, CustNum, PaymentID)
MsgBox(response)
string CustNum = "89792";
string PaymentID = "21";
Boolean response;
try
{
response = client.deleteCustomerPaymentMethod(token, CustNum, PaymentID);
MessageBox.Show(string.Concat(response));
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
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:deleteCustomerPaymentMethod>
<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">3d3a48eb1887857ae8bcb74a8e106ffecd7127de</HashValue>
<Seed xsi:type="xsd:string">1782568488-test</Seed>
<Type xsi:type="xsd:string">sha1</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
</Token>
<Custnum xsi:type="xsd:string">4608157</Custnum>
<PaymentMethodID xsi:type="xsd:string">163</PaymentMethodID>
</ns1:deleteCustomerPaymentMethod>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example Response
<?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
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:deleteCustomerPaymentMethodResponse>
<deleteCustomerPaymentMethodReturn xsi:type="xsd:boolean">true</deleteCustomerPaymentMethodReturn>
</ns1:deleteCustomerPaymentMethodResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Delete a payment method from an existing customer.
This method removes a stored payment method from a customer's record.
Each customer record may contain multiple payment methods. (Exception: see Beta6 note below.) This option allows you to remove expired or unused payment methods from your customer's records.
New payment methods may be added by using addCustomerPaymentMethod.
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.
Please Note: Beta6 supports only one payment method for each customer. This means that if you delete a payment method from a customer's account without adding a new method, the customer will be left with no existing payment methods.
Related Methods
- runCustomerTransaction
- enableCustomer
- disableCustomer
- deleteCustomer
- searchCustomerID
- getCustomer
- searchCustomers
- getCustomerHistory
- addCustomer
- addCustomerPaymentMethod
- updateCustomer
- quickUpdateCustomer
Syntax
boolean deleteCustomerPaymentMethod ( ueSecurityToken Token, string CustNum, string PaymentMethodID )
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| CustNum | string | System assigned CustNum of stored customer record. |
| PaymentMethodID | string | System assigned id of stored customer payment method. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| deleteCustomerPaymentMethodReturn | boolean | Returns confirmation of payment method deletion only if successful. If deletion fails, an exception will be thrown. |
getCustomerPaymentMethod
Example Request
<?php
try {
$custnum = '532';
$methodid = '1234';
$paymethod = $client->getCustomerPaymentMethod($token,$custnum,$methodid);
print_r($paymethod);
echo $paymethod->MethodName . "\n";
} catch(SoapFault $e) {
echo $e->getMessage();
echo "\n\nRequest: " . $client->__getLastRequest();
echo "\n\nResponse: " . $client->__getLastResponse();
}
?>
try {
//Set custnum to the Customer Number of customer you
//want to retrieve a payment method from.
BigInteger custnum = new BigInteger("12345678");
//Set PayID to the Payment Method ID of the
//Payment Method you want to retrieve.
BigInteger PayID = new BigInteger("654321");
PaymentMethod PayMethod = new PaymentMethod();
PayMethod = client.getCustomerPaymentMethod(token, custnum, PayID);
} catch (Exception e) {
System.out.println("Soap Exception: " + e.getMessage());
}
Dim CustNum As String
CustNum = "103125"
Dim MethodID As String
MethodID = "39"
Dim Method As usaepay.PaymentMethod = New usaepay.PaymentMethod
Method = client.getCustomerPaymentMethod(token, CustNum, MethodID)
MsgBox(Method.Created)
string CustNum = "89147";
string MethodID = "19";
usaepay.PaymentMethod Method = new usaepay.PaymentMethod();
try {
Method = client.getCustomerPaymentMethod(token, CustNum, MethodID);
MessageBox.Show(string.Concat(Method.Created));
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay" 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:getCustomerPaymentMethod>
<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">cb0d69fef422f746976fa6eceef0cc2535fa6263</HashValue>
<Seed xsi:type="xsd:string">1753029979-test</Seed>
<Type xsi:type="xsd:string">sha1</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
</Token>
<CustNum xsi:type="xsd:string">4608985</CustNum>
<MethodID xsi:type="xsd:string">178</MethodID>
</ns1:getCustomerPaymentMethod>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example Response
<?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
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:getCustomerPaymentMethodResponse>
<getCustomerPaymentMethodReturn xsi:type="ns1:PaymentMethod">
<MethodType xsi:type="xsd:string">cc</MethodType>
<MethodID xsi:type="xsd:string">178</MethodID>
<MethodName xsi:type="xsd:string">CreditCard</MethodName>
<SecondarySort xsi:type="xsd:integer">8</SecondarySort>
<Created xsi:type="xsd:dateTime">2015-12-09T11:08:20+08:00</Created>
<Modified xsi:type="xsd:dateTime">2015-12-09T11:08:20+08:00</Modified>
<AvsStreet xsi:type="xsd:string">5454 Bravo St</AvsStreet>
<AvsZip xsi:type="xsd:string">91111</AvsZip>
<CardExpiration xsi:type="xsd:string">2018-12</CardExpiration>
<CardNumber xsi:type="xsd:string">XXXXXXXXXXXX7779</CardNumber>
<CardType xsi:type="xsd:string">V</CardType>
</getCustomerPaymentMethodReturn>
</ns1:getCustomerPaymentMethodResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
This method allows you to retrieve a specific payment method stored for a particular customer.
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.
You must also specify the MethodID for the desired Payment Method. This MethodID is assigned by the gateway and returned by (#addcustomerpaymentmethod). You can also obtain the methodid from the MethodID property of the PaymentMethod object. This is returned by either getCustomer or (#getcustomerpaymentmethods).
Related Methods
Syntax
PaymentMethod getCustomerPaymentMethod ( ueSecurityToken Token, string CustNum, string Method ID )
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| CustNum | string | A unique customer number assigned by the gateway |
| MethodID | string | Unique payment method ID assigned by the gateway. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| %PaymentMethod% | object | Includes method name, description, ID, and expiration date. |
Change Log
| Version | Description |
|---|---|
| 1.7 | Changed CustNum and PaymentMethodID to type string |
| 1.2 | The getPaymentMethod method was added in release 1.2 |
updateCustomerPaymentMethod
Example Request
<?php
try {
$PaymentMethod=array(
'MethodID' => '375',
'MethodName'=>'',
'CardNumber'=>'XXXXXXXXXXXX7779',
'CardExpiration'=>'2013-02',
'CardType'=>'',
'CardCode'=>'',
'AvsStreet'=>'',
'AvsZip'=>'',
'CardPresent'=>'',
'MagStripe'=>'',
'TermType'=>'',
'MagSupport'=>'',
'XID'=>'',
'CAVV'=>'',
'ECI'=>'',
'InternalCardAuth'=>'',
'Pares'=>'',
'SecondarySort'=>0,
);
$Verify=false;
$res=$client->updateCustomerPaymentMethod($token,$PaymentMethod,$Verify);
$this->assertTrue($res>0, 'Positive PaymentMethodID');
print_r($res);
}
catch(SoapFault $e) {
echo "\n\nResponse: " . $tran->__getLastResponse();
die("soap fault: " .$e->getMessage());
echo "SoapFault: " .$e->getMessage();
print_r($e);
echo "\n\nRequest: " . $tran->__getLastRequest();
}
?>
Dim method As usaepay.PaymentMethod = New usaepay.PaymentMethod
method.MethodID = "39"
method.MethodName = "My different"
method.CardExpiration = "1212"
method.CardNumber = "4444555566667779"
Dim verify As Boolean
verify = True
Dim response As Boolean
response = client.updateCustomerPaymentMethod(token, method, verify)
MessageBox.Show(String.Concat(response))
usaepay.PaymentMethod method = new usaepay.PaymentMethod();
method.MethodID = "19";
method.MethodName = "My different";
method.CardExpiration = "1212";
method.CardNumber = "4444555566667779";
Boolean verify = true;
Boolean response;
try
{
response = client.updateCustomerPaymentMethod(token, method, verify);
MessageBox.Show(string.Concat(response));
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
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:updateCustomerPaymentMethod>
<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">ad0d6fd9b98dae47ad7055cb913fba200ed483e1</HashValue>
<Seed xsi:type="xsd:string">1160851186-test</Seed>
<Type xsi:type="xsd:string">sha1</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
</Token>
<PaymentMethod xsi:type="ns1:PaymentMethod">
<MethodID xsi:type="xsd:string">292</MethodID>
<MethodName xsi:type="xsd:string">Work visa</MethodName>
<SecondarySort xsi:type="xsd:integer">0</SecondarySort>
<AvsStreet xsi:type="xsd:string">2828 vida st</AvsStreet>
<AvsZip xsi:type="xsd:string">94444</AvsZip>
<CardExpiration xsi:type="xsd:string">2019-02</CardExpiration>
<CardNumber xsi:type="xsd:string">4000100711112227</CardNumber>
</PaymentMethod>
<Verify xsi:type="xsd:boolean">false</Verify>
</ns1:updateCustomerPaymentMethod>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example Response
<?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
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:updateCustomerPaymentMethodResponse>
<updateCustomerPaymentMethodReturn xsi:type="xsd:boolean">true</updateCustomerPaymentMethodReturn>
</ns1:updateCustomerPaymentMethodResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Updates the existing payment method. PaymentMethod.MethodID is used to determine which payment method to update.
Related Methods
- runCustomerTransaction
- enableCustomer
- disableCustomer
- deleteCustomer
- searchCustomerID
- getCustomer
- searchCustomers
- getCustomerHistory
- addCustomer
- deleteCustomerPaymentMethod
- updateCustomer
- quickUpdateCustomer
Syntax
string updateCustomerPaymentMethod ( ueSecurityToken Token, PaymentMethod PaymentMethod, boolean Verify )
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| %PaymentMethod% | object | Includes method name, description, ID, and expiration date. |
| Verify | boolean | If set to true, an AuthOnly verification of the credit card validity will be run. (See above.) |
Response Parameters
| Name | Type | Description |
|---|---|---|
| updateCustomerPaymentMethodReturn | boolean | Returns true if payment method is updated successfully. |
Change Log
| Version | Description |
|---|---|
| 1.2 | Method added. |
Search Customer Database
searchCustomers
Example Request
<?php
try {
$search=array(
array(
'Field'=>'amount',
'Type'=>'gt',
'Value'=>'8.00'),
array(
'Field'=>'failures',
'Type'=>'gt',
'Value'=>'0')
);
$start=0;
$limit=10;
$matchall=true;
$RefNum=1009411;
$Sort = "fname";
$res=$client->searchCustomers($token,$search,$matchall,$start,$limit,$Sort);
print_r($res);
$this->assertTrue($res->CustomersMatched>0 && $res->CustomersReturned>0);
}
catch (SoapFault $e) {
die("Search Customers failed :" .$e->getMessage());
}
?>
Dim matchAll As Boolean
matchAll = True
Dim search(0) As usaepay.SearchParam
search(0) = New usaepay.SearchParam()
search(0).Field = "Created"
search(0).Type = "Contains"
search(0).Value = "2010-09-09"
Dim response As usaepay.CustomerSearchResult = New usaepay.CustomerSearchResult
response = client.searchCustomers(token, search, matchAll, "0", "10", "fname")
MsgBox(response.CustomersMatched)
Boolean matchAll;
matchAll = true;
usaepay.SearchParam[] search = new usaepay.SearchParam[2];
search[0] = new usaepay.SearchParam();
search[0].Field = "Created";
search[0].Type = "Contains";
search[0].Value = "2010-08-10";
usaepay.CustomerSearchResult response = new usaepay.CustomerSearchResult();
try
{
response = client.searchCustomers(token, search, matchAll, "0", "10", "fname");
MessageBox.Show(response.CustomersMatched);
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"xmlns:ns1="urn:usaepay"
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:searchCustomers>
<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">1766a93e46bf263b409d0f444b2eb34b00daa035</HashValue>
<Seed xsi:type="xsd:string">1345308215-test</Seed>
<Type xsi:type="xsd:string">sha1</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
</Token>
<Search SOAP-ENC:arrayType="ns1:SearchParam[1]" xsi:type="ns1:SearchParamArray">
<item xsi:type="ns1:SearchParam">
<Field xsi:type="xsd:string">customerid</Field>
<Type xsi:type="xsd:string">contains</Type>
<Value xsi:type="xsd:string">380</Value>
</item>
</Search>
<MatchAll xsi:type="xsd:boolean">true</MatchAll>
<Start xsi:type="xsd:integer">0</Start>
<Limit xsi:type="xsd:integer">9999</Limit>
<Sort xsi:nil="true"/></ns1:searchCustomers>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example Response
<?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"xmlns:ns1="urn:usaepay"
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body>
<ns1:searchCustomersResponse>
<searchCustomersReturn xsi:type="ns1:CustomerSearchResult">
<Customers SOAP-ENC:arrayType="ns1:CustomerObject[1]" xsi:type="ns1:CustomerObjectArray">
<item 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">John</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>
<Created xsi:type="xsd:dateTime">2015-12-07T16:35:00+08:00</Created>
<Currency xsi:type="xsd:string">0</Currency>
<CustNum xsi:type="xsd:string">4606627</CustNum>
<CustomData xsi:type="xsd:string"></CustomData>
<CustomFields SOAP-ENC:arrayType="ns1:FieldValue[0]" xsi:type="ns1:FieldValueArray" />
<CustomerID xsi:type="xsd:string">380</CustomerID>
<Description xsi:type="xsd:string">Weekly Bill</Description>
<Enabled xsi:type="xsd:boolean">true</Enabled>
<Failures xsi:type="xsd:int">0</Failures>
<LookupCode xsi:type="xsd:string"></LookupCode>
<Modified xsi:type="xsd:dateTime">2015-12-07T16:35:00+08:00</Modified>
<Next xsi:type="xsd:string">2016-12-01T12:00:00</Next>
<Notes xsi:type="xsd:string">Testing the soap addCustomer Function</Notes>
<NumLeft xsi:type="xsd:integer">50</NumLeft>
<OrderID xsi:type="xsd:string">1698032860</OrderID>
<PaymentMethods SOAP-ENC:arrayType="ns1:PaymentMethod[1]" xsi:type="ns1:PaymentMethodArray">
<item xsi:type="ns1:PaymentMethod">
<MethodType xsi:type="xsd:string">cc</MethodType>
<MethodID xsi:type="xsd:string">115</MethodID>
<MethodName xsi:type="xsd:string">CreditCard</MethodName>
<SecondarySort xsi:type="xsd:integer">8</SecondarySort>
<Created xsi:type="xsd:dateTime">2015-12-07T16:35:00+08:00</Created>
<Modified xsi:type="xsd:dateTime">2015-12-07T16:35:00+08:00</Modified>
<CardExpiration xsi:type="xsd:string">2018-12</CardExpiration>
<CardNumber xsi:type="xsd:string">XXXXXXXXXXXX7779</CardNumber>
<CardType xsi:type="xsd:string">V</CardType>
</item>
</PaymentMethods>
<PriceTier xsi:type="xsd:string"></PriceTier>
<ReceiptNote xsi:type="xsd:string">addCustomer test Created Charge</ReceiptNote>
<Schedule xsi:type="xsd:string">Weekly</Schedule>
<SendReceipt xsi:type="xsd:boolean">true</SendReceipt>
<Source xsi:type="xsd:string">Recurring</Source>
<Tax xsi:type="xsd:double">0</Tax>
<TaxClass xsi:type="xsd:string"></TaxClass>
<User xsi:type="xsd:string">(Auto)</User>
<URL xsi:type="xsd:string"></URL>
</item>
</Customers>
<CustomersMatched xsi:type="xsd:integer">1</CustomersMatched>
<CustomersReturned xsi:type="xsd:integer">1</CustomersReturned>
<Limit xsi:type="xsd:integer">1000</Limit>
<StartIndex xsi:type="xsd:integer">0</StartIndex>
</searchCustomersReturn>
</ns1:searchCustomersResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
This method allows you to search the customer database using flexible search terms. This method searches the customer database (aka recurring billing) not the transactions history. To search the transaction history for a specific customer, use either the searchTransactions or getCustomerHistory method.
Use as many or as few search terms as you like. With MatchAll set to "true," all terms must match to return a result. If the search does not yield the desired results, try broadening your search by eliminating terms, or change MatchAll to "false."
Valid field names for search and sort are:
| BillingAddress.FirstName | Modified | Amount |
| BillingAddress.lastname | CustNum | Tax |
| BillingAddress.Company | CustomerID | Enabled |
| BillingAddress.Street | Created | Failures |
| BillingAddress.Street2 | Description | Start |
| BillingAddress.City | Notes | Next |
| BillingAddress.State | OrderID | NumLeft |
| BillingAddress.Zip | Source | Schedule |
| BillingAddress.Country | User | SendReceipt |
| BillingAddress.Phone | CustomFields | ReceiptNote |
| BillingAddress.Fax | ||
| BillingAddress.Email |
Related Methods
Syntax
CustomerSearchResult searchCustomers ( ueSecurityToken Token, SearchParam Search, boolean MatchAll, integer Start, integer Limit, string Sort)
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| %SearchParam% | array | Array of search parameters. |
| MatchAll | boolean | If set to "true," only results matching all search criteria will be returned, if set to "false," results matching any of the search criteria will be returned. |
| Start | integer | Record number to start returning from (ie if 1,000 were found and you only want to receive the last 200 you would set Start=800 and Limit=200) |
| Limit | integer | Maximum number of records to return in result set. |
| Sort | string | Comma separated list of fields to sort by. |
Return Value
| Name | Type | Description |
|---|---|---|
| %CustomerSearchResult% | object | Returns results of customer search based on parameters set. Customers will only show up to 1000 payment methods per customer. |
searchCustomerID
Example Request
<?php
try {
$CustID = "21021";
$CustNum = $client->searchCustomerID(token, $CustID);
$this->assertEquals($CustNum, "1222");
}
catch(SoapFault $e) {
die("soap fault: " .$e->getMessage());
}
?>
Dim custID As String
custID = "123456"
Dim response As String
response = client.searchCustomerID(token, custID)
MsgBox(response)
string custID = "123456";
string response;
try
{
response = client.searchCustomerID(token, custID);
MessageBox.Show(string.Concat("CustNum: ",response));
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
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:searchCustomerID>
<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">41e7d8ace19560b582699e53ac83b784c5fe911c</HashValue>
<Seed xsi:type="xsd:string">11039155194-test</Seed>
<Type xsi:type="xsd:string">sha1</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
</Token>
<CustID xsi:type="xsd:string">1861505359</CustID>
</ns1:searchCustomerID>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example Response
<?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
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:searchCustomerIDResponse>
<searchCustomerIDReturn xsi:type="xsd:string">4606609</searchCustomerIDReturn>
</ns1:searchCustomerIDResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
This method allows you to use the CustID - a customer identification number assigned by the merchant at the time the customer account is created - to find the gateway assigned CustNum associated with the customer's stored data.
The CustNum is required for several customer data storage management methods, including addCustomerPaymentMethod, updateCustomer, and deleteCustomer.
Related Methods
- runCustomerTransaction
- enableCustomer
- disablecustomer
- deleteCustomer
- getCustomer
- searchCustomers
- getCustomerHistory
- addCustomer
- addCustomerPaymentMethod
- deleteCustomerPaymentMethod
- updateCustomer
- quickUpdateCustomer
Syntax
string searchCustomerID ( ueSecurityToken Token, string CustID )
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| CustID | string | Merchant assigned Customer ID. |
Return Value
| Name | Type | Description |
|---|---|---|
| CustNum | string | Returns gateway assigned Customer Number. |
searchCustomersCount
Example Request
<?php
try {
$search=array(
array(
'Field'=>'amount',
'Type'=>'gt',
'Value'=>'8.00'),
array(
'Field'=>'failures',
'Type'=>'gt',
'Value'=>'0')
);
$start=0;
$limit=10;
$matchall=true;
$RefNum=1009411;
$Sort = "fname";
$res=$client->searchCustomersCount($token,$search,$matchall,$start,$limit,$Sort);
print_r($res);
}
catch (SoapFault $e) {
die("Search Customers failed :" .$e->getMessage());
}
?>
Dim matchAll As Boolean
matchAll = True
Dim search(0) As usaepay.SearchParam
search(0) = New usaepay.SearchParam()
search(0).Field = "Created"
search(0).Type = "Contains"
search(0).Value = "2010-09-09"
Dim response As usaepay.CustomerSearchResult = New usaepay.CustomerSearchResult
response = client.searchCustomersCount(token, search, matchAll, "0", "10", "fname")
MsgBox(response.CustomersMatched)
Boolean matchAll;
matchAll = true;
string[] fields = new string[3];
usaepay.SearchParam[] search = new usaepay.SearchParam[2];
search[0] = new usaepay.SearchParam();
search[0].Field = "Created";
search[0].Type = "Contains";
search[0].Value = "2010-08-10";
usaepay.CustomerSearchResult response = new usaepay.CustomerSearchResult();
try
{
response = client.searchCustomersCount(token, search, matchAll, "0", "10", "fname");
MessageBox.Show(response.CustomersMatched);
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
Identical to the searchCustomers method except only the customer counts are returned. Like searchCustomers, this method returns CustomerSearchResult. The only difference is that CustomerSearchResult.Customers is left empty. This method provides a quicker way to determine the size of the result set before starting to retrieve the full search results.
Related Methods
Syntax
CustomerSearchResult searchCustomersCount ( ueSecurityToken Token, SearchParam Search, boolean MatchAll, integer Start, integer Limit, string Sort)
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| %SearchParam% | array | Array of search parameters. |
| MatchAll | boolean | If set to "true," only results matching all search criteria will be returned, if set to "false," results matching any of the search criteria will be returned. |
| Start | integer | Record number to start returning from (ie if 1,000 were found and you only want to receive the last 200 you would set Start=800 and Limit=200) |
| Limit | integer | Maximum number of records to return in result set. |
| Sort | string | Comma separated list of fields to sort by. |
Return Value
| Name | Type | Description |
|---|---|---|
| %CustomerSearchResult% | object | Returns results of customer search based on parameters set. |
Change Log
| Version | Description |
|---|---|
| 1.2 | Method added in soap 1.2 release |
searchCustomersCustom
Example Request
<?php
try {
$search=array(
array('Field'=>'amount', 'Type'=>'gt','Value'=>'8.00'),
array('Field'=>'customerid', 'Type'=>'gt', 'Value'=>'0')
);
$start=0;
$limit=10;
$matchall=true;
$fieldList = array('CustNum', 'BillingAddress.Company', 'Amount', 'Next');
$format='csv';
$Sort='fname';
$res=$this->client->searchCustomersCustom($this->token,$search,$matchall,$start,$limit,$fieldList,$format,$Sort);
$res=base64_decode($res);
print_r($res);
}
catch (SoapFault $e) {
die("Search Customers failed :" .$e->getMessage());
}
?>
Dim matchAll As Boolean
matchAll = True
Dim search(0 To 1) As usaepay.SearchParam
search(0) = New usaepay.SearchParam()
search(0).Field = "Created"
search(0).Type = "Contains"
search(0).Value = "2010-09-09"
Dim FieldList(0 To 2) As String
FieldList(0) = "CustNum"
FieldList(1) = "BillingAddress.Company"
FieldList(2) = "Amount"
Dim result As String
result = client.searchCustomersCustom(token, search, matchAll, "0", "10", FieldList, "csv", "fname")
Dim binaryData() As Byte
binaryData = Convert.FromBase64String(result)
MsgBox(Encoding.UTF8.GetString(binaryData))
Boolean matchAll = true;
usaepay.SearchParam[] search = new usaepay.SearchParam[2];
search[0] = new usaepay.SearchParam();
search[0].Field = "Created";
search[0].Type = "Contains";
search[0].Value = "2010-08-10";
string[] FieldList = new string[3];
FieldList[0] = "CustNum";
FieldList[1] = "BillingAddress.Company";
FieldList[2] = "Amount";
string result;
try
{
result = client.searchCustomersCustom(token, search, matchAll, "0", "10", FieldList, "csv", "fname");
Byte[] binaryData = new Byte[3];
binaryData = Convert.FromBase64String(result);
MessageBox.Show(Encoding.UTF8.GetString(binaryData));
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay" 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:searchCustomersCustom>
<Token xsi:type="ns1:ueSecurityToken">
<ClientIP xsi:type="xsd:string">192.168.0.1</ClientIP>
<PinHash xsi:type="ns1:ueHash">
<HashValue xsi:type="xsd:string">6e62ffd4cbf1aaa659912f4444122e0b66ed2bd4</HashValue>
<Seed xsi:type="xsd:string">12966001102012554704</Seed>
<Type xsi:type="xsd:string">sha1</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">(Your Source Key Here)</SourceKey>
</Token>
<Search SOAP-ENC:arrayType="ns1:SearchParam[2]" xsi:type="ns1:SearchParamArray">
<item xsi:type="ns1:SearchParam">
<Field xsi:type="xsd:string">amount</Field>
<Type xsi:type="xsd:string">gt</Type>
<Value xsi:type="xsd:string">8.00</Value>
</item>
<item xsi:type="ns1:SearchParam">
<Field xsi:type="xsd:string">customerid</Field>
<Type xsi:type="xsd:string">gt</Type>
<Value xsi:type="xsd:string">0</Value>
</item>
</Search>
<MatchAll xsi:type="xsd:boolean">true</MatchAll>
<Start xsi:type="xsd:integer">0</Start>
<Limit xsi:type="xsd:integer">10</Limit>
<FieldList SOAP-ENC:arrayType="xsd:string[5]" xsi:type="ns1:stringArray">
<item xsi:type="xsd:string">CustNum</item>
<item xsi:type="xsd:string">BillingAddress.Company</item>
<item xsi:type="xsd:string">Amount</item>
<item xsi:type="xsd:string">Next</item>
<item xsi:type="xsd:string">CustomData</item>
</FieldList>
<Format xsi:type="xsd:string">csv</Format>
<Sort xsi:nil="true"/></ns1:searchCustomersCustom>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
This method allows you to search the customer database using flexible search terms. This method searches the customer database (aka recurring billing) not the transactions history. To search the transaction history for a specific customer, use either the searchTransactions or getCustomerHistory method.
Use as many or as few search terms as you like. With MatchAll set to "true," all terms must match to return a result. If the search does not yield the desired results, try broadening your search by eliminating terms, or change MatchAll to "false."
Valid field names for search, sort and return are:
| BillingAddress.FirstName | Modified | Amount |
| BillingAddress.lastname | CustNum | Tax |
| BillingAddress.Company | CustomerID | Enabled |
| BillingAddress.Street | Created | Failures |
| BillingAddress.Street2 | Description | Start |
| BillingAddress.City | Notes | Next |
| BillingAddress.State | OrderID | NumLeft |
| BillingAddress.Zip | Source | Schedule |
| BillingAddress.Country | User | SendReceipt |
| BillingAddress.Phone | CustomFields | ReceiptNote |
| BillingAddress.Fax | ||
| BillingAddress.Email |
Related Methods
Syntax
string searchCustomersCustom ( ueSecurityToken Token, SearchParam Search, boolean MatchAll, integer Start, integer Limit, string FieldList, string Format, string Sort)
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| %SearchParam% | array | Array of search parameters. |
| MatchAll | boolean | If set to "true," only results matching all search criteria will be returned, if set to "false," results matching any of the search criteria will be returned. |
| Start | integer | Record number to start returning from (ie if 1,000 were found and you only want to receive the last 200 you would set Start=800 and Limit=200) |
| Limit | integer | Maximum number of records to return in result set. |
| Sort | string | Comma separated list of fields to sort by. |
| FieldList | list | List of fields to return in search. |
| Format | string | Specify format of return data. Possible formats include: csv, tab, xml, php, json. |
Return Value
| Name | Type | Description |
|---|---|---|
| searchCustomersCustomReturn | string | Base64 encode result set. Returns all of the fields from any customers matching your search parameters. Customers will only show up to 1000 payment methods per customer. |
Change Log
| Version | Description |
|---|---|
| 1.2 | Added Sort Parameter |
| 1.1 | Soap 1.1 Release |
| 1.0 | Method added in soap v1.0 |
getCustomerHistory
Example Request
<?php
try {
$custnum='547';
print_r($client->getCustomerHistory($token,$custnum));
}
catch(SoapFault $e) {
echo $e->getMessage();
}
echo "\n\nRequest: " . $client->__getLastRequest();
echo "\n\nResponse: " . $client->__getLastResponse();
?>
try {
//Set CustNum to the Customer Number of customer you
//want to retrieve a transaction history from.
BigInteger CustNum = new BigInteger;
TransactionSearchResult CustHist = new TransactionSearchResult();
CustHist = client.getCustomerHistory(token, CustNum);
} catch (Exception e) {
System.out.println("Soap Exception: " + e.getMessage());
}
Dim CustNum As String
CustNum = "103125"
Dim tran As usaepay.TransactionSearchResult
tran = New usaepay.TransactionSearchResult
tran = client.getCustomerHistory(token, CustNum)
MsgBox(tran.SalesCount)
string CustNum = "89147";
usaepay.TransactionSearchResult tran = new usaepay.TransactionSearchResult();
try
{
tran = client.getCustomerHistory(token, CustNum);
MessageBox.Show(string.Concat(tran.SalesCount));
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
This method allows you to view all of the transactions completed for a particular customer.
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.
Related Methods
- runCustomerTransaction
- enableCustomer
- disableCustomer
- deleteCustomer
- searchCustomerID
- getCustomer
- searchCustomers
- addCustomer
- addCustomerPaymentMethod
- deleteCustomerPaymentMethod
- updateCustomer
- quickUpdateCustomer
Syntax
TransactionSearchResult getCustomerHistory ( ueSecurityToken Token, string CustNum )
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| CustNum | string | A unique customer number assigned by the gateway |
| Start | integer | Record number to start returning from (ie if 1,000 were found and you only want to receive the last 200 you would set Start=800 and Limit=200) |
| Limit | integer | Maximum number of records to return in result set. Largest Limit allowed is 1000. |
Response Parameters
| Type | Description |
|---|---|
| %TransactionSearchResult% | Returns the results of the customer transaction history search. |
Change Log
| Version | Description |
|---|---|
| 1.6 | Added start and limit parameters |
| 1.7 | Changed CustNum to type string |
Customer Transactions
convertTranToCust
Example Request
<?php
try {
// Set RefNum to the Reffernce Num of the
//transaction you want to convert to a customer
$RefNum="123456789";
// Creating customer, saving exact time and verifying customer was created.
$RecurringBillData = array(
array('Field'=>'NumLeft', 'Value'=>'10'),
array('Field'=>'Amount', 'Value'=>'7.40'),
array('Field'=>'Description', 'Value'=>'Monthly Bill'),
array('Field'=>'Schedule', 'Value'=>'Monthly'),
array('Field'=>'Enabled', 'Value'=>'Yes'),
);
$custnum = $client->convertTranToCust($token, $RefNum, $RecurringBillData);
} catch(Exception $e) {
echo 'Error: ' . $e->getMessage();
}
?>
try {
//Transaction Reffernce Number to convert to a customer
BigInteger RefNum = new BigInteger('123456');
//Setting up the Field Value array for updated data specific to the customer
FieldValueArray UpdateData = new FieldValueArray();
UpdateData.add(new FieldValue("Schedule", "weekly"));
UpdateData.add(new FieldValue("NumLeft", "7"));
//Converting to a customer
BigInteger CustNum = client.convertTranToCust(token, RefNum,UpdateData);
} catch (Exception e) {
System.out.println("Soap Exception: " + e.getMessage());
}
Dim refnum As String
refnum = "46978031"
Dim update(0 To 1) As usaepay.FieldValue
For i As Integer = 0 To 1
update(i) = New usaepay.FieldValue
Next
update(0).Field = "Schedule"
update(0).Value = "weekly"
update(1).Field = "NumLeft"
update(1).Value = "7"
Dim response As String
response = client.convertTranToCust(token, refnum, update)
MsgBox(response)
string refnum = "46978031";
usaepay.FieldValue[] update = new usaepay.FieldValue[2];
for (int i = 0; i < 2; i++) {
update[i] = new usaepay.FieldValue();
}
update[0].Field = "Schedule"; update[0].Value = "weekly";
update[1].Field = "NumLeft"; update[1].Value = "7";
string response;
try
{
response = client.convertTranToCust(token, refnum, update);
MessageBox.Show(string.Concat("Customer Number: ",
response));
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
This method copies the credit card/check data, card holder name and address information from an existing transaction and uses it to create a new customer record to be stored in the Customer Database. By default, the customer will be created with recurring billing disabled.
The method returns the new CustNum (customer number). Optional customer fields can be created using the UpdateData parameter. See the (#quickupdatecustomer) method for details on what fields may be set.
Only information entered in the original transaction will be saved. To input additional data, use the (#updatecustomer) or (#quickupdatecustomer) methods. (#updatecustomer) will replace all existing customer data, while (#quickupdatecustomer) allows you to update selected fields only.
Possible fields are:
| CustomerID | Amount |
| FirstName | Enabled |
| LastName | Next |
| Company | NumLeft |
| Address | Schedule |
| Address2 | SendReceipt |
| City | ReceiptNote |
| State | Card Number |
| Zip | Card Expiration |
| Country | Account Number |
| Phone | Routing Number |
| Fax | Description |
| Notes | |
| URL | OrderID |
| CustomData | Source |
| User |
Syntax
string convertTranToCust ( ueSecurityToken Token, string RefNum, FieldValue UpdateData )
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| Update | array | Array of FieldValue objects you would like to update. |
| RefNum | string | Unique transaction reference number assigned by the gateway. You can also use TransKey in the RefNum field. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| CustNum | string | Returns the gateway generated CustNum of the new customer. |
Change Log
| Version | Description |
|---|---|
| 1.7 | TransKey can be used in RefNum field. |
| 1.0 | Method added in soap v1.0 |
runCustomerTransaction
Example Request
<?php
try {
$Parameters=array(
'Command'=>'Sale',
'Details'=>array(
'Invoice' => rand(),
'PONum' => '',
'OrderID' => '',
'Description' => 'Sample Credit Card Sale',
'Amount'=>'1.50' )
);
$CustNum='123456';
$PayMethod='0';
$res=$client->runCustomerTransaction($token, $CustNum, $PayMethod, $Parameters);
print_r($res);
}
catch (SoapFault $e) {
echo $client->__getLastRequest();
echo $client->__getLastResponse();
die("runCustomerTransaction failed :" .$e->getMessage());
}
?>
Dim custnum As String
custnum = "103125"
Dim paymentMethodID As String
paymentMethodID = "39"
Dim tran As usaepay.CustomerTransactionRequest = New usaepay.CustomerTransactionRequest
tran.Details = New usaepay.TransactionDetail
tran.Details.Invoice = "123456"
tran.Details.Description = "Sample Credit Card Sale"
tran.Details.Amount = 1.05
tran.Details.AmountSpecified = True
Dim response As usaepay.TransactionResponse
response = New usaepay.TransactionResponse
response = client.runCustomerTransaction(token, custnum, paymentMethodID, tran)
MessageBox.Show(String.Concat(response.Result))
string custNum = "89147";
string paymentMethodID = "19";
usaepay.CustomerTransactionRequest tran = new usaepay.CustomerTransactionRequest();
tran.Details = new usaepay.TransactionDetail();
tran.Details.Invoice = "123456";
tran.Details.Description = "Sample Credit Card Sale";
tran.Details.Amount = 1.05;
tran.Details.AmountSpecified = true;
usaepay.TransactionResponse response = new usaepay.TransactionResponse();
try
{
response = client.runCustomerTransaction(token, custNum, paymentMethodID, tran);
MessageBox.Show(string.Concat(response.Result));
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
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:runCustomerTransaction>
<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">28294c0d68cd498353c6f6dad03e00a1ac8668e1</HashValue>
<Seed xsi:type="xsd:string">11688496410-test</Seed>
<Type xsi:type="xsd:string">sha1</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
</Token>
<CustNum xsi:type="xsd:string">4600666</CustNum>
<PaymentMethodID xsi:type="xsd:string">0</PaymentMethodID>
<Parameters xsi:type="ns1:CustomerTransactionRequest">
<Command xsi:type="xsd:string">Sale</Command>
<Details xsi:type="ns1:TransactionDetail">
<Amount xsi:type="xsd:double">10.5</Amount>
<Description xsi:type="xsd:string">Sample Credit Card Sale</Description>
<Invoice xsi:type="xsd:string">327061455</Invoice>
<OrderID xsi:type="xsd:string"></OrderID>
<PONum xsi:type="xsd:string"></PONum>
</Details>
</Parameters>
</ns1:runCustomerTransaction>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example Response
<?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
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:runCustomerTransactionResponse>
<runCustomerTransactionReturn xsi:type="ns1:TransactionResponse">
<AcsUrl xsi:type="xsd:string"></AcsUrl>
<AuthAmount xsi:type="xsd:double">10.5</AuthAmount>
<AuthCode xsi:type="xsd:string">144519</AuthCode>
<AvsResult xsi:type="xsd:string">Address: Match & 5 Digit Zip: Match</AvsResult>
<AvsResultCode xsi:type="xsd:string">YYY</AvsResultCode>
<BatchNum xsi:type="xsd:string">211</BatchNum>
<BatchRefNum xsi:type="xsd:string">198907</BatchRefNum>
<CardCodeResult xsi:type="xsd:string">Not Processed</CardCodeResult>
<CardCodeResultCode xsi:type="xsd:string">P</CardCodeResultCode>
<CardLevelResult xsi:nil="true" />
<CardLevelResultCode xsi:nil="true" />
<ConversionRate xsi:type="xsd:double">0</ConversionRate>
<ConvertedAmount xsi:type="xsd:double">0</ConvertedAmount>
<ConvertedAmountCurrency xsi:type="xsd:string">0</ConvertedAmountCurrency>
<CustNum xsi:type="xsd:string">4600666</CustNum>
<Error xsi:type="xsd:string">Approved</Error>
<ErrorCode xsi:type="xsd:integer">0</ErrorCode>
<isDuplicate xsi:type="xsd:boolean">false</isDuplicate>
<Payload xsi:type="xsd:string"></Payload>
<RefNum xsi:type="xsd:string">102506029</RefNum>
<Result xsi:type="xsd:string">Approved</Result>
<ResultCode xsi:type="xsd:string">A</ResultCode>
<Status xsi:type="xsd:string">Pending</Status>
<StatusCode xsi:type="xsd:string">P</StatusCode>
<VpasResultCode xsi:type="xsd:string"></VpasResultCode>
</runCustomerTransactionReturn>
</ns1:runCustomerTransactionResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Processes a new transaction using the payment details stored for the customer. This is a one time charge and does not use or affect the recurring billing values, such as amount and description, that have been stored for the customer. The transaction result will be tied to the customer and will be visible in the customer's billing history. The customer does not need to have recurring billing enabled for this method to be used. If you do not have a cardholder listed as part of the payment method, the customer's first and last name in their customer profile will be used as the cardholder.
Related Methods
Syntax
TransactionResponse runCustomerTransaction ( ueSecurityToken Token, string CustNum, string PaymentMethodID )
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| CustNum | string | System assigned CustNum of stored customer record. |
| PaymentMethodID | string | System assigned id of stored customer payment method. |
| %CustomerTransactionRequest% | object | Transaction amount, invoice number, etc. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| %TransactionResponse% | object | Returns a TransactionResponse object containing the results of the transaction and all relevant data. |
Change Log
| Version | Description |
|---|---|
| 1.7 | Changed CustNum and PaymentMethodID to type string |
Product Methods
Products
addProduct
Example Request
<?php
try {
$Product = array(
"ProductID" => "0-13-508011-8",
"SKU" =>"135080118",
"UPC" => "9780135080115",
"Category" => "Books:Math",
"Enabled" => true,
"Name" => "Elementary Differential Equations",
"Description" => "Rainville, Bedient and Bedient (Eight Edition)",
"Weight" => 1.0,
"ShipWeight" => 1.1,
"Price" => 112.00,
"ListPrice" => 128.00,
"WholesalePrice"=> 100.00,
"DateAvailable" => "2009-12-01",
"Manufacturer" => "Prentice Hall",
"Type" => "Unknown",
"MinQuantity" =>0,
"ImageURL" => "http://acme.com/prodimg/123123.jpg",
"URL" => "http:/acme.com/prod/123123.html"
);
$ProductRefNum = $client->addProduct($token, $Product);
print_r($res);
}
catch(SoapFault $e) {
echo $e->getMessage();
}
?>
Dim product As usaepay.Product = New usaepay.Product
product.ProductID = "0-13-508011-8"
product.SKU = "135080118"
product.UPC = "9780135080115"
product.Category = "Books:Math"
Dim inventory(0 To 1) As usaepay.ProductInventory
inventory(0) = New usaepay.ProductInventory()
inventory(0).InventoryLocation = "Los angeles"
inventory(0).QtyOnHand = "10"
inventory(0).QtyOnOrder = "5"
inventory(0).DateAvailable = "2010-08-20"
product.Inventory = inventory
Dim priceTier(0 To 1) As usaepay.PriceTier
priceTier(0) = New usaepay.PriceTier()
priceTier(0).Qty = "2"
priceTier(0).Price = "100"
product.PriceTiers = priceTier
product.TaxClass = "your_tax_class"
product.Enabled = True
product.Name = "Elementary Differential Equations"
product.Description = "Rainville, Bedient and Bedient (Eight Edition)"
product.Weight = 1.0
product.ShipWeight = 1.1
product.Price = 112.0
product.ListPrice = 128.0
product.WholesalePrice = 100.0
product.DateAvailable = "2010-08-01"
product.Manufacturer = "Prentice Hail"
product.MinQuantity = "0"
Dim refNum As String
refNum = client.addProduct(token, product)
MsgBox(refNum)
usaepay.Product product = new usaepay.Product();
product.ProductID = "0-13-508011-8";
product.SKU = "135080118";
product.UPC = "9780135080115";
product.Category = "Books:Math";
usaepay.ProductInventory[] inventory = new usaepay.ProductInventory[1];
inventory[0] = new usaepay.ProductInventory();
inventory[0].InventoryLocation = "Los angeles";
inventory[0].QtyOnHand = "10";
inventory[0].QtyOnOrder = "5";
inventory[0].DateAvailable = "2010-08-20";
product.Inventory = inventory;
usaepay.PriceTier[] priceTier = new usaepay.PriceTier[1];
priceTier[0] = new usaepay.PriceTier();
priceTier[0].Qty = "2";
priceTier[0].Price = "100";
product.PriceTiers = priceTier;
product.TaxClass = "your_tax_class";
product.Enabled = true;
product.Name = "Elementary Differential Equations";
product.Description = "Rainville, Bedient and Bedient (Eight Edition)";
product.Weight = 1.0;
product.ShipWeight = 1.1;
product.Price = 112.00;
product.ListPrice = 128.00;
product.WholesalePrice = 100.00;
product.DateAvailable = "2010-08-01";
product.Manufacturer = "Prentice Hail";
product.MinQuantity = "0";
string refNum;
try
{
refNum = client.addProduct(token, product);
MessageBox.Show(string.Concat(refNum));
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay" 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:addProduct>
<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">6336749834eabc43b70de5bc20fe037b6517b8d4</HashValue>
<Seed xsi:type="xsd:string">1667362908-test</Seed>
<Type xsi:type="xsd:string">sha1</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
</Token>
<Product xsi:type="ns1:Product">
<ProductID xsi:type="xsd:string">2345678</ProductID>
<SKU xsi:type="xsd:string">909090</SKU>
<UPC xsi:type="xsd:string">789789</UPC>
<Category xsi:type="xsd:string">liqour</Category>
<Enabled xsi:type="xsd:boolean">true</Enabled>
<Name xsi:type="xsd:string">sailor jerry</Name>
<Description xsi:type="xsd:string">spice rum bottle</Description>
<Model xsi:type="xsd:string">bottle</Model>
<Weight xsi:type="xsd:double">7.7</Weight>
<ShipWeight xsi:type="xsd:double">11.7</ShipWeight>
<Price xsi:type="xsd:double">40</Price>
<WholesalePrice xsi:type="xsd:double">60</WholesalePrice>
<ListPrice xsi:type="xsd:double">20</ListPrice>
<Manufacturer xsi:type="xsd:string">Chase</Manufacturer>
<PhysicalGood xsi:type="xsd:boolean">true</PhysicalGood>
<MinQuantity xsi:type="xsd:integer">18</MinQuantity>
<ImageURL xsi:type="xsd:string">www.candyland.com</ImageURL>
<URL xsi:type="xsd:string">www.candyland.com</URL>
<Inventory SOAP-ENC:arrayType="ns1:ProductInventory[1]" xsi:type="ns1:ProductInventoryArray">
<item xsi:type="ns1:ProductInventory">
<InventoryLocation xsi:type="xsd:string">compton</InventoryLocation>
<QtyOnHand xsi:type="xsd:string">30</QtyOnHand>
<QtyOnOrder xsi:type="xsd:string">10</QtyOnOrder>
<DateAvailable xsi:type="xsd:string">461</DateAvailable>
</item>
</Inventory>
<PriceTiers SOAP-ENC:arrayType="ns1:PriceTier[2]" xsi:type="ns1:PriceTierArray">
<item xsi:type="ns1:PriceTier">
<Qty xsi:type="xsd:string">10</Qty>
<Price xsi:type="xsd:string">25</Price>
</item>
<item xsi:type="ns1:PriceTier">
<Qty xsi:type="xsd:string">20</Qty>
<Price xsi:type="xsd:string">15</Price>
</item>
</PriceTiers>
</Product>
</ns1:addProduct>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example Response
<?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
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:addProductResponse>
<ProductRefNum xsi:type="xsd:string">9001001937</ProductRefNum>
</ns1:addProductResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
This method creates a new product record and returns a ProductRefNum
The addProduct method creates a new product record. If successful, a ProductRefNum will be returned. The ProductRefNum is a gateway assigned product identifier. This product identifier should be stored and is needed for updating and deleting products. The product database is an optional feature and may not be supported by all merchants. The merchant should check their gateway package to determine if this feature is available to them.
Related Methods
Syntax
string addProduct ( ueSecurityToken Token, Product )
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| %Product% | object | Object contain product details |
Response Parameters
| Name | Type | Description |
|---|---|---|
| ProductRefNum | string | Unique gateway generated product id. |
Exceptions
| Code | Message | Advice |
|---|---|---|
| 41001 | Unable to create product database | Merchant does not have a product database. The feature not be enabled for merchant. Contact customer service and make sure product database feature is enabled. |
deleteProduct
Example Request
<?php
try {
$ProductRefNum='919932077432';
$client->deleteProduct($token, $ProductRefNum);
}
catch(SoapFault $e) {
echo $e->getMessage();
}
?>
Dim refNum As String
refNum = "9001169810"
Dim response As Boolean
response = client.deleteProduct(token, refNum)
MsgBox(response)
string RefNum = "900116982";
Boolean response;
try
{
response = client.deleteProduct(token, RefNum);
MessageBox.Show(string.Concat(response));
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
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:deleteProduct>
<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">31fdc81f0d453b90e6896ae62062369a33fade08</HashValue>
<Seed xsi:type="xsd:string">11821282856-test</Seed>
<Type xsi:type="xsd:string">sha1</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
</Token>
<ProductRefNum xsi:type="xsd:string">9001001973</ProductRefNum>
</ns1:deleteProduct>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example Response
<?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
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:deleteProductResponse>
<deleteProductReturn xsi:type="xsd:boolean">true</deleteProductReturn>
</ns1:deleteProductResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
This method deletes an existing product.
This method removes the specified ProductRefNum from the product database. The product is deleted immediately and this operation can not be undone. The ProductRefNum is the gateway assigned product ID that was returned by addProduct. searchProducts can be used to find the ProductRefNum for a product if it is not known.
Related Methods
Syntax
boolean deleteProduct ( ueSecurityToken Token, ProductRefNum )
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| ProductRefNum | string | Product reference number used to delete a product |
Response Parameters
| Name | Type | Description |
|---|---|---|
| deleteProductReturn | boolean | Returns true if product has been deleted (on error an exception is thrown). |
Exceptions
| Code | Message | Advice |
|---|---|---|
| 41002 | Product Not Found | Product specified by ProductRefNum was not found. Make sure the number stored is not truncated or rounded. |
| 41005 | Failed to delete product | A database fault was encountered while deleting product record. Try operation again or contact support. |
updateProduct
Example Request
<?php
try {
$Product = array(
"ProductID" => "0-13-508011-8",
"SKU" =>"135080118",
"UPC" => "9780135080115",
"Category" => "Books:Math",
"Enabled" => true,
"Name" => "Elementary Differential Equations",
"Description" => "Rainville, Bedient and Bedient (Eight Edition)",
"Weight" => 1.0,
"ShipWeight" => 1.1,
"Price" => 112.00,
"ListPrice" => 128.00,
"WholesalePrice"=> 100.00,
"DateAvailable" => "2009-12-01",
"Manufacturer" => "Prentice Hall",
"Type" => "Unknown",
"MinQuantity" =>0,
"MaxQuantity" =>10,
"ImageURL" => "http://acme.com/prodimg/123123.jpg",
"URL" => "http:/acme.com/prod/123123.html"
);
$client->updateProduct($token, $ProductRefNum, $Product);
}
catch(SoapFault $e) {
echo $e->getMessage();
}
?>
Dim RefNum As String
RefNum = "9001169810"
Dim product As usaepay.Product = New usaepay.Product()
product.ProductID = "0-13-508011-8"
product.SKU = "135080118"
product.UPC = "9780135080115"
product.Category = "Books:Science"
product.Enabled = True
product.Name = "Non-Elementary Differential Equations"
product.Description = "Rainville, Bedient and Bedient (Eight Edition)"
product.Weight = 1.0
product.ShipWeight = 1.1
product.Price = 112.0
product.ListPrice = 128.0
product.WholesalePrice = 100.0
product.DateAvailable = "2010-08-01"
product.Manufacturer = "Prentice Hail"
product.MinQuantity = "0"
Dim response As Boolean
response = client.updateProduct(token, RefNum, product)
MsgBox(response)
string RefNum = "900116982";
usaepay.Product product = new usaepay.Product();
product.ProductID = "0-13-508011-8";
product.SKU = "135080118";
product.UPC = "9780135080115";
product.Category = "Books:Science";
product.Enabled = true;
product.Name = "Elementary Differential Equations";
product.Description = "Rainville, Bedient and Bedient (Eight Edition)";
product.Weight = 1.0;
product.ShipWeight = 1.1;
product.Price = 112.00;
product.ListPrice = 128.00;
product.WholesalePrice = 100.00;
product.DateAvailable = "2010-08-01";
product.Manufacturer = "Prentice Hail";
product.MinQuantity = "0";
Boolean response;
try
{
response = client.updateProduct(token, RefNum, product);
MessageBox.Show(string.Concat(response));
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
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:updateProduct>
<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">a6a24337700a018bb569202fefb5e034414f2adf</HashValue>
<Seed xsi:type="xsd:string">11288967116-test</Seed>
<Type xsi:type="xsd:string">sha1</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
</Token>
<ProductRefNum xsi:type="xsd:string">9001001967</ProductRefNum>
<Product xsi:type="ns1:Product">
<ProductID xsi:type="xsd:string">866872</ProductID>
<SKU xsi:type="xsd:string">111111111</SKU>
<UPC xsi:type="xsd:string">555555555</UPC>
<Category xsi:type="xsd:string">liqour</Category>
<Enabled xsi:type="xsd:boolean">true</Enabled>
<Name xsi:type="xsd:string">Big V</Name>
<Description xsi:type="xsd:string">vodka</Description>
<Model xsi:type="xsd:string">bottle</Model>
<Weight xsi:type="xsd:double">5.7</Weight>
<ShipWeight xsi:type="xsd:double">11.7</ShipWeight>
<Price xsi:type="xsd:double">40</Price>
<WholesalePrice xsi:type="xsd:double">60</WholesalePrice>
<ListPrice xsi:type="xsd:double">20</ListPrice>
<Manufacturer xsi:type="xsd:string">Chase</Manufacturer>
<PhysicalGood xsi:type="xsd:boolean">true</PhysicalGood>
<MinQuantity xsi:type="xsd:integer">80</MinQuantity>
<ImageURL xsi:type="xsd:string">www.lime.com</ImageURL>
<URL xsi:type="xsd:string">www.lime.com</URL>
<Created xsi:type="xsd:dateTime"/>
<Modified xsi:type="xsd:dateTime"/>
<PriceTiers SOAP-ENC:arrayType="ns1:PriceTier[1]" xsi:type="ns1:PriceTierArray">
<item xsi:type="ns1:PriceTier">
<Qty xsi:type="xsd:string">10</Qty>
<Price xsi:type="xsd:string">25</Price>
</item>
</PriceTiers>
</Product>
</ns1:updateProduct>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example Response
<?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
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:updateProductResponse>
<updateProductReturn xsi:type="xsd:boolean">true</updateProductReturn>
</ns1:updateProductResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
This method updates an existing product.
Updates an existing product based on its ProductRefNum. The entire product is replaced by the contents of the Product parameter. Developers can use the getProduct method to retrieve the Product object, modify a field and then post the object back to the server. If you only need to update one field, consider using the quickUpdateProduct method instead.
Related Methods
Syntax
boolean updateProduct ( ueSecurityToken, ProductRefNum, Product )
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| ProductRefNum | string | Unique gateway generated product id. |
| %Product% | object | Product data |
Response Parameters
| Name | Type | Description |
|---|---|---|
| updateProductReturn | boolean | Returns a true if the product is updated correctly. |
Exceptions
| Code | Message | Advice |
|---|---|---|
| 41002 | Product Not Found | Product specified by ProductRefNum was not found. Make sure the number stored is not truncated or rounded. |
| 41003 | Error saving product | A database fault was encountered while saving product record. Try operation again or contact support. |
quickUpdateProduct
Update product data in selected fields only.
This method allows you to update only specified data for a product record, rather than replacing all existing data.
This method requires the use of the ProductRefNum, a unique product number assigned by the gateway. If you have lost or cannot remember the products's ProductRefNum, use the searchProducts method to find the correct ProductRefNum.
This method uses the UpdateData array containing the fields that you would like to update. The "key" of each element is the name of the field you wish to change and the "value" of the element is the new value that you would like to assign.
The following fields may be updated using this method:
| Type | Name | Description |
|---|---|---|
| ProductID | string | Merchant assigned product ID |
| CategoryID | integer | Merchant assigned category ID. |
| SKU | string | Stock-Keeping Unit |
| UPC | string | Universal Product Code |
| Enabled | boolean | Enables the ability to store products |
| Name | string | Name of the product |
| Description | string | Product description |
| Model | string | Model of the product |
| Weight | double | Weight of the product |
| ShipWeight | double | Shipping weight of the product |
| Price | double | Price of the product |
| WholesalePrice | double | Wholesale price of the product |
| ListPrice | double | List price of the product |
| DateAvailable | string | Date the product is available for sale |
| Manufacturer | string | Maker of the product |
| PhysicalGood | boolean | Tangible/Shippable good |
| MinQuantity | integer | Minimum quantity allowed |
| MaxQuantity | integer | Maximum quantity allowed |
| ImageURL | string | URL address of the product image |
| URL | string | URL of the product |
Syntax
boolean quickUpdateProduct ( ueSecurityToken, string ProductRefNum, FieldValue UpdateData )
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| UpdateData | array | Array of FieldValue objects to be updated. |
| ProductRefNum | string | A unique product id assigned by the gateway. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| quickUpdateProductReturn | boolean | Returns confirmation of request only if successful. If request fails, an exception will be thrown |
getProduct
Example Request
<?php
try {
$ProductRefNum = '912093987473';
$product = $client->getProduct($token, $ProductRefNum);
print_r($product);
}
catch(SoapFault $e) {
echo $e->getMessage();
}
?>
Dim prod As usaepay.Product = New usaepay.Product
Dim refNum As String
refNum = "9001169811"
prod = client.getProduct(token, refNum)
MsgBox(prod.Name)
string RefNum = "900116985";
usaepay.Product response = new usaepay.Product();
try
{
response = client.getProduct(token, RefNum);
MessageBox.Show(string.Concat(response.Price));
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
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:getProduct>
<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">720104052fd3b583716a1b18021b4986fee3c482</HashValue>
<Seed xsi:type="xsd:string">11434035177-test</Seed>
<Type xsi:type="xsd:string">sha1</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
</Token>
<ProductRefNum xsi:type="xsd:string">9001001976</ProductRefNum>
</ns1:getProduct>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example Response
<?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
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:getProductResponse>
<getProductReturn xsi:type="ns1:Product">
<ProductRefNum xsi:type="xsd:string">9001001976</ProductRefNum>
<ProductID xsi:type="xsd:string">2345678</ProductID>
<SKU xsi:type="xsd:string">909090</SKU>
<UPC xsi:type="xsd:string">789789</UPC>
<Category xsi:type="xsd:string">liqour</Category>
<Enabled xsi:type="xsd:boolean">true</Enabled>
<Name xsi:type="xsd:string">sailor jerry</Name>
<Description xsi:type="xsd:string">spice rum bottle</Description>
<Model xsi:type="xsd:string">bottle</Model>
<Weight xsi:type="xsd:double">7.7</Weight>
<ShipWeight xsi:type="xsd:double">11.7</ShipWeight>
<Price xsi:type="xsd:double">40</Price>
<WholesalePrice xsi:type="xsd:double">60</WholesalePrice>
<ListPrice xsi:type="xsd:double">20</ListPrice>
<DateAvailable xsi:type="xsd:string">0000-00-00</DateAvailable>
<Manufacturer xsi:type="xsd:string">Chase</Manufacturer>
<PhysicalGood xsi:type="xsd:boolean">true</PhysicalGood>
<TaxClass xsi:type="xsd:string">None</TaxClass>
<MinQuantity xsi:type="xsd:integer">18</MinQuantity>
<ImageURL xsi:type="xsd:string">www.candyland.com</ImageURL>
<URL xsi:type="xsd:string">www.candyland.com</URL>
<Created xsi:type="xsd:dateTime">2015-12-17T14:54:28+08:00</Created>
<Modified xsi:type="xsd:dateTime">2015-12-17T14:54:28+08:00</Modified>
<Inventory SOAP-ENC:arrayType="ns1:ProductInventory[0]"
xsi:type="ns1:ProductInventoryArray" />
<PriceTiers SOAP-ENC:arrayType="ns1:PriceTier[1]" xsi:type="ns1:PriceTierArray">
<item xsi:type="ns1:PriceTier">
<Qty xsi:type="xsd:string">10</Qty>
<Price xsi:type="xsd:string">25</Price>
<CustomerTier xsi:type="xsd:string"></CustomerTier>
</item>
</PriceTiers>
</getProductReturn>
</ns1:getProductResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Retrieve all data for a single product.
This method retrieves the Product object for the product specified by ProductRefNum. The ProductRefNum is the gateway assigned unique product identifier that was returned by addProduct. searchProducts can be used to find the ProductRefNum for a product if it is not known.
The entire Product object is returned.
Related Methods
Syntax
Product getProduct ( ueSecurityToken Token, string, ProductRefNum )
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| ProductRefNum | string | Unique gateway generated product id. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| %Product% | object | Returns a Product object containing fields and their values. |
Exceptions
| Code | Message | Advice |
|---|---|---|
| 41002 | Product Not Found | Product specified by ProductRefNum was not found. Make sure the number stored is not truncated or rounded. |
Product Categories
addProductCategory
Example Request
Dim category As usaepay.ProductCategory = New usaepay.ProductCategory
category.Name = "The first"
Dim response As String
response = client.addProductCategory(token, category)
MsgBox(response)
usaepay.ProductCategory category = new usaepay.ProductCategory();
category.Name = "The first";
string response;
try
{
response = client.addProductCategory(token, category);
MessageBox.Show(string.Concat(response));
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
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:addProductCategory>
<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">e229fb6ce9c42bfc12c41f738dfc3984cb8a5461</HashValue>
<Seed xsi:type="xsd:string">1975389982-test</Seed>
<Type xsi:type="xsd:string">sha1</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
</Token>
<ProductCategory xsi:type="ns1:ProductCategory">
<Name xsi:type="xsd:string">IceCream</Name>
</ProductCategory>
</ns1:addProductCategory>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example Response
<?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
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:addProductCategoryResponse>
<ProductCategoryRefNum xsi:type="xsd:string">9001001925</ProductCategoryRefNum>
</ns1:addProductCategoryResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
This method creates a new product category record and returns a ProductCategoryRefNum
The addProductCategory method creates a new product category record. If successful, a ProductCategoryRefNum will be returned. The ProductCategoryRefNum is a gateway assigned product category identifier. This product category identifier should be stored and is needed for updating and deleting product categories. The product database is an optional feature and may not be supported by all merchants. The merchant should check their gateway package to determine if this feature is available to them.
Related Methods
Syntax
string addProductCategory ( ueSecurityToken , ProductCategory )
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| Name | string | Product Category name. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| ProductCategoryRefNum | string | Unique gateway generated product category id. |
Exceptions
| Code | Message | Advice |
|---|---|---|
| 41001 | Unable to create product database | Merchant does not have a product database. The feature not be enabled for merchant. Contact customer service and make sure product database feature is enabled. |
deleteProductCategory
Example Request
Dim catRefNum As String
catRefNum = "9001169811"
Dim response As Boolean
response = client.deleteProductCategory(token, catRefNum)
MsgBox(response)
string catRefNum = "900116983";
Boolean response;
try
{
response = client.deleteProductCategory(token, catRefNum);
MessageBox.Show(string.Concat(response));
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
This method deletes an existing product category.
This method removes the specified ProductCategoryRefNum from the product database. The product category is deleted immediately and this operation can not be undone. The ProductCategoryRefNum is the gateway assigned product Category ID that was returned by addProductCategory.
Related Methods
Syntax
boolean deleteProductCategory ( ueSecurityToken Token, string ProductCategoryRefNum )
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| ProductCategoryRefNum | string | Product category reference number used to delete a product category. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| deleteProductCategoryReturn | boolean | Returns true if product category has been deleted (on error an exception is thrown). |
Exceptions
| Code | Message | Advice |
|---|---|---|
| 41008 | Failed to delete product category | Product category specified by ProductCategoryRefNum was not found. Make sure the number stored is not truncated or rounded. |
getProductCategory
Example Request
Dim catRefNum As String
catRefNum = "9001169812"
Dim category As usaepay.ProductCategory
category = client.getProductCategory(token, catRefNum)
MsgBox(category.Name)
string catRefNum = "900116985";
try
{
usaepay.ProductCategory category = client.getProductCategory(token, catRefNum);
MessageBox.Show(string.Concat(category.Name));
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
Retrieve all data for a single product category
This method retrieves the ProductCategory object for the product category specified by ProductCateogryRefNum. The ProductCategoryRefNum is the gateway assigned unique product category identifier that was returned by addProductCategory.
The entire addProductCategory object is returned.
Related Methods
Syntax
addProductCategory getProductCategory ( ueSecurityToken Token, string ProductCategoryRefNum )
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| ProductCategoryRefNum | string | Unique gateway generated product category id. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| %ProductCategory% | object | Returns a Product Category object containing fields and their values. |
Exceptions
| Code | Message | Advice |
|---|---|---|
| 41006 | Product Category Not Found | Product category specified by ProductCategoryRefNum was not found. Make sure the number stored is not truncated or rounded. |
updateProductCategory
Example Request
Dim catRefNum As String
catRefNum = "9001169811"
Dim category As usaepay.ProductCategory = New usaepay.ProductCategory
category.Name = "third try"
Dim response As Boolean
response = client.updateProductCategory(token, catRefNum, category)
MsgBox(response)
string catRefNum = "900116983";
usaepay.ProductCategory category = new usaepay.ProductCategory();
category.Name = "next try";
Boolean response;
try
{
response = client.updateProductCategory(token, catRefNum, category);
MessageBox.Show(string.Concat(response));
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
This method updates an existing product category.
Updates an existing product category based on its ProductCategoryRefNum. The entire product category is replaced by the contents of the Product category parameter. Developers can use the getProductCategory method to retrieve the Product category object, modify a field and then post the object back to the server.
Syntax
boolean updateProductCategory ( ueSecurityToken, ProductCategoryRefNum, ProductCategory )
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| ProductCategoryRefNum | string | Unique gateway generated product category id. |
| %ProductCategory% | object | Returns a Product Category object containing fields and their values. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| updateProductCategoryReturn | boolean | Returns a true if the product category is updated correctly. |
Exceptions
| Code | Message | Advice |
|---|---|---|
| 41007 | Error saving product category | Product Category specified by ProductCategoryRefNum was not found. Make sure the number stored is not truncated or rounded. |
getProductCategories
Example Request
Dim category() As usaepay.ProductCategory
category = client.getProductCategories(token)
MsgBox(category.Length)
try
{
usaepay.ProductCategory[] category = client.getProductCategories(token);
MessageBox.Show(string.Concat(category.Length));
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay" 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:getProductCategories>
<Token xsi:type="ns1:ueSecurityToken">
<ClientIP xsi:type="xsd:string">192.168.0.1</ClientIP>
<PinHash xsi:type="ns1:ueHash">
<HashValue xsi:type="xsd:string">11ac55b0a0b59f8f028dbf85bc32266fa973dd0e</HashValue>
<Seed xsi:type="xsd:string">12678150211876663375</Seed>
<Type xsi:type="xsd:string">sha1</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">HB4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
</Token>
</ns1:getProductCategories>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example Response
<?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body>
<ns1:getProductCategoriesResponse>
<getProductCategoriesReturn SOAP-ENC:arrayType="ns1:ProductCategory[4]" xsi:type="ns1:ProductCategoryArray">
<item xsi:type="ns1:ProductCategory">
<ProductCategoryRefNum xsi:type="xsd:string">900100191</ProductCategoryRefNum>
<Name xsi:type="xsd:string">Books:Math</Name>
</item>
<item xsi:type="ns1:ProductCategory">
<ProductCategoryRefNum xsi:type="xsd:string">900100193</ProductCategoryRefNum>
<Name xsi:type="xsd:string">Example Category</Name>
</item>
<item xsi:type="ns1:ProductCategory">
<ProductCategoryRefNum xsi:type="xsd:string">900100194</ProductCategoryRefNum>
<Name xsi:type="xsd:string">Example Category</Name>
</item>
<item xsi:type="ns1:ProductCategory">
<ProductCategoryRefNum xsi:type="xsd:string">900100192</ProductCategoryRefNum>
<Name xsi:type="xsd:string">Test Category</Name>
</item>
</getProductCategoriesReturn>
</ns1:getProductCategoriesResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Retrieve all product categories.
This method retrieves an array of ProductCategory objects for all product categories.
Related Methods
Syntax
ProductCategory getProductCategories ( ueSecurityToken
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| %ProductCategory% | array | Returns an array of ProductCategory objects containing information on the product categories |
Product Inventory
getProductInventory
Example Request
<?php
try {
$ProductRefNum = '912093987473';
$inventory = $client->getProductInventory($token, $ProductRefNum);
print_r($inventory);
}
catch(SoapFault $e) {
echo $e->getMessage();
}
?>
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
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:getProductInventory>
<Token xsi:type="ns1:ueSecurityToken">
<ClientIP xsi:type="xsd:string">192.168.0.1</ClientIP>
<PinHash xsi:type="ns1:ueHash">
<HashValue xsi:type="xsd:string">fa10e601d0c6be6c79fce2fdb89f51c65148f8bf</HashValue>
<Seed xsi:type="xsd:string">12693612492090882854</Seed>
<Type xsi:type="xsd:string">sha1</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">1B93L5cpXV5hbx557d183q96EZ2jpqEf</SourceKey>
</Token>
<ProductRefNum xsi:type="xsd:string">9011780645</ProductRefNum>
</ns1:getProductInventory>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example Response
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body>
<ns1:getProductInventoryResponse>
<getProductInventoryReturn SOAP-ENC:arrayType="ns1:ProductInventory[1]" xsi:type="ns1:ProductInventoryArray">
<item xsi:type="ns1:ProductInventory">
<InventoryLocation xsi:type="xsd:string">Los Angeles</InventoryLocation>
<QtyOnHand xsi:type="xsd:string">5</QtyOnHand>
<QtyOnOrder xsi:type="xsd:string">25</QtyOnOrder>
<DateAvailable xsi:type="xsd:string">2009-10-10</DateAvailable>
</item>
</getProductInventoryReturn>
</ns1:getProductInventoryResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Retrieve all current inventory for a single product.
This method retrieves an array of ProductInventory objects for the product specified by ProductRefNum. The ProductRefNum is the gateway assigned unique product identifier that was returned by addProduct. searchProducts can be used to find the ProductRefNum for a product if it is not known.
Each element in the returned array represents the QtyOnHand and QtyOnOrder for each inventory location. For example, if you have inventory in three warehouses, an array with three elements will be returned.
Related Methods
Syntax
ProductInventory getProductInventory ( ueSecurityToken Token, string ProductRefNum)
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| ProductRefNum | string | Unique gateway generated product id. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| %ProductInventory% | array | Returns an array of ProductInventory objects. |
Exceptions
| Code | Message | Advice |
|---|---|---|
| 41002 | Product Not Found | Product specified by ProductRefNum was not found. Make sure the number stored is not truncated or rounded. |
adjustInventory
Example Request
Dim refNum As String
refNum = "9001169811"
Dim inventory(0 To 1) As usaepay.ProductInventory
inventory(0) = New usaepay.ProductInventory()
inventory(0).QtyOnHand = "+100"
inventory(0).DateAvailable = "2010-08-12"
Dim response() As usaepay.ProductInventory
response = client.adjustInventory(token, refNum, inventory)
MsgBox(response.Length)
string RefNum = "900116985";
usaepay.ProductInventory[] inventory = new usaepay.ProductInventory[1];
inventory[0] = new usaepay.ProductInventory();
inventory[0].QtyOnHand = "+100";
inventory[0].DateAvailable = "2010-08-12";
try
{
usaepay.ProductInventory[] response = client.adjustInventory(token, RefNum, inventory);
MessageBox.Show(string.Concat(response.Length));
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
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:adjustInventory>
<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">4e510e34e0e9a2ea067608e7a3298eeb453b3d0b</HashValue>
<Seed xsi:type="xsd:string">11699233146-test</Seed>
<Type xsi:type="xsd:string">sha1</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
</Token>
<ProductRefNum xsi:type="xsd:string">9001001994</ProductRefNum>
<Inventory SOAP-ENC:arrayType="ns1:ProductInventory[1]" xsi:type="ns1:ProductInventoryArray">
<item xsi:type="ns1:ProductInventory">
<InventoryLocation xsi:type="xsd:string">La Mirada</InventoryLocation>
<QtyOnHand xsi:type="xsd:string">50</QtyOnHand>
<QtyOnOrder xsi:type="xsd:string">50</QtyOnOrder>
<DateAvailable xsi:type="xsd:string">2016-01-01</DateAvailable>
</item>
</Inventory>
</ns1:adjustInventory>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example Response
<?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body>
<ns1:adjustInventoryResponse>
<adjustInventoryReturn SOAP-ENC:arrayType="ns1:ProductInventory[1]"
xsi:type="ns1:ProductInventoryArray">
<item xsi:type="ns1:ProductInventory">
<InventoryLocation xsi:type="xsd:string">La Mirada</InventoryLocation>
<QtyOnHand xsi:type="xsd:string">50</QtyOnHand>
<QtyOnOrder xsi:type="xsd:string">50</QtyOnOrder>
<DateAvailable xsi:type="xsd:string">2016-01-01</DateAvailable>
</item>
</adjustInventoryReturn>
</ns1:adjustInventoryResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
This method adjusts the inventory for a product.
This method can be used to either adjust or set the inventory for a product. The product to update inventory for is selected by the ProductRefNum parameter which is assigned by the gateway when the product was added. Inventory levels for multiple warehouses (inventory locations) may be set at the same time. The Inventory parameter is an array of ProductInventory objects containing the new qty levels or adjustments to current levels. Warehouses that are not sent in the array are left as is. Quantities sent as simple numbers will replace the existing quantities. If a "+" or "-" is sent before the number, the existing quantity will be either increased or decreased.
Starting Inventory
| Inventory Location | QtyOnHand | QtyOnOrder |
|---|---|---|
| Los Angeles | 5 | 200 |
| Washington DC | 10 | 0 |
| New York | 123 | 10 |
| Chicago | 24 | 0 |
Inventory Adjustment
| Inventory Location | QtyOnHand | QtyOnOrder | Date Available |
|---|---|---|---|
| Los Angeles | +100 | -100 | 8/10/2010 |
| Washington DC | 0 | 19 | 6/30/2010 |
| New York | -13 | 10 | 8/10/2010 |
Inventory After Adjustment
| Inventory Location | QtyOnHand | QtyOnOrder | Date Available |
|---|---|---|---|
| Los Angeles | 105 | 100 | 8/10/2010 |
| Washington DC | 0 | 19 | 6/30/2010 |
| New York | 110 | 10 | 8/10/2010 |
| Chicago | 24 | 0 |
Related Methods
Syntax
ProductInventory adjustinventory ( ueSecurityToken ProductRefNum, ProductInventory)
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| ProductRefNum | string | Unique gateway generated product id. |
| %ProductInventory% | array | Array of ProductInventory objects containing qty or adjustments for each warehouse/inventory location. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| %ProductInventory% | array | Returns an array of ProductInventory objects containing the adjusted inventory levels. |
Exceptions
| Code | Message | Advice |
|---|---|---|
| 41002 | Product Not Found | Product specified by ProductRefNum was not found. Make sure the number stored is not truncated or rounded. |
| 41003 | Error Saving Product | A database fault was encountered while saving product record. Try operation again or contact support. |
Search Product Database
searchProducts
Example Request
<?php
try {
// Create search parameter list
$search=array(
array(
'Field'=>'name',
'Type'=>'eq',
'Value'=>'A Great Product')
);
$start=0;
$limit=100;
$matchall=true;
$sort='created';
$res=$client->searchProducts($token,$search,$matchall,$start,$limit,$sort);
print_r($res);
}
catch(SoapFault $e) {
echo $client->__getLastResponse();
die("Search Products Failed :".$e->getMessage());
}
?>
<?php
include './nusoap.php';
// Create Soap Client
$s=new soapclient("./usaepay.wsdl",'wsdl');
$tran=$s->getProxy();
// Source Key Setting
$sourcekey='yQbOFkjD8wwlkZ3AhY248k3Lc9PH1l14';
$pin='1234';
// Prep source key
$seed=mktime() . rand();
$tmp=$sourcekey . $seed . $pin;
$hash=sha1($tmp);
$token=array('SourceKey'=>$sourcekey, 'PinHash'=>array('Type'=>'sha1', 'Seed'=>$seed,'HashValue'=>$hash));
// Prep Request data
$search=array(
array('Field'=>'title', 'Type'=>'eq','Value'=>'A Great Product')
);
$start=0;
$limit=10;
$matchall=true;
$sort='created';
$res=$tran->searchProducts($token,$search,$matchall,$start,$limit,$sort);
if(!$err=$tran->getError()) {
print_r($res);
} else {
echo "Error: $err\n";
echo $tran->request;
}
?>
Dim MatchAll As Boolean
MatchAll = False
Dim searchParams(1) As usaepay.SearchParam
searchParams(0) = New usaepay.SearchParam
searchParams(0).Field = "Created"
searchParams(0).Type = "gt"
searchParams(0).Value = "2010-09-07"
Dim SearchResults As usaepay.ProductSearchResult = New usaepay.ProductSearchResult
SearchResults = client.searchProducts(token, searchParams, MatchAll, "0", "1000", "created")
MsgBox(SearchResults.ProductsMatched)
usaepay.SearchParam[] param = new usaepay.SearchParam[1];
param[0] = new usaepay.SearchParam();
param[0].Field = "Created";
param[0].Type = "Contains";
param[0].Value = "2010-08-12";
Boolean matchAll = true;
string start = "0";
string limit = "10";
string sort = "created";
usaepay.ProductSearchResult response = new usaepay.ProductSearchResult();
try
{
response = client.searchProducts(token, param, matchAll, start, limit, sort);
MessageBox.Show(string.Concat(response.ProductsMatched));
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay" 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:searchTransactions>
<Token xsi:type="ns1:ueSecurityToken">
<ClientIP xsi:type="xsd:string">192.168.0.1</ClientIP>
<PinHash xsi:type="ns1:ueHash">
<HashValue xsi:type="xsd:string">11ac55b0a0b59f8f028dbf85bc32266fa973dd0e</HashValue>
<Seed xsi:type="xsd:string">12678150211876663375</Seed>
<Type xsi:type="xsd:string">sha1</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">HB4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
</Token>
<Search SOAP-ENC:arrayType="ns1:SearchParam[1]" xsi:type="ns1:SearchParamArray">
<item xsi:type="ns1:SearchParam">
<Field xsi:type="xsd:string">amount</Field>
<Type xsi:type="xsd:string">eq</Type>
<Value xsi:type="xsd:string">29.00</Value>
</item>
</Search>
<MatchAll xsi:type="xsd:boolean">true</MatchAll>
<Start xsi:type="xsd:integer">0</Start>
<Limit xsi:type="xsd:integer">10</Limit>
<Sort xsi:type="xsd:string">created</Sort>
</ns1:searchTransactions>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Search products and return full product records.
The following fields may be used to search the database and return transaction details:
- ProductID
- ProductRefNum
- SKU
- CategoryID
- Enabled
- Name
- Description
- Model
- Weight
- ShipWeight
- Price
- WholesalePrice
- ListPrice
- DateAvailable
- Manufacturer
- Type
- MinQuantity
- MaxQuantity
- ImageURL
- URL
Related Methods
Syntax
ProductSearchResult searchProducts ( ueSecurityToken Token, SearchParam Search, boolean MatchAll, integer Start, integer limit, string sort)
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| %SearchParam% | array | Array of search parameters. |
| MatchAll | boolean | If set to "true," only results matching all search criteria will be returned, if set to "false," results matching any of the search criteria will be returned. |
| Start | integer | Record number to start returning from (ie if 1,000 were found and you only want to receive the last 200 you would set Start=800 and Limit=200) |
| Limit | integer | Maximum number of records to return in result set. |
| Sort | string | Comma separated list of fields to sort by. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| %ProductSearchResult% | object | Returns full product records for all products matching the specified search parameters. |
searchProductsCount
Example Request
Dim MatchAll As Boolean
MatchAll = False
Dim searchParams(1) As usaepay.SearchParam
searchParams(0) = New usaepay.SearchParam
searchParams(0).Field = "Created"
searchParams(0).Type = "gt"
searchParams(0).Value = "2010-09-07"
Dim SearchResults As usaepay.ProductSearchResult = New usaepay.ProductSearchResult
SearchResults = client.searchProductsCount(token, searchParams, MatchAll, 0, 1000, "created")
MsgBox(SearchResults.ProductsMatched)
usaepay.SearchParam[] param = new usaepay.SearchParam[1];
param[0] = new usaepay.SearchParam();
param[0].Field = "Created";
param[0].Type = "Contains";
param[0].Value = "2010-08-12";
Boolean matchAll = true;
string start = "0";
string limit = "10";
string sort = "created";
usaepay.ProductSearchResult response = new usaepay.ProductSearchResult();
try
{
response = client.searchProductsCount(token, param, matchAll, start, limit, sort);
MessageBox.Show(string.Concat(response.ProductsMatched));
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
Search the product database, only return number of products matched.
Identical to the searchProducts method except only the product counts are returned. Like searchProducts, this method returns productsearchresult. The only difference is that ProductSearchResult.Products is left empty. This method provides a quicker way to determine the size of the result set before starting to retrieve the full search results.
Related Methods
Syntax
ProductSearchResult searchProductsCount ( ueSecurityToken Token, SearchParam Search, boolean MatchAll, integer Start, integer Limit, string Sort )
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| %SearchParam% | array | Array of search parameters. |
| MatchAll | boolean | If set to "true," only results matching all search criteria will be returned, if set to "false," results matching any of the search criteria will be returned. |
| Start | integer | Record number to start returning from (ie if 1,000 were found and you only want to receive the last 200 you would set Start=800 and Limit=200) |
| Limit | integer | Maximum number of records to return in result set. |
| Sort | string | Comma separated list of fields to sort by. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| %ProductSearchResult% | object | Returns full products records for all products matching the specified search parameters. |
searchProductsCustom
Example Request
<?php
try {
// Create search parameter list
$search=array(
array(
'Field'=>'name',
'Type'=>'eq',
'Value'=>'A Great Product')
);
$start=0;
$limit=100;
$matchall=true;
$sort='created';
$res=$client->searchProducts($token,$search,$matchall,$start,$limit,$sort);
print_r($res);
}
catch(SoapFault $e) {
echo $client->__getLastResponse();
die("Search Products Failed :".$e->getMessage());
}
?>
<?php
include './nusoap.php';
// Create Soap Client
$s=new soapclient("./usaepay.wsdl",'wsdl');
$tran=$s->getProxy();
// Source Key Setting
$sourcekey='yQbOFkjD8wwlkZ3AhY248k3Lc9PH1l14';
$pin='1234';
// Prep source key
$seed=mktime() . rand();
$tmp=$sourcekey . $seed . $pin;
$hash=sha1($tmp);
$token=array('SourceKey'=>$sourcekey, 'PinHash'=>array('Type'=>'sha1', 'Seed'=>$seed,'HashValue'=>$hash));
// Prep Request data
$search=array(
array('Field'=>'title', 'Type'=>'eq','Value'=>'A Great Product')
);
$start=0;
$limit=10;
$matchall=true;
$sort='created';
$res=$tran->searchProducts($token,$search,$matchall,$start,$limit,$sort);
if(!$err=$tran->getError()) {
print_r($res);
} else {
echo "Error: $err\n";
echo $tran->request;
}
?>
Dim search(0 To 1) As usaepay.SearchParam
search(0) = New usaepay.SearchParam()
search(0).Field = "Created"
search(0).Type = "Contains"
search(0).Value = "2010-09-07"
Dim matchAll As Boolean
matchAll = True
Dim start As String
start = "0"
Dim limit As String
limit = "10"
Dim FieldList(0 To 2) As String
FieldList(0) = "ProductRefNum"
FieldList(1) = "Name"
FieldList(2) = "Price"
Dim format As String
format = "csv"
Dim sort As String
sort = "created"
Dim result As String
result = client.searchProductsCustom(token, search, matchAll, start, limit, FieldList, format, sort)
Dim binaryData() As Byte
binaryData = Convert.FromBase64String(result)
MsgBox(Encoding.UTF8.GetString(binaryData))
usaepay.SearchParam[] search = new usaepay.SearchParam[1];
search[0] = new usaepay.SearchParam();
search[0].Field = "Created";
search[0].Type = "Contains";
search[0].Value = "2010-08-12";
Boolean matchAll = true;
string start = "0";
string limit = "10";
string[] FieldList = new string[3];
FieldList[0] = "ProductRefNum";
FieldList[1] = "Name";
FieldList[2] = "Price";
string format = "csv";
string sort = "created";
string result;
try
{
result = client.searchProductsCustom(token, search, matchAll, start, limit, FieldList, format, sort);
Byte[] binaryData = new Byte[3];
binaryData = Convert.FromBase64String(result);
MessageBox.Show(Encoding.UTF8.GetString(binaryData));
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay" 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:searchTransactions>
<Token xsi:type="ns1:ueSecurityToken">
<ClientIP xsi:type="xsd:string">192.168.0.1</ClientIP>
<PinHash xsi:type="ns1:ueHash">
<HashValue xsi:type="xsd:string">34108e1b91894ab1da5ecdc213341c6d757217c1</HashValue>
<Seed xsi:type="xsd:string">11936961311067412713</Seed>
<Type xsi:type="xsd:string">sha1</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">HB4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
</Token>
<Search SOAP-ENC:arrayType="ns1:SearchParam[1]" xsi:type="ns1:SearchParamArray">
<item xsi:type="ns1:SearchParam">
<Field xsi:type="xsd:string">amount</Field>
<Type xsi:type="xsd:string">eq</Type>
<Value xsi:type="xsd:string">29.00</Value>
</item>
</Search>
<MatchAll xsi:type="xsd:boolean">true</MatchAll>
<Start xsi:type="xsd:integer">0</Start>
<Limit xsi:type="xsd:integer">10</Limit>
<Sort xsi:type="xsd:string">created</Sort>
</ns1:searchTransactions>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Search products and return specific fields in csv, tab or xml format.
Like searchProducts this function allows for the searching of the product database. Instead of return all data about each product in Product object form, it takes a FieldList parameter which specifies which fields should be returned. The results can be returned in a csv, tab or xml format. In all cases the data is base64 encoded. Developer must decode the data before using.
The following fields may be used to search the database and return transaction details:
- ProductID
- ProductRefNum
- SKU
- CategoryID
- Enabled
- Name
- Description
- Model
- Weight
- ShipWeight
- Price
- WholesalePrice
- ListPrice
- DateAvailable
- Manufacturer
- Type
- MinQuantity
- MaxQuantity
- ImageURL
- URL
Related Methods
Syntax
ProductSearchResult searchproducts ( ueSecurityToken Token, SearchParam Search, boolean MatchAll, integer Start, integer Limit, string FieldList, string Format, string Sort )
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| %SearchParam% | array | Array of search parameters. |
| MatchAll | boolean | If set to "true," only results matching all search criteria will be returned, if set to "false," results matching any of the search criteria will be returned. |
| Start | integer | Record number to start returning from (ie if 1,000 were found and you only want to receive the last 200 you would set Start=800 and Limit=200) |
| Limit | integer | Maximum number of records to return in result set. |
| Sort | string | Comma separated list of fields to sort by. |
| FieldList | list | List of fields to return in search. |
| Format | string | Specify format of return data. Possible formats include: csv, tab, xml. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| searchProductsCustomReturn | string | Base64 encode result set. Returns all of the fields from any transactions matching your search parameters. |
Report Methods
Transaction Reports
getReport
Example Request
<?php
try {
$Options = array(
array('Field'=>'StartDate', 'Value'=>'2007/01/01'),
array('Field'=>'EndDate', 'Value'=>'2007/04/01')
);
$Format='csv';
$Report='CreditCard:Errors By Date';
$res=$client->getReport($token, $Report, $Options, $Format);
$data=base64_decode($res);
print_r($data);
}
catch (SoapFault $e) {
die("Get Transaction failed :" .$e->getMessage());
}
?>
Dim report As String
report = "creditcard:errors by date"
Dim options(0 To 1) As usaepay.FieldValue
options(0) = New usaepay.FieldValue
options(1) = New usaepay.FieldValue
options(0).Field = "Start date"
options(0).Value = "2010-08-01"
options(1).Field = "End date"
options(1).Value = "2010-08-16"
Dim format As String
format = "csv"
Dim response As String
response = client.getReport(token, report, options, format)
Dim binary_data As Byte() = Convert.FromBase64String(response)
MsgBox(System.Text.Encoding.UTF8.GetString(binary_data))
string report = "creditcard:errors by date ";
usaepay.FieldValue[] options = new usaepay.FieldValue[2];
for (int i = 0; i < 2; i++)
{
options[i] = new usaepay.FieldValue();
}
options[0].Field = "StartDate"; options[0].Value = "2010-08-01";
options[1].Field = "EndDate"; options[1].Value = "2010-08-16";
string format = "csv";
string response;
try
{
response = client.getReport(token, report, options, format);
Byte[] binaryData = new Byte[3];
binaryData = Convert.FromBase64String(response);
MessageBox.Show(Encoding.UTF8.GetString(binaryData));
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay" 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:getReport>
<Token xsi:type="ns1:ueSecurityToken">
<ClientIP xsi:type="xsd:string">192.168.0.1</ClientIP>
<PinHash xsi:type="ns1:ueHash">
<HashValue xsi:type="xsd:string">cb451c1c7cd0c9928933c074d6e4b239</HashValue>
<Seed xsi:type="xsd:string">1234</Seed>
<Type xsi:type="xsd:string">md5</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">_0409i1S8XvmVj3ndoBG0HlBu32kYD3t</SourceKey>
</Token>
<Report xsi:type="xsd:string">creditcard:declines by user</Report>
<Format xsi:type="xsd:string">csv</Format>
<Options SOAP-ENC:arrayType="ns1:FieldValue[2]" xsi:type="ns1:FieldValueArray">
<item xsi:type="ns1:FieldValue">
<Field xsi:type="xsd:string">StartDate</Field>
<Value xsi:type="xsd:string">2013/01/01</Value>
</item>
<item xsi:type="ns1:FieldValue">
<Field xsi:type="xsd:string">EndDate</Field>
<Value xsi:type="xsd:string">2013/12/12</Value>
</item>
</Options>
</ns1:getReport>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
This method retrieves a report from the merchant console. Any reports, including custom reports, may be retrieved. The returned data is base 64 encoded. The format of the returned data can be HTML, comma separated (cvs), or tab separated (tab).
Names of built-in reports are prefaced with "CreditCard:", "Check:" or "Customer:". For example, to pull "Sales by Date" for credit cards, the "Report" parameter would be set to "CreditCard:Sales by Date."
To pull a custom credit card or check report, prefix the name with "Custom:" or "CustomCheck:" For example, to pull a custom report titled "Recurring Declines" set the "Report" parameter to "Custom:Recurring Declines." Customer reports can only be created from within the merchant console. If none of the built-in or custom reports provide data required, see the custom search methods (ie searchTransactionsCustom) for more flexibility.
Related Methods
Syntax
string getReport ( ueSecurityToken Token, string Report FieldValue Options, string Format )
Credit Card Reports
| Available Reports | Reports Description |
|---|---|
| creditcard:errors by date | Credit card transactions resulting in errors, sorted by date |
| creditcard:errors by source | Credit card transactions resulting in errors, sorted by source key |
| creditcard:errors by reason | Credit card transactions resulting in errors, sorted by reason |
| creditcard:errors by user | Credit card transactions resulting in errors, sorted by user |
| creditcard:declines by date | Credit card transactions resulting in declines, sorted by date |
| creditcard:declines by source | Credit card transactions resulting in declines, sorted by source key |
| creditcard:declines by reason | Credit card transactions resulting in declines, sorted by reason |
| creditcard:declines by user | Credit card transactions resulting in declines, sorted by user |
| creditcard:sales by date | Credit card transactions resulting in approval, sorted by date |
| creditcard:sales by source | Credit card transactions resulting in approval, sorted by source key |
| creditcard:sales by reason | Credit card transactions resulting in approval, sorted by reason |
| creditcard:sales by user | Credit card transactions resulting in approval, sorted by user |
Check Reports
| Available Reports | Reports Description |
|---|---|
| check:Deposit Report | Check transactions sorted by estimated deposit date |
| check:All Transactions by Date | All Check transactions sorted by date (does not include errors) |
| check:settled by date | Check transactions that have been marked as settled, sorted by date |
| check:settled by source | Check transactions that have been marked as settled, sorted by source |
| check:settled by users | Check transactions that have been marked as settled, sorted by user |
| check:returns by date | Check transactions that have been marked as returned, sorted by date |
| check:returns by source | Check transactions that have been marked as returned, sorted by source |
| check:returns by reason | Check transactions that have been marked as returned, sorted by reason |
| check:returns by user | Check transactions that have been marked as returned, sorted by user |
| check:declines by date | Check transactions were rejected by check processor, sorted by date |
| check:declines by source | Check transactions were rejected by check processor, sorted by sourcekey |
| check:declines by reason | Check transactions were rejected by check processor, sorted by reason |
| check:declines by user | Check transactions were rejected by check processor, sorted by user |
Customer Reports
| Available Reports | Reports Description |
|---|---|
| customer:Pending Billing by Date | Customers that are pending for recurring billing, sorted by next bill date |
| customer:Pending Billing by Source | Customers that are pending for recurring billing, sorted by Source |
| customer:Billing History by Date | Transactions results for recurring billing, sorted by billing date |
| customer:Billing History by Source | Transactions results for recurring billing, sorted by Source |
| customer:Expired Cards | Customers who have an expired credit card on file |
| customer:Expiring before Next Billing | Customers that have a credit card that will expire before the next payment is scheduled to run |
| customer:Expiring by Date Range | Customers that have a credit card expiring in the future |
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| Options | array | Array of FieldValue objects specifying report options such as (StartDate and EndDate) |
| Report | String | Name of report to retrieve. |
| Format | String | Format of returned report data. Possible values are: html, csv, or tab. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| getReportReturn | string | Returns specified report data according to parameters set in search. |
Exceptions
| Code | Message | Advice |
|---|---|---|
| 20014 | Unsupported file format | Valid file formats are html, csv or tab. |
| 20028 | Requested Report not found | Double check the name of the report. |
| 20029 | Unable to retrieve requested report | An account configuration issue was encountered while generating the report. Contact support for assistance. |
getTransactionReport
Example Request
<?php
try {
$StartDate='2007/01/01';
$EndDate='2007/04/10';
$Format='csv';
$Report='CreditCard:Errors By Date';
$res=$client->getTransactionReport($token, $StartDate, $EndDate, $Report, $Format);
$data=base64_decode($res);
print_r($data);
}
catch (SoapFault $e) {
die("Get Transaction failed :" .$e->getMessage());
}
?>
try {
String StartDate = "2009/01/01";
String EndDate = "2009/09/09";
String Format = "html";
String Report = "CreditCard:Errors By Date";
String response = client.getTransactionReport(token, StartDate, EndDate, Report, Format);
BASE64Decoder decoder = new BASE64Decoder();
byte[] decodedBytes = decoder.decodeBuffer(response);
String report = new String(decodedBytes);
System.out.println(report);
} catch (Exception e) {
System.out.println("Soap Exception: " + e.getMessage());
}
Dim start As String
start = "2010-08-01"
Dim endd As String
endd = "2010-08-09"
Dim format As String
format = "html"
Dim report As String
report = "CreditCard:Sales By Date"
Dim response As String
response = client.getTransactionReport(token, start, endd, report, format)
Dim decbuff() As Byte
decbuff = Convert.FromBase64String(response)
MsgBox(Encoding.UTF8.GetString(decbuff))
string start = "2010-08-01";
string end = "2010-08-09";
string format = "html";
string report = "CreditCard:Sales By Date";
try
{
string response = client.getTransactionReport(token, start, end, report, format);
byte[] decbuff = Convert.FromBase64String(response);
MessageBox.Show(Encoding.UTF8.GetString(decbuff));
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
This method retrieves a report from the merchant console. Any reports, including custom reports, may be retrieved. The returned data is base 64 encoded. The format of the returned data can be HTML, comma separated (cvs), or tab separated (tab).
Names of built-in reports are prefaced with either "CreditCard:" or "Check:" For example, to pull "Sales by Date" for credit cards, the "Report" parameter would be set to "CreditCard:Sales by Date."
To pull a custom credit card or check report, prefix the name with "Custom:" or "CustomCheck:" For example, to pull a custom report titled "Recurring Declines" set the "Report" parameter to "Custom:Recurring Declines."
Related Methods
- getTransactionStatus
- getTransactionCustom
- searchTransactions
- searchTransactionsCustom
- getTransaction
Syntax
string getTransactionReport ( ueSecurityToken Token, string StartDate, string EndDate, string Report, string Format )
Credit Card Reports
| Available Reports | Reports Description |
|---|---|
| creditcard:errors by date | Credit card transactions resulting in errors, sorted by date |
| creditcard:errors by source | Credit card transactions resulting in errors, sorted by source key |
| creditcard:errors by reason | Credit card transactions resulting in errors, sorted by reason |
| creditcard:errors by user | Credit card transactions resulting in errors, sorted by user |
| creditcard:declines by date | Credit card transactions resulting in declines, sorted by date |
| creditcard:declines by source | Credit card transactions resulting in declines, sorted by source key |
| creditcard:declines by reason | Credit card transactions resulting in declines, sorted by reason |
| creditcard:declines by user | Credit card transactions resulting in declines, sorted by user |
| creditcard:sales by date | Credit card transactions resulting in approval, sorted by date |
| creditcard:sales by source | Credit card transactions resulting in approval, sorted by source key |
| creditcard:sales by reason | Credit card transactions resulting in approval, sorted by reason |
| creditcard:sales by user | Credit card transactions resulting in approval, sorted by user |
Check Reports
| Available Reports | Reports Description |
|---|---|
| check:Deposit Report | Check transactions sorted by estimated deposit date |
| check:All Transactions by Date | All Check transactions sorted by date (does not include errors) |
| check:settled by date | Check transactions that have been marked as settled, sorted by date |
| check:settled by source | Check transactions that have been marked as settled, sorted by source |
| check:settled by users | Check transactions that have been marked as settled, sorted by user |
| check:returns by date | Check transactions that have been marked as returned, sorted by date |
| check:returns by source | Check transactions that have been marked as returned, sorted by source |
| check:returns by reason | Check transactions that have been marked as returned, sorted by reason |
| check:returns by user | Check transactions that have been marked as returned, sorted by user |
| check:declines by date | Check transactions were rejected by check processor, sorted by date |
| check:declines by source | Check transactions were rejected by check processor, sorted by sourcekey |
| check:declines by reason | Check transactions were rejected by check processor, sorted by reason |
| check:declines by user | Check transactions were rejected by check processor, sorted by user |
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| StartDate | string | The earliest report date to retrieve. |
| EndDate | string | The latest report date to retrieve. |
| Report | string | Name of report to retrieve. |
| Format | string | Format of returned report data. Possible values are: html, csv, or tab. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| getTransactionReportReturn | string | Returns specified report data according to parameters set in search. |
Customer Reporting
getCustomerReport
This method retrieves a report from the merchant console. Any reports, including custom reports, may be retrieved. The returned data is base 64 encoded. The format of the returned data can be HTML, comma separated (cvs), or tab separated (tab).
Names of built-in reports are prefaced with "CreditCard:", "Check:" or "Customer:". For example, to pull "Sales by Date" for credit cards, the "Report" parameter would be set to "CreditCard:Sales by Date."
To pull a custom credit card or check report, prefix the name with "Custom:" or "CustomCheck:" For example, to pull a custom report titled "Recurring Declines" set the "Report" parameter to "Custom:Recurring Declines." Customer reports can only be created from within the merchant console. If none of the built-in or custom reports provide data required, see the custom search methods (ie searchTransactionsCustom) for more flexibility.
| Available Reports | Reports Description |
|---|---|
| customer:Pending Billing by Date | Customers that are pending for recurring billing, sorted by next bill date |
| customer:Pending Billing by Source | Customers that are pending for recurring billing, sorted by Source |
| customer:Future Billing by Date | Customers that have recurring billing enabled, sorted by bill date |
| customer:Future Billing by Source | Customers that have recurring billing enabled, sorted by source |
| customer:Billing History by Date | Transactions results for recurring billing, sorted by billing date |
| customer:Billing History by Source | Transactions results for recurring billing, sorted by Source |
| customer:Expired Cards | Customers who have an expired credit card on file |
| customer:Expiring before Next Billing | Customers that have a credit card that will expire before the next payment is scheduled to run |
| customer:Expiring by Date Range | Customers that have a credit card expiring in the future |
Related Methods
Syntax
string getCustomerReport ( ueSecurityToken Token, string Report, FieldValue Options, string Format )
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| Options | array | Array of FieldValue objects specifying report options such as (StartDate and EndDate) |
| Report | string | Name of report to retrieve. |
| Format | string | Format of returned report data. Possible values are: html, csv, or tab. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| getCustomerReportReturn | string | Returns specified report data according to parameters set in search. |
Change Log
| Version | Description |
|---|---|
| 1.3 | Method added in this release |
Settings Methods
Fraud Profiling
getSession
Example Request
<?php
try {
$res=$client->getSession($token);
print_r($data);
}
catch (SoapFault $e) {
die("Get Session failed :" .$e->getMessage());
}
?>
Dim response As usaepay.TransactionSession
response = client.getSession(token, report, options, format)
Dim binary_data As Byte() = Convert.FromBase64String(response)
MsgBox("SessionID: " & response.SessionID);
usaepay.TransactionSession response;
try
{
response = client.getSession(token);
MessageBox.Show(response.SessionID);
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
This method generates a fraud profiling session. Fraud profiling allows merchants to perform in depth analysis and business risk assessment using third party services such as Threat Metrix. These premium services must be enabled on the merchants account before this method may be used.
The method returns a TransactionSession object which contains a session id and an org id. These variables are used to assemble the profiling html snippet that needs to be displayed to the end user. The session id is then passed in with the runTransaction, runSale, etc call.
See also: ThreatMetrix
Syntax
TransactionSession getSession ( ueSecurityToken Token )
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| %TransactionSession% | object | Returns session data. |
Exceptions
| Code | Message | Advice |
|---|---|---|
| 20035 | Merchant does not have fraud profiling enabled | The merchant's account must be configured for fraud profiling. They should contact their reseller to sign up for the service. |
getTransactionProfile
Example Request
<?php
try {
$RefNum='12345678';
$data=$client->getTransactionProfile($token, $RefNum);
print_r($data);
}
catch (SoapFault $e) {
die("Call failed :" .$e->getMessage());
}
?>
Dim response As usaepay.TransactionProfile
response = client.getTransactionProfile(token, 1234567)
MsgBox("DeviceID: " & response.DeviceID);
usaepay.TransactionProfile response;
try
{
response = client.getTransactionProfile(token);
MessageBox.Show(response.DeviceID);
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
This method retrieves the fraud profiling data for a given transaction.
Fraud profiling allows merchants to perform in depth analysis and business risk assessment using third party services such as Threat Metrix. These premium services must be enabled on the merchants account before this method may be used.
If profiling data is available, a TransactionProfile object is returned. This object contains profile data such as the scoring and extended device data.
See also: ThreatMetrix
Related Methods
Syntax
TransactionProfile getTransactionProfile ( ueSecurityToken Token, string RefNum )
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| RefNum | string | Unique transaction reference number assigned by the gateway. You can also use TransKey in the RefNum field. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| TransactionProfile | string | Returns fraud profile data. |
Exceptions
| Code | Message | Advice |
|---|---|---|
| 20001 | Specified transactions was not found | RefNum didn't match any of the merchants transactions. |
| 20035 | Merchant does not have fraud profiling enabled | The merchant's account must be configured for fraud profiling. They should contact their reseller to sign up for the service. |
Change Log
| Version | Description |
|---|---|
| 1.7 | TransKey can be used in RefNum field. |
Multi-Currency
getSupportedCurrencies
Example Request
<?php
try {
$currencies = $client->getSupportedCurrencies($token);
print_r($currencies);
}
catch(SoapFault $e) {
die("soap fault: " .$e->getMessage(). "\n\nRequest: " .
$this->client->__getLastResponse());
}
?>
//PHP Pear SOAP
<?php
$params=array("Token"=>$token);
$currencies=$client->call('getSupportedCurrencies', $params);
print_r($currencies);
?>
Dim response() As usaepay.CurrencyObject
response = client.getSupportedCurrencies(token)
MsgBox(response.Length)
try
{
usaepay.CurrencyObject[] currency = client.getSupportedCurrencies(token);
MessageBox.Show(string.Concat(currency.Length));
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
Depending on the merchant account configuration, different currencies are available for multi-currency processing. This method will return an array containing the currencies that are supported by the merchant account.
If multi-currency processing is not supported, the array will be empty.
To view the account details for a particular merchant account, including whether or not the account supports multi-currency processing, use the getAccountDetails method.
Each currency type is assigned a three digit numeric code (ie: USD=840, Japanese yen=392). You must enter the three digit code for both the original currency and the converted currency in a conversion. The Currency Code list provides all of the three digit codes and their corresponding currencies for international currency conversion.
If you would like to add support for multi-currency transactions to a merchant account please contact the merchant's service provider or customer service.
Related Methods
Syntax
CurrencyObject getSupportedCurrencies ( ueSecurityToken Token)
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| %CurrencyObject% | object | Returns an array of currencies supported by the merchant account for use with multi-currency processing. |
currencyConversion
Example Request
<?php
// for directions on how to set up the
// WSDL link and create "$mctoken" and "$client,"
try {
$ToCurrency='978';
$FromCurrency='840';
$Amount=50;
$res=$client->currencyConversion($mctoken, $FromCurrency, $ToCurrency, $Amount);
print_r($res);
$this->assertEquals($res->FromCurrency, $FromCurrency);
$this->assertEquals($res->Currency, $ToCurrency);
$this->assertTrue($res->Rate > 0);
$this->assertTrue($res->Amount > 0);
} catch (SoapFault $e) {
echo $client->__getLastRequest();
echo $client->__getLastResponse();
die('Currency conversion failed : '.$e->getMessage());
}
?>
Dim from As String
Dim convert As String
Dim amount As Double
from = "036"
convert = "826"
amount = 50
Dim response As usaepay.CurrencyConversion = New usaepay.CurrencyConversion
response = client.currencyConversion(token, from, convert, amount)
MsgBox(response.Amount)
string from = "840";
string to = "978";
int amount = 50;
usaepay.CurrencyConversion response = new usaepay.CurrencyConversion();
try
{
response = client.currencyConversion(token, from, to, amount);
MessageBox.Show(string.Concat(response.Amount));
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
This method allows you to determine the rate of conversion for different currencies in multi-currency transactions. A merchant account must have support for specific types of currency before it will be able to run multi-currency transactions.
To determine if a currency is supported by a merchant account, use either the getSupportedCurrencies or the getAccountDetails method.
Each currency type is assigned a three digit numeric code (ie: USD=840, Japanese yen=392). You must enter the three digit code for both the original currency and the converted currency in a conversion. The Currency Code list provides all of the three digit codes and their corresponding currencies for international currency conversion.
If you would like to add support for multi-currency transactions to a merchant account please contact the merchant's service provider or customer service.
Related Methods
Syntax
currencyConversion currencyConversion ( ueSecurityToken Token, integer FromCurrency, integer ToCurrency, double Amount )
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| Amount | double | Amount of currency to be converted. |
| FromCurrency | string | Currency code funds will be converted from. |
| ToCurrency | string | Currency code funds will be converted to. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| %CurrencyConversion% | object | Returns the rate of conversion and the amount of the converted currency. |
bulkCurrencyConversion
Example Request
<?php
try {
$ToCurrency='978';
$FromCurrency='840';
$Amounts=array(
50.10,
11.23,
34.21,
12.23
);
$res=$client->bulkCurrencyConversion($mctoken, $FromCurrency, $ToCurrency, $Amounts);
print_r($res);
$this->assertEquals(count($res), count($Amounts));
$this->assertEquals($res[0]->FromCurrency, $FromCurrency);
$this->assertEquals($res[0]->Currency, $ToCurrency);
$this->assertEquals($res[0]->FromAmount, $Amounts[0]);
$this->assertTrue($res[0]->Rate > 0);
$this->assertTrue($res[0]->Amount > 0);
}
catch (SoapFault $e) {
die('Currency conversion failed : '.$e->getMessage());
}
?>
Dim from As String
Dim convert As String
Dim amount(0 To 2) As Double
from = "036"
convert = "826"
amount(0) = 10
amount(1) = 20
amount(2) = 30
Dim response() As usaepay.CurrencyConversion
response = client.bulkCurrencyConversion(token, from, convert, amount)
MsgBox(response.Length)
string from = "124";
string to = "826";
double[] amount = new double[3];
amount[0] = 10;
amount[1] = 5;
amount[2] = 19.99;
//usaepay.CurrencyConversion response = new usaepay.CurrencyConversion();
try
{
usaepay.CurrencyConversion[] response = client.bulkCurrencyConversion(token, from, to, amount);
MessageBox.Show(string.Concat(response.Length));
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
This method allows you to complete a large batch of currency conversions all at once without having to use the CurrencyConversion method for each conversion.
Currently this method supports bulk conversions from a single currency to another single currency and not several currencies simultaneously. (ie: if you want to convert fifty amounts from USD [US dollars] to CAD [Canadian dollars] and twenty amounts from USD to EUR [Euros] you would need to run two separate bulkCurrencyConversion method calls.)
To determine if a currency is supported by a merchant account, use either the getSupportedCurrencies or the getAccountDetails method.
Each currency type is assigned a three digit numeric code (ie: USD=840, Japanese yen=392). You must enter the three digit code for both the original currency and the converted currency in a conversion. The Currency Code list provides all of the three digit codes and their corresponding currencies for international currency conversion.
If you would like to add support for multi-currency transactions to a merchant account please contact the merchant's service provider or customer service.
Related Methods
Syntax
CurrencyConversion bulkCurrencyConversion ( ueSecurityToken Token, integer FromCurrency, integer ToCurrency, double Amounts )
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| Amount | double | Amount of currency to be converted. |
| FromCurrency | string | Currency code funds will be converted from. |
| ToCurrency | string | Currency code funds will be converted to. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| %CurrencyConversion% | object | Returns the rate of conversion and the amount of the converted currency. |
Account Details/System Info
getAccountDetails
Example Request
<?php
try {
$details = $client->getAccountDetails($token);
}
catch(SoapFault $e) {
echo "soap fault: " .$e->getMessage();
}
?>
try {
AccountDetails Account = new AccountDetails();
Account = client.getAccountDetails(token);
} catch (Exception e) {
System.out.println("Soap Exception: " + e.getMessage());
}
Dim response As usaepay.AccountDetails = New usaepay.AccountDetails
response = client.getAccountDetails(token)
MsgBox(response.CreditCardPlatform)
usaepay.AccountDetails merchant = new usaepay.AccountDetails();
try
{
merchant = client.getAccountDetails(token);
MessageBox.Show(string.Concat(merchant.CreditCardPlatform));
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay" 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:getAccountDetails>
<Token xsi:type="ns1:ueSecurityToken">
<ClientIP xsi:type="xsd:string">192.168.0.1</ClientIP>
<PinHash xsi:type="ns1:ueHash">
<HashValue xsi:type="xsd:string">11ac55b0a0b59f8f028dbf85bc32266fa973dd0e</HashValue>
<Seed xsi:type="xsd:string">12678150211876663375</Seed>
<Type xsi:type="xsd:string">sha1</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">HB4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
</Token>
</ns1:getAccountDetails>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
This method will return details about your merchant account. It is useful for determining what functionality your account supports.
For example this method can help you determine if your account includes support for check processing, multiple currencies or cardholder authentication.
Related Methods
Syntax
AccountDetails getAccountDetails ( ueSecurityToken Token )
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| %AccountDetails% | object | Returns details pertaining to the merchant account requested, including the name of their credit card platform, the merchant's type of industry, whether the merchant account supports check processing, type of cardholder authentication and an array of currencies supported by the account. |
getSystemInfo
Example Request
<?php
try {
$response=$client->getSystemInfo($this->token);
print_r($response);
}
catch (SoapFault $e){
echo $client->__getLastRequest();
echo $client->__getLastResponse();
$this->fail("Get SystemInfo failed:" .$e->getMessage());
}
?>
Dim info As usaepay.SystemInfo = New usaepay.SystemInfo
info = client.getSystemInfo(token)
MsgBox(info.ApiVersion)
try
{
usaepay.SystemInfo system = client.getSystemInfo(token);
MessageBox.Show(string.Concat(system.ApiVersion));
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
This method pulls the system information.
Information accessible through this method includes API version number, environment (production/sandbox/staging), data-center location, and the current time.
Syntax
SystemInfo getSystemInfo ( ueSecurityToken Token )
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| %SystemInfo% | object | Retrieves API version, environment, data-center, time. |
getSyncLog
Example Request
Dim ObjectName As String
ObjectName = "Product"
Dim FromPosition As String
Dim log() As usaepay.SyncLog
log = client.getSyncLog(token, ObjectName, FromPosition)
MsgBox(log.Length)
string ObjectName = "Product";
string FromPosition = "0";
try
{
usaepay.SyncLog[] log = client.getSyncLog(token, ObjectName, FromPosition);
MessageBox.Show(string.Concat(log.Length));
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay" 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:getSyncLog>
<Token xsi:type="ns1:ueSecurityToken">
<ClientIP xsi:type="xsd:string">192.168.0.1</ClientIP>
<PinHash xsi:type="ns1:ueHash">
<HashValue xsi:type="xsd:string">11ac55b0a0b59f8f028dbf85bc32266fa973dd0e</HashValue>
<Seed xsi:type="xsd:string">12678150211876663375</Seed>
<Type xsi:type="xsd:string">sha1</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">HB4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
</Token>
<ObjectName xsi:type="xsd:string">
Product
</ObjectName>
<FromPosition xsi:type="xsd:integer">
181
</FromPosition>
</ns1:getSyncLog>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example Response
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body>
<ns1:getSyncLogResponse>
<getSyncLogReturn SOAP-ENC:arrayType="ns1:SyncLog[1]" xsi:type="ns1:SyncLogArray">
<item xsi:type="ns1:SyncLog">
<SyncPosition xsi:type="xsd:integer">
181
</SyncPosition>
<ObjectName xsi:type="xsd:string">
Product
</ObjectName>
<RefNum xsi:type="xsd:string">
9011780645
</RefNum>
<ChangeDate xsi:type="xsd:dateTime">
2010-03-23T09:01:40
</ChangeDate>
<Action xsi:type="xsd:string">
Update
</Action>
</item>
</getSyncLogReturn>
</ns1:getSyncLogResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
This method allows for the intelligent synchronization of data between the gateway and the developer's software.
Related Methods
Syntax
SyncLog getSyncLog ( ueSecurityToken ObjectName, FromPosition )
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| ObjectName | string | The name of object being synced (leave blank to look at all objects).c |
| FromPosition | integer | Specifies the log position to start from. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| %SyncLog% | object | Returns as array of SyncLog objects. |
Exceptions
| Code | Message | Advice |
|---|---|---|
| 41004 | Unknown Object | The specified ObjectName was not recognized. ObjectName must either be left blank (for all objects) or must correspond to a valid object (ie Product, Customer, etc). |
getSyncLogCurrentPosition
Example Request
Dim ObjectName As String
ObjectName = "Product"
Dim log As String
log = client.getSyncLogCurrentPosition(token, ObjectName)
MsgBox(log)
string ObjectName = "Product";
string response;
try
{
response = client.getSyncLogCurrentPosition(token, ObjectName);
MessageBox.Show(string.Concat(response));
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
The system keeps a log of every change made to various objects (such as Product, Customers, etc). Each change is tagged with a sequential log position (starting at 1 and counting up). This method returns the last position in the log for the given ObjectName. This is useful if you have just retrieved all products from the server and are now ready to start doing incremental syncing. (See the getSyncLog method for more information on incremental syncing).
Leave ObjectName blank to retrieve the last position for all objects.
Syntax
integer getSyncLogCurrentPosition ( ueSecurityToken ObjectName )
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
| ObjectName | string | Type of object: Product, Customer, etc. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| getSyncLogCurrentPositionReturn | integer | Returns the current sync position for ObjectName |
Exceptions
| Code | Message | Advice |
|---|---|---|
| 41004 | Unknown Object | The specified ObjectName was not recognized. ObjectName must either be left blank (for all objects) or must correspond to a valid object (ie Product, Customer, etc). |
getCustomFields
Example Request
<?php
try {
$res = $client->getCustomFields($token);
print_r($res);
}
catch(SoapFault $e) {
echo $e->getMessage();
}
?>
Dim trace() As usaepay.FieldValue
trace = client.getCustomFields(token)
MsgBox(trace(0).Value)
try
{
usaepay.FieldValue[] response = client.getCustomFields(token);
MessageBox.Show(string.Concat(response.Length));
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay" 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:getCustomFields>
<Token xsi:type="ns1:ueSecurityToken">
<ClientIP xsi:type="xsd:string">192.168.0.1</ClientIP>
<PinHash xsi:type="ns1:ueHash">
<HashValue xsi:type="xsd:string">11ac55b0a0b59f8f028dbf85bc32266fa973dd0e</HashValue>
<Seed xsi:type="xsd:string">12678150211876663375</Seed>
<Type xsi:type="xsd:string">sha1</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">HB4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
</Token>
</ns1:getCustomFields>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example Response
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:usaepay"
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body>
<ns1:getCustomFieldsResponse>
<getCustomFieldsReturn SOAP-ENC:arrayType="ns1:FieldValue[3]" xsi:type="ns1:FieldValueArray">
<item xsi:type="ns1:FieldValue">
<Field xsi:type="xsd:string">custom1</Field>
<Value xsi:type="xsd:string">Favorite Color</Value>
</item>
<item xsi:type="ns1:FieldValue">
<Field xsi:type="xsd:string">custom2</Field>
<Value xsi:type="xsd:string">Favorite Movie</Value>
</item>
<item xsi:type="ns1:FieldValue">
<Field xsi:type="xsd:string">custom3</Field>
<Value xsi:type="xsd:string">Favorite Icecream</Value>
</item>
</getCustomFieldsReturn>
</ns1:getCustomFieldsResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
This method allows you to retrieve the custom fields for a specific gateway account.
Use this method to identify which custom fields exist.
To retrieve the list of custom fields a token must me provided as an argument. The token will be used to identify the specific gateway account.
Related Methods
Syntax
FieldValue getCustomFields ( ueSecurityToken )
Examples
- PHP- For directions on how to set up the WSDL link, create "$token" and "$client", go to SOAP PHP How-to.
- Java- This example uses the USAePay Java library. For directions on how to install the library and create the token/client objects, go to to the Java JAX-WS Howto.
- VB.NET- For directions on how to set up the WSDL link, create "token" and "client", go to Visual Basic .Net Soap How-to.
- .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.
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Merchant security token: used to identify merchant and validate transaction. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| FieldValue | array | Returns a FieldValue array containing the custom field and its name. |
Exceptions
| Code | Message | Advice |
|---|---|---|
| 40470 | No custom fields defined. | Merchant has not configured any custom fields. They must log into the merchant console to configure custom fields. |
Objects
ueSecurityToken
Defines a source key used to identify a merchant or reseller.
This object defines a source key which is used to identify the merchant or reseller making the request. Source keys are obtained by logging into the merchant or reseller console.
A source key that has a pin assigned must include the Hash object. It is highly recommended that a pin always be used in conjunction with the source key.
All SOAP methods require the use of a pin, except the following transaction methods:
- runTransactionApi
- runTransaction
- runSale
- runQuickSale
- runCredit
- runAuthOnly
- postAuth
- captureTransaction
The ClientIP is used to reference the end client. While this field is not required (it can be left blank) it is used by several fraud modules and is recommended.
Properties
Example Code
<?php
class TokenClientExample {
public $client; // initialize client
public $token;// initialize token
function setUp{
$client=self::getClient(); //Using this class
$token=self::getToken(); //Using this class
}
static function getClient(){
//for live server use 'www' for test server use 'sandbox'
$wsdl='https://www.usaepay.com/soap/gate/131C979E/usaepay.wsdl';
return new SoapClient($wsdl,array("trace"=>1,"exceptions"=>1));
//Must have Php5 compiled with --enable-soap
*Otherwise use pear soap. For more info please visit: http:*pear.php.net/package/SOAP
}
static function getToken(){
// Creating a ueSecurityToken
$sourcekey = 'yQbOFkmykeygoeshere3Lc9PH1l14';
//Input your merchant console generated source key
$pin = '1234'; //Input the PIN set in the source editor for your source key
// generate random seed value
$seed=mktime() . rand();
// make hash value using sha1 function
$clear= $sourcekey . $seed . $pin;
$hash=sha1($clear);
// assembly ueSecurityToken as an array
// (php5 will correct the type for us)
$tok=array(
'SourceKey'=>$sourcekey,
'PinHash'=>array(
'Type'=>'sha1',
'Seed'=>$seed,
'HashValue'=>$hash
),
'ClientIP'=>'192.168.0.1'
);
return $tok;
}
}
?>
<?php
// Creating a ueSecurityToken
$sourcekey = 'yQbOFkjD8wwlkZ3AhY248k3Lc9PH1l14';
$pin = '1234';
// generate random seed value
$seed=mktime() . rand();
// make hash value using sha1 function
$clear= $sourcekey . $seed . $pin;
$hash=sha1($clear);
// assembly ueSecurityToken as an array
// (php4 will correct the type for us)
$token=array(
'SourceKey'=>$sourcekey,
'PinHash'=>array(
'Type'=>'sha1',
'Seed'=>$seed,
'HashValue'=>$hash
),
'ClientIP'=>'192.168.0.1'
);
?>
Imports System
Imports System.Web
Imports System.IO
Imports System.Security.Cryptography
Imports System.Text
Private Sub mySoapCall()
Dim token As usaepay.ueSecurityToken
Dim hash As usaepay.ueHash = New usaepay.ueHash
Dim sourcekey As String
Dim pin As String
' The source key and pin are created by the merchant
sourcekey = "e42SYc86C4uvlvyP62ow54Kv93SZsJVm"
pin = "1234"
token = New usaepay.ueSecurityToken
token.SourceKey = sourcekey
' To create the hash we must concat the sourcekey, seed and pin
Dim rand As System.Random = New System.Random
hash.Seed = Date.Now.ToUniversalTime & rand.Next()
Dim prehashvalue As String
prehashvalue = sourcekey & hash.Seed & pin
' Generate the md5 hash
hash.Type = "md5"
hash.HashValue = GenerateHash(prehashvalue)
token.PinHash = hash
End Sub
Private Function GenerateHash(ByVal SourceText As String) As String
'Instantiate an MD5 Provider object
Dim md5 As New MD5CryptoServiceProvider
'Compute the hash value from the source
Dim ByteHash() As Byte = md5.ComputeHash(Encoding.Default.GetBytes(SourceText))
'Instantiate a StringBuilder object
Dim sb As New StringBuilder
'Repack binary hash as hex
For c As string = 0 To ByteHash.Length - 1
sb.AppendFormat("{0:x2}", ByteHash(c))
Next c
'Return the hex hash
Return sb.ToString
End Function
usaepay.ueSecurityToken token = new usaepay.ueSecurityToken();
// SourceKey and Pin (created in merchant console)
token.SourceKey = "O79****************************c8";
string pin = "1234";
// IP address of end user (if applicable)
token.ClientIP = "11.22.33.44";
// Instantiate Hash
usaepay.ueHash hash = new usaepay.ueHash();
hash.Type = "md5"; // Type of encryption
hash.Seed = Guid.NewGuid().ToString(); // unique encryption seed
// Assemble string and hash
string prehashvalue = string.Concat(token.SourceKey, hash.Seed, pin);
hash.HashValue = GenerateHash(prehashvalue);
// Add hash to token
token.PinHash = hash;
| Name | Type | Description |
|---|---|---|
| SourceKey | string | SourceKey obtained in merchant console. |
| %ueHash% | PinHash | Hash object for the PIN (only necessary if this source key has a pin assigned) |
| ClientIP | string | The IP Address of the end client |
ueHash
Defines the properties of the hash used to validate a source key.
This object defines the properties of the hash used to validate a source key. This object is only required on source keys that have a pin assigned.
Pins are not meant to be stored by the application. Instead the application should prompt the end user for the pin. The pin may be cached temporarily, but should not be stored permanently unless appropriate security measures such as strong encryption are taken.
Please note that access to certain methods will require a pin. These features are restricted to sources with a pin to minimize the impact of a merchant's source key being stolen.
Properties
Example Code
Dim hash As usaepay.ueHash = New usaepay.ueHash
Dim sourcekey As String
Dim pin As String
' The source key and pin are created by the merchant
sourcekey = "e42SYc86C4uvlvyP62ow54Kv93SZsJVm"
pin = "1234"
token = New usaepay.ueSecurityToken
token.SourceKey = sourcekey
' To create the hash we must concat the sourcekey, seed and pin
Dim rand As System.Random = New System.Random
hash.Seed = Date.Now.ToUniversalTime & rand.Next()
Dim prehashvalue As String
prehashvalue = sourcekey & hash.Seed & pin
' Generate the md5 hash
hash.Type = "md5"
hash.HashValue = GenerateHash(prehashvalue)
token.PinHash = hash
Private Function GenerateHash(ByVal SourceText As String) As String
'Instantiate an MD5 Provider object
Dim md5 As New MD5CryptoServiceProvider
'Compute the hash value from the source
Dim ByteHash() As Byte = md5.ComputeHash(Encoding.Default.GetBytes(SourceText))
'Instantiate a StringBuilder object
Dim sb As New StringBuilder
'Repack binary hash as hex
For c As Integer = 0 To ByteHash.Length - 1
sb.AppendFormat("{0:x2}", ByteHash(c))
Next c
'Return the hex hash
Return sb.ToString
End Function
MD5 md5Hasher = MD5.Create();
// Convert the input string to a byte array and compute the hash.
byte[] data = md5Hasher.ComputeHash(Encoding.Default.GetBytes(input));
// Create a new Stringbuilder to collect the bytes
// and create a string.
StringBuilder sBuilder = new StringBuilder();
// Loop through each byte of the hashed data
// and format each one as a hexadecimal string.
for (int i = 0; i < data.Length; i++)
{
sBuilder.Append(data[i].ToString("x2"));
}
// Return the hexadecimal string.
return sBuilder.ToString();
| Name | Type | Description |
|---|---|---|
| Type | string | Hashing Function Used: Currently only "md5" and "sha1" are supported. |
| Seed | string | The data used to seed the hash: This value must be unique and cannot be reused. The system will reject the request if a Seed is reused. The reason for this is to minimize the damage if a HashValue is stolen. An intruder may manage to obtain a SourceKey and a HashValue, but will not be able to use the source key since the HashValue is based on a seed that cannot be reused. |
| HashValue | string | Hash string: The resulting hash. The hash is calculated by concatenating the SourceKey, the Seed and the Pin value. Do not place any characters in between these values. Once the values have been concatenated, calculate the hash string using the algorithm specified by Type. |
AccountDetails
Contains all relevant data pertaining to a merchant account.
This object details the functionality of a merchant account including type of processing platform, account industry, check processing capabilities, integrated cardholder authentication systems and types of currencies accepted by the merchant account.
Places Used
Properties
Example Object
<?php
// for directions on how to set up the
// WSDL link and create "$token" and "$client,"
// see: [https://help.usaepay.info/developer/soap-api/howto/php/](https://help.usaepay.info/developer/soap-api/howto/php/)
$AccountDetails = $this->client->getAccountDetails($this->token);
echo $AccountDetails->CreditCardPlatform;
?>
Dim response As usaepay.AccountDetails = New usaepay.AccountDetails
response = client.getAccountDetails(token)
MsgBox(response.CreditCardPlatform)
usaepay.AccountDetails merchant = new usaepay.AccountDetails();
try
{
merchant = client.getAccountDetails(token);
MessageBox.Show(string.Concat(merchant.CreditCardPlatform));
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
<getAccountDetailsReturn xsi:type="ns1:AccountDetails">
<CardholderAuthentication xsi:type="xsd:string">Disabled</CardholderAuthentication>
<CheckPlatform xsi:type="xsd:string">TestBed</CheckPlatform>
<CreditCardPlatform xsi:type="xsd:string">Test Bed</CreditCardPlatform>
<DebitCardSupport xsi:type="xsd:boolean">false</DebitCardSupport>
<DirectPayPlatform xsi:type="xsd:string">Disabled</DirectPayPlatform>
<Industry xsi:type="xsd:string">eCommerce</Industry>
<SupportedCurrencies SOAP-ENC:arrayType="ns1:CurrencyObject[0]" xsi:type="ns1:CurrencyObjectArray"/>
</getAccountDetailsReturn>
| Name | Type | Description |
|---|---|---|
| CreditCardPlatform | string | Name of Card Processing Platform, "Disabled" if no credit card support |
| Industry | string | Account Industry (eCommerce, Mail Order, Retail, Restaurant, Hotel) |
| CheckPlatform | string | Name of Check Processor, "Disabled" if no support for checks. |
| CardholderAuthentication | string | Integrated cardholder authentication (Verified by Visa or MC 3D Secure) |
| DebitCardSupport | boolean | True if merchant has support for processing pin based debit cards |
| DirectPayPlatform | string | Name of the direct payment platform if supported |
| %CurrencyObject% | object | Array of currencies supported by merchant. Empty if using a non-multicurrency enabled credit card processor. |
Change Log
| Version | Description |
|---|---|
| 1.2 | Added DebitCardSupport and DirectPayPlatform parameters |
| 1.1 | Soap 1.1 Release |
Address
Contains customer contact information.
This object contains all customer contact information including telephone number, fax number and email address.
Places Used
Properties
Example Object
<?php
// for directions on how to set up the
// WSDL link and create "$token" and "$client,"
// see: [https://help.usaepay.info/developer/soap-api/howto/php/](https://help.usaepay.info/developer/soap-api/howto/php/)
$Address=array(
'City' => 'Los Angeles',
'Company' => 'Usaepay',
'Country' => 'US',
'Email' => 'support@usaepay.com',
'FirstName' => 'PHP5',
'LastName' => 'Example',
'Phone' => '1-866-872-3729',
'State' => 'CA',
'Street' => '5500 Wilshire Blvd',
'Street2' => 'suite 2700',
'Zip' => '90036'
);
$Request=array(
'AccountHolder' => 'Example Creator',
'ClientIP' => '123.123.123.123',
'CustomerID' => '123456',
'Command' => 'Sale',
'Details' => array(
'Amount' => '29.00',
'Clerk' => 'John Doe',
'Currency' => '0',
'Description' => 'Example for address object',
'Discount' => '1.00',
'Invoice' => '44539'),
'BillingAddress' => $Address,
'ShippingAddress' => $Address,
'CreditCardData' => array(
'CardNumber' => '4444555566667779',
'CardExpiration' => '0909',
'AvsStreet' => '1234 Main Street',
'AvsZip' => '99281',
'CardCode' => '999')
);
$Response=$this->client->runTransaction($this->token, $Request);
$TransactionObject=$this->client->getTransaction($this->token, $Response->RefNum);
echo $TransactionObject->BillingAddress->City;
?>
Dim address As usaepay.Address = New usaepay.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
usaepay.CustomerObject customer = new usaepay.CustomerObject();
usaepay.Address address = new usaepay.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;
<BillingAddress xsi:type="ns1:Address">
<City xsi:type="xsd:string">Los Angeles</City>
<Company xsi:type="xsd:string">Usaepay</Company>
<Country xsi:type="xsd:string">US</Country>
<Email xsi:type="xsd:string">support@usaepay.com</Email>
<Fax xsi:type="xsd:string"></Fax>
<FirstName xsi:type="xsd:string">XML</FirstName>
<LastName xsi:type="xsd:string">Example</LastName>
<Phone xsi:type="xsd:string">1-866-872-3729</Phone>
<State xsi:type="xsd:string">CA</State>
<Street xsi:type="xsd:string">5500 Wilshire Blvd</Street>
<Street2 xsi:type="xsd:string">suite 2700</Street2>
<Zip xsi:type="xsd:string">90036</Zip>
</BillingAddress>
| Name | Type | Description |
|---|---|---|
| FirstName | String | Customer's First Name |
| LastName | String | Customer's Last Name |
| Company | String | Company or Organization Name |
| Street | String | Street Address Line 1 |
| Street2 | String | Street Address Line 2 |
| City | String | City |
| State | String | State or Province |
| Zip | String | Zip or Postal Code |
| Country | String | Country |
| Phone | String | Telephone Number |
| Fax | String | Fax Number |
| String | Email Address |
BatchSearchResult
Contains results of a batch search.
This object is returned by the developer:soap:methods:searchBatches method. It describes the result of the search, including the total number of batches matched, the number being returned, and an array of BatchStatus objects
Places Used
Properties
Example Object
Dim result As usaepay.BatchSearchResult = New usaepay.BatchSearchResult
result = client.searchBatches(token, search, matchAll, start, limit, sort)
MsgBox(result.BatchesMatched)
usaepay.BatchSearchResult result = new usaepay.BatchSearchResult();
try
{
result = client.searchBatches(token, search, matchAll, start, limit, sort);
MessageBox.Show(string.Concat(result.BatchesMatched));
}
| Name | Type | Description |
|---|---|---|
| BatchesMatched | integer | Total number of batches matched |
| BatchesReturned | integer | Number of batches returned in this result set |
| StartIndex | integer | The starting index used (defaults to 0) |
| Limit | integer | The max number batches to return in each result set. |
| %BatchStatus% | array | An array BatchStatus objects for the matched batches |
BatchStatus
Contains information about a batch awaiting settlement.
This object contains information about a batch of transactions that has been authorized and is awaiting settlement. It is returned when attempting to determine the status of a batch using the getBatchStatus method.
This should reflect the same information contained in the Batch Manager section of the merchant console.
Places Used
Properties
Example Object
<?php
// for directions on how to set up the
// WSDL link and create "$token" and "$client,"
// see: [https://help.usaepay.info/developer/soap-api/howto/php/](https://help.usaepay.info/developer/soap-api/howto/php/)
$BatchStatus=$this->client->getBatchStatus($this->token, $BatchRefNum);
echo $BatchStatus->Status;
?>
Dim result as usaepay.BatchStatus = New usaepay.BatchStatus
result = client.getBatchStatus(token, BatchRefNum)
MsgBox(result.Status)
usaepay.BatchStatus result = new usaepay.BatchStatus();
try
{
result = client.getBatchStatus(token, BatchRefNum);
MessageBox.Show(string.Concat(result.Status));
}
<getBatchStatusReturn xsi:type="ns1:BatchStatus">
<BatchRefNum xsi:type="xsd:string">1936</BatchRefNum>
<Closed xsi:type="xsd:string"></Closed>
<CreditsAmount xsi:type="xsd:double">0</CreditsAmount>
<CreditsCount xsi:type="xsd:integer">0</CreditsCount>
<NetAmount xsi:type="xsd:double">245</NetAmount>
<Opened xsi:type="xsd:string">04/30/2008T11:26:15</Opened>
<SalesAmount xsi:type="xsd:double">245</SalesAmount>
<SalesCount xsi:type="xsd:integer">20</SalesCount>
<Scheduled xsi:type="xsd:string"></Scheduled>
<Sequence xsi:type="xsd:integer">1</Sequence>
<Status xsi:type="xsd:string">Open</Status>
<TransactionCount xsi:type="xsd:integer">20</TransactionCount>
<VoidsAmount xsi:type="xsd:double">0</VoidsAmount>
<VoidsCount xsi:type="xsd:integer">0</VoidsCount>
</getBatchStatusReturn>
| Name | Type | Description |
|---|---|---|
| BatchKey | string | Batch reference number (assigned by the gateway). |
| BatchRefNum | string | A unique batch reference number assigned by the gateway. |
| Sequence | integer | Batch sequence number |
| Status | string | Status of this batch (ie: open, closing, closed) |
| Opened | string | Date/time the batch was opened (first transaction was run) |
| Closed | string | Date/time the batch was closed (if it has been closed) |
| Scheduled | string | Date/time the batch is scheduled to close |
| TransactionCount | integer | Number of transactions in the batch |
| SalesCount | integer | Number of sales in the batch |
| CreditsCount | integer | Number of credits in the batch |
| VoidsCount | integer | Number of voids in the batch |
| SalesAmount | double | Dollar amount of the sales |
| CreditsAmount | double | Dollar amount of the credits |
| NetAmount | double | Dollar amount of the sales-credits |
| VoidsAmount | double | Dollar amount of the voids |
Change Log
| Version | Description |
|---|---|
| 1.7 | Added BatchKey type string. Changed BatchRefNum to type string |
| 1.2 | Renamed BatchNum Parameter to BatchRefNum |
BatchUploadStatus
Contains information on an uploaded batch.
This object contains details on an uploaded batch and describes the status of a batch of transactions that has been uploaded for authorization.
Places Used
Properties
Example object
<?php
// for directions on how to set up the
// WSDL link and create "$token" and "$client,"
// see: [https://help.usaepay.info/developer/soap-api/howto/php/](https://help.usaepay.info/developer/soap-api/howto/php/)
$BatchUploadStatus = $client->getBatchUploadStatus($this->token, $UploadRefNum);
echo $BatchUploadStatus->Status;
?>
Dim res As usaepay.BatchUploadStatus = New usaepay.BatchUploadStatus
res = client.getBatchUploadStatus(token, uploadrefnum)
MsgBox(res.Status)
try
{
res = client.getBatchUploadStatus(token, uploadrefnum);
MessageBox.Show(string.Concat(res.Status));
}
<getBatchUploadStatusReturn xsi:type="ns1:BatchUploadStatus">
<Approved xsi:type="xsd:integer">0</Approved>
<UploadRefNum xsi:type="xsd:string">440</UploadRefNum>
<Declined xsi:type="xsd:integer">0</Declined>
<Errors xsi:type="xsd:integer">0</Errors>
<Finished xsi:type="xsd:string"></Finished>
<Remaining xsi:type="xsd:integer">102</Remaining>
<Started xsi:type="xsd:string">2008-03-19 09:55:19</Started>
<Status xsi:type="xsd:string">Paused</Status>
<Transactions xsi:type="xsd:integer">102</Transactions>
</getBatchUploadStatusReturn>
| Name | Type | Description |
|---|---|---|
| UploadRefNum | string | Upload reference number (assigned by the gateway). |
| Status | String | Current status of the upload batch. |
| Started | String | Date and time the batch upload was initiated. |
| Finished | String | Date and time the batch upload was completed. |
| Transactions | Integer | Total number of transactions in the upload batch. |
| Remaining | Integer | Number transactions remaining to be run. |
| Approved | Integer | Number of transactions that have been approved. |
| Declined | Integer | Number of transactions that have been declined. |
| Errors | Integer | Number of transactions that resulted in errors. |
Change Log
| Version | Change |
|---|---|
| 1.7 | Changed UploadRefNum to type string |
| 1.2 | Renamed BatchNum parameter to UploadRefNum |
| 1.1 | Soap 1.1 Release |
CheckData
Contains information for electronic check transactions.
This object is used for electronic check processing and includes all of the fields required for processing a check transaction.
Places Used
Properties
Example Object
<?php
// for directions on how to set up the
// WSDL link and create "$token" and "$client,"
// see: [https://help.usaepay.info/developer/soap-api/howto/php/](https://help.usaepay.info/developer/soap-api/howto/php/)
$CheckData=array(
'CheckNumber' => '321',
'Account' => '123456',
'Routing' => '123456789',
'AccountType' => 'Savings',
'DriversLicense' => '123123123',
'DriversLicenseState' => 'NA',
'RecordType' => 'ARC'
);
$Request=array(
'AccountHolder' => 'Example Creator',
'ClientIP' => '123.123.123.123',
'CustomerID' => '123456',
'Command' => 'Check',
'Details' => array(
'Amount' => '29.00',
'Clerk' => 'John Doe',
'Currency' => '0',
'Description' => 'Example for CheckData object',
'Discount' => '1.00',
'Invoice' => '44539'),
'CheckData' => $CheckData
);
$Response=$this->client->runTransaction($this->token, $Request);
$TransactionObject=$this->client->getTransaction($this->token, $Response->RefNum);
echo $TransactionObject->CheckData->AccountType;
?>
Dim tran As usaepay.TransactionRequestObject = new usaepay.TransactionRequestObject
Dim CheckData As usaepay.CheckData = new usaepay.CheckData
CheckData.Account = "1112223333"
CheckData.Routing = "123456789"
CheckData.DriversLicense = "D5555555"
CheckData.DriversLicenseState = "CA"
tran.CheckData = CheckData
usaepay.TransactionRequestObject tran = new usaepay.TransactionRequestObject();
tran.CheckData = new usaepay.CheckData();
tran.CheckData.Account = "1112223333";
tran.CheckData.Routing = "123456789";
tran.CheckData.DriversLicense = "D5555555";
tran.CheckData.DriversLicenseState = "CA";
<CheckData xsi:type="ns1:CheckData">
<Account xsi:type="xsd:string">XXXXX3456</Account>
<AccountType xsi:type="xsd:string">Savings</AccountType>
<CheckNumber xsi:type="xsd:integer">321</CheckNumber>
<DriversLicense xsi:type="xsd:string">XXXXX3123</DriversLicense>
<DriversLicenseState xsi:type="xsd:string">NA</DriversLicenseState>
<RecordType xsi:type="xsd:string">ARC</RecordType>
<Routing xsi:type="xsd:string">XXXXX6789</Routing>
</CheckData>
| Name | Type | Description |
|---|---|---|
| CheckNumber | Integer | Check number of check being used for transaction. |
| Routing | String | Nine digit bank routing number. |
| Account | String | Bank account number. |
| AccountType | String | Checking or Savings - if left blank, default is Checking. |
| DriversLicense | String | Driver's license of checking account holder. |
| DriversLicenseState | String | Driver's license state of issue. |
| RecordType | String | Record type of electronic check transaction. Not supported by all check processors. List of Check Record Types |
| MICR | String | MICR Data for Check 21 (optional, depending on processor) |
| AuxOnUS | String | MICR Data for Check 21 (optional, depending on processor) |
| EpcCode | String | MICR Data for Check 21 (optional, depending on processor) |
| FrontImage | String | Scan of front of check, base64 encoded (optional) |
| BackImage | String | Scan of back of check, base64 (optional) |
| SSN | String | Customer Social Security Number |
Change Log
| Version | Change |
|---|---|
| 1.7 | Added SSN, ImageEncoding |
CheckTrace
Electronic check transaction tracking data.
Tracking data for an electronic check transaction that provides the details and status of a check transaction.
Check transactions can change status several times, including being returned by the customer's bank. Make sure to check the status of a transaction for 1-2 weeks after a transaction has posted. Typically the reason for a return will be contained in the BankNote parameter.
Properties
Example Object
Dim trace As usaepay.CheckTrace = New usaepay.CheckTrace
trace = client.getCheckTrace(token, refnum)
MsgBox("Tracking Number: " & trace.TrackingNum)
usaepay.CheckTrace trace = new usaepay.CheckTrace();
try
{
trace = client.getCheckTrace(token,refnum);
MessageBox.Show(string.Concat(trace.TrackingNum));
}
| Name | Type | Description |
|---|---|---|
| Status | string | Text description of the status code. |
| StatusCode | string | A single letter code indicating the status of a transaction. |
| TrackingNum | string | Reference number assigned by check processor. |
| Effective | string | Date check was originally posted. |
| Processed | string | Date check was received by processor. |
| Settled | string | Date check was originally settled. |
| Returned | string | Date check was returned. |
| ReturnCode | string | |
| Reason | string | |
| BankNote | string | Note from checking account holder's bank. Typically this note will explain the reason for a returned check, but it may also indicate future changes to routing/account number even if the electronic check transaction was approved. For example, if the customer's bank has been bought by another bank, the original routing number will only remain valid for about a year. During this period, the bank will send back a note indicating the new routing number. |
CreditCardData
This object contains credit card specific information for a transaction.
When retrieving stored CreditCardData from the gateway with a function like getTransaction, many of the properties such as CardNumber, CardExpiration and MagStripe will be masked for security reasons. Full, unmasked, credit card data can not be retrieved via the Soap API.
Places Used
Properties
Example Object
<?php
// for directions on how to set up the
// WSDL link and create "$token" and "$client,"
// see: [https://help.usaepay.info/developer/soap-api/howto/php/](https://help.usaepay.info/developer/soap-api/howto/php/)
$CreditCardData=array(
'CardNumber' => '4444555566667779',
'CardExpiration' => '0909',
'AvsStreet' => '1234 Main Street',
'AvsZip' => '99281',
'CardCode' => '999'
);
$Request=array(
'AccountHolder' => 'Example Creator',
'ClientIP' => '123.123.123.123',
'CustomerID' => '123456',
'Command' => 'Sale',
'Details' => array(
'Amount' => '29.00',
'Clerk' => 'John Doe',
'Currency' => '0',
'Description' => 'Example for CreditCardData object',
'Discount' => '1.00',
'Invoice' => '44539'),
'CreditCardData' => $CreditCardData
);
$Response=$this->client->runTransaction($this->token, $Request);
$TransactionObject=$this->client->getTransaction($this->token, $Response->RefNum);
echo $TransactionObject->CreditCardData->AvsZip;
?>
Dim tran As usaepay.TransactionRequestObject = New usaepay.TransactionRequestObject
tran.CreditCardData = New usaepay.CreditCardData
tran.CreditCardData.CardNumber = "4444555566667779"
tran.CreditCardData.CardExpiration = "0913"
tran.CreditCardData.CardCode = "999"
usaepay.TransactionRequestObject tran = new usaepay.TransactionRequestObject();
tran.CreditCardData = new usaepay.CreditCardData();
tran.CreditCardData.CardNumber = "4444555566667779";
tran.CreditCardData.CardExpiration = "0909";
<CreditCardData xsi:type="ns1:CreditCardData">
<AvsStreet xsi:type="xsd:string">1234 Main Street</AvsStreet>
<AvsZip xsi:type="xsd:string">99281</AvsZip>
<CardCode xsi:type="xsd:string">XXX</CardCode>
<CardExpiration xsi:type="xsd:string">XXXX</CardExpiration>
<CardNumber xsi:type="xsd:string">XXXXXXXXXXXX7779</CardNumber>
<CardPresent xsi:type="xsd:boolean">false</CardPresent>
<CardType xsi:type="xsd:string">V</CardType>
<DataSource xsi:type="xsd:string">Contactless</DataSource>
<InternalCardAuth xsi:type="xsd:boolean">false</InternalCardAuth>
<MagStripe xsi:type="xsd:string"></MagStripe>
<MagSupport xsi:type="xsd:string"></MagSupport>
<Pares xsi:type="xsd:string"></Pares>
<TermType xsi:type="xsd:string"></TermType>
</CreditCardData>
| Name | Type | Description |
|---|---|---|
| CardType | string | Card Type - describes card issuer (Visa, MC, Amex, Discover). Read only property (ignored if sent as a parameter to transaction methods). |
| CardNumber | string | Card Number |
| CardExpiration | string | Expiration Date - Should be set to 4 digit MMYY. |
| CardCode | string | CVV2/CID card code value from back of card. Set to -2 if the code is not legible, -9 if the code is not on the card. |
| AvsStreet | string | Billing address associated with card, used by AVS. |
| AvsZip | string | Billing zipcode associated with card, used by AVS. |
| CardPresent | boolean | Indicates if the card is present during the transaction (ie: the card was swiped at a POS terminal). Used to indicate retail. |
| MagStripe | string | Track 1 and/or Track 2 data for swiped transactions. For unencrypted swipers send the raw data. For encrypted swipers please look at end to end encryption |
| DataSource | string | Entry mode of transaction. (Contactless, Card Not Present- Manually Keyed, Card Swiped, Chip Read) |
| DUKPT | string | DUKPT encrypted pin block. Only required for pin debit transactions. The first 16 characters are the encrypted pin block, followed by the 6 character long Key Set Identifier (KSID). The remaining characters are the Pin Pad serial number and transaction counter. |
| Signature | string | Signature capture image. Base64 encoded. |
| TermType | string | Terminal type (POS, StandAlone, Unattended, or Unkown). May be left blank if unknown. |
| MagSupport | string | Indicates whether software has support for mag swipe (Yes, No, Unknown). |
| XID | string | XID value received from 3rd party Visa VPAS or MC UCAF. |
| CAVV | string | CAVV value received from 3rd party Visa VPAS or MC UCAF. |
| ECI | integer | ECI value. |
| InternalCardAuth | boolean | Use gateway based authentication for Visa VPAS or MC UCAF. |
| Pares | string | Pares returned by client after successful |
Change Log
| Version | Change |
|---|---|
| 1.7 | Added DataSource type String(Return Only) |
| 1.1 | Added DUKPT parameter for pin-debit transactions, Signature parameter for signature capture. |
CreditCardToken
This object describes a tokenized credit card.
Places Used
Properties
| Name | Type | Description |
|---|---|---|
| CardRef | string | Unique token representing card |
| CardExpiration | string | Expiration Date of credit card |
| CardNumber | string | Masked card number |
| CardType | string | Type of card |
Change Log
| Version | Description |
|---|---|
| 1.6 | Object added in this version. |
CurrencyObject
Describes a currency supported by the merchant's account.
This object describes a currency supported by the merchant. For a full list of all currencies supported by the gateway see the Currency Code list.
To add support for additional currencies to your account, please contact customer service.
Places Used
Properties
Example Object
<?php
// for directions on how to set up the
// WSDL link and create "$token" and "$client,"
// see: [https://help.usaepay.info/developer/soap-api/howto/php/](https://help.usaepay.info/developer/soap-api/howto/php/)
//Note: getSupportedCurrencies returns an array of currency
//objects. Not a single object with all supported currencies.
$CurrencyObjects=$this->client->getSupportedCurrencies($this->token);
echo $CurrencyObjects[0]->Currency;
?>
Dim response() As usaepay.CurrencyObject
response = client.getSupportedCurrencies(token)
MsgBox(response.Length)
try
{
usaepay.CurrencyObject[] currency = client.getSupportedCurrencies(token);
MessageBox.Show(string.Concat(currency.Length));
}
<item xsi:type="ns1:CurrencyObject">
<Currency xsi:type="xsd:string">Australian Dollars</Currency>
<DecimalPlaces xsi:type="xsd:integer">2</DecimalPlaces>
<NumericCode xsi:type="xsd:integer">36</NumericCode>
<Rate xsi:type="xsd:double">1.1284389176</Rate>
<TextCode xsi:type="xsd:string">AUD</TextCode>
</item>
| Name | Type | Description |
|---|---|---|
| NumericCode | integer | 3 digit numeric currency code to be used when processing transactions in the corresponding currency. |
| TextCode | string | 3 character currency code (ie: USD or EUR). |
| Currency | string | Full name of currency (ie: US Dollars or Euros). |
| Rate | double | Currency's current conversion rate. This is the conversion rate to the merchant's specified settling currency. |
| DecimalPlaces | integer | Number of positions to the right of the decimal (or whole units separator). Used for rounding (ie for USD 12.88, DecimalPlaces=2, for Japanese Yen 512 DecimalPlaces=0). |
CustomerObject
Contains customer data.
This object contains all relevant customer data including the CustNum (a unique customer number assigned by the gateway), CustID (a merchant assigned customer ID), as well as customer name, address, recurring billing status and schedule, and any other relevant data.
Places Used
Properties
<?php
// for directions on how to set up the
// WSDL link and create "$token" and "$client,"
// see: [https://help.usaepay.info/developer/soap-api/howto/php/](https://help.usaepay.info/developer/soap-api/howto/php/)
$CustomerObject=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'=>'support@usaepay.com',
'Phone'=>'333-333-3333',
'Fax'=>'333-333-3334'
),
'PaymentMethods' =>
array(
array(
'CardNumber'=>'4444555566667779',
'CardExpiration'=>'0918',
'CardType'=>'',
'CardCode'=>'',
'AvsStreet'=>'',
'AvsZip'=>'',
'CardPresent'=>'',
'MagStripe'=>'',
'TermType'=>'',
'MagSupport'=>'',
'XID'=>'',
'CAVV'=>'',
'ECI'=>'',
'InternalCardAuth'=>'',
'Pares'=>'',
"Expires"=>"",
"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',
'CustNum'=>'C'.rand()
);
$CustomerNumber=$this->client->addCustomer($this->token,$CustomerObject);
$CustomerObject= $this->client->getCustomer($this->token, $CustomerNumber);
echo $CustomerObject->CustNum;
?>
<getCustomerReturn xsi:type="ns1:CustomerObject">
<Amount xsi:type="xsd:double">1.00</Amount>
<BillingAddress xsi:type="ns1:Address">
<City xsi:type="xsd:string">Los Angeles</City>
<Company xsi:type="xsd:string">UsaEpay</Company>
<Country xsi:type="xsd:string">US</Country>
<Email xsi:type="xsd:string">support@usaepay.com</Email>
<Fax xsi:type="xsd:string">333-333-3334</Fax>
<FirstName xsi:type="xsd:string">Example</FirstName>
<LastName xsi:type="xsd:string">Generator</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>
<CustNum xsi:type="xsd:string">21727</CustNum>
<CustomData xsi:type="xsd:string">
</CustomData>
<CustomFields SOAP-ENC:arrayType="ns1:FieldValue[2]" xsi:type="ns1:FieldValueArray">
<item xsi:type="ns1:FieldValue">
<Field xsi:type="xsd:string">Example</Field>
<Value xsi:type="xsd:string">Field</Value>
</item>
</CustomFields>
<CustomerID xsi:type="xsd:string">156244967</CustomerID>
<Created xsi:type="xsd:string">2008-05-08 13:40:35</Created>
<Description xsi:type="xsd:string">Weekly Bill</Description>
<Enabled xsi:type="xsd:boolean">false</Enabled>
<Modified xsi:type="xsd:string">2008-05-08 13:40:35</Modified>
<Next xsi:type="xsd:string">2012-01-21T12:00:00</Next>
<Notes xsi:type="xsd:string">Any notes go here</Notes>
<NumLeft xsi:type="xsd:integer">50</NumLeft>
<OrderID xsi:type="xsd:string">1707022452</OrderID>
<PaymentMethods SOAP-ENC:arrayType="ns1:PaymentMethod[1]" xsi:type="ns1:PaymentMethodArray">
<item xsi:type="ns1:PaymentMethod">
<CheckData xsi:type="ns1:CheckData">
<Account xsi:nil="true"/>
<Routing xsi:nil="true"/>
</CheckData>
<CreditCardData xsi:type="ns1:CreditCardData">
<AvsStreet xsi:type="xsd:string">1234 main st</AvsStreet>
<AvsZip xsi:type="xsd:string">12345</AvsZip>
<CardExpiration xsi:type="xsd:string">XXXX</CardExpiration>
<CardNumber xsi:type="xsd:string">XXXXXXXXXXXX7779</CardNumber>
<CardType xsi:type="xsd:string">V</CardType>
</CreditCardData>
<Expires xsi:type="xsd:string">2008-05-08</Expires>
<MethodID xsi:type="xsd:string">7353</MethodID>
<MethodName xsi:type="xsd:string">My Visa</MethodName>
<SecondarySort xsi:type="xsd:integer">1</SecondarySort>
</item>
</PaymentMethods>
<ReceiptNote xsi:type="xsd:string">Example Receipt Note</ReceiptNote>
<Schedule xsi:type="xsd:string">Weekly</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">(Auto)</User>
</getCustomerReturn>
usaepay.CustomerObject customer = new usaepay.CustomerObject();
usaepay.Address address = new usaepay.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";
usaepay.PaymentMethod[] payMethod = new usaepay.PaymentMethod[1];
payMethod[0] = new usaepay.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 customer As usaepay.CustomerObject = New usaepay.CustomerObject
Dim address As usaepay.Address = New usaepay.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 usaepay.PaymentMethod
payMethod(0) = New usaepay.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
| Name | Type | Description |
|---|---|---|
| CustNum | string | Customer Number (System assigned) |
| CustKey | string | Customer Number (System assigned) |
| CustomerID | string | Customer ID (Merchant assigned) |
| %BillingAddress% | object | Billing Address |
| %PaymentMethod% | array | Array of PaymentMethod objects. Multiple credit cards or ACH accounts may be stored for each customer. |
| Notes | string | Notes (visible to merchant only). |
| CustomData | string | Custom data is a raw text field, please serialize and encode (ie: base64) your data so that complex types are stored and retrieved correctly. |
| %CustomFields% | array | Array of field values containing the merchant defined customer fields. These fields are defined in the merchant console. |
| URL | string | URL for customers website |
| Created | string | Date/Time customer was created (Read Only) |
| Modified | string | Date/Time customer was last changed (Read Only) |
| Enabled | boolean | Notes whether or not a customer has been enabled for a recurring billing cycle. The customer billing does not need to be enabled to run one time transactions via the runCustomerTransaction method. |
| Schedule | string | Recurring billing schedule, if any. Possible values include: daily, weekly, bi-weekly (every two weeks), monthly, bi-monthly (every two months), quarterly, bi-annually (every six months), annually, first of month, last day of month. |
| NumLeft | string | Number of transactions remaining in customer's recurring billing cycle. "-1" indicates unlimited transactions. |
| Next | string | Date of customer's next scheduled transaction. |
| Amount | double | Total Amount to be billed in recurring billing cycle. |
| Tax | double | Portion of Amount that is Tax |
| Currency | string | Numeric currency code for Amount. (Only needed if multicurrency merchant account) |
| Description | string | Description of transaction. |
| OrderID | string | Transaction Order ID |
| User | string | Merchant username assigned to billing. |
| Source | string | Name of source key assigned to billing. |
| SendReceipt | boolean | Send client a receipt. |
| ReceiptNote | string | Note to send on receipt. |
| Failures | integer | Number of failures since last approval. |
| PriceTier | string | Name of customer price tier |
| TaxClass | string | Tax Class (Group) |
| LookupCode | string | Lookup code from customer/member id card. Either barcode or Magnetic stripe. Can be assigned by merchants. Defaults to system assigned if left blank. |
Change Log
| Version | Change |
|---|---|
| 1.7 | Added Custkey type string |
CustomerSearchResult
Contains customer search data.
This object is returned by the searchCustomers method. It describes the result of the search, including the total number of customers matched, the number being returned, and an array of CustomerObjects.
Places Used
Properties
Example Object
Dim response As usaepay.CustomerSearchResult = New usaepay.CustomerSearchResult
response = client.searchCustomers(token, search, matchAll, "0", "10", "fname")
MsgBox(response.CustomersMatched)
usaepay.CustomerSearchResult response = new usaepay.CustomerSearchResult();
try
{
response = client.searchCustomers(token, search, matchAll, "0", "10", "fname");
MessageBox.Show(response.CustomersMatched);
}
| Name | Type | Description |
|---|---|---|
| CustomersMatched | integer | Total number of customers matched by search criteria. |
| CustomersReturned | integer | Total number of customers contained in search result. |
| StartIndex | integer | The index where this result set begins (default is 0). |
| Limit | integer | The maximum number of customers to be returned in the search. |
| %CustomerObject% | array | An array of CustomerObjects matched by search criteria. |
Change Log
| Version | Description |
|---|---|
| 1.1 | Method added prior to soap-1.1 |
CustomerTransactionRequest
Used to run a new customer transaction.
This object contains the data needed to run a new stored customer transaction.
Places Used
Properties
Example Object
| Name | Type | Description |
|---|---|---|
| Command | string | Processing command to run. Possible values: Sale, AuthOnly, Credit, Check and CheckCredit. If a blank is passed, the default value is Sale for credit card or Check for checks |
| IgnoreDuplicate | boolean | Do not check for duplicate transaction. Set to "true" if you would like to override the duplicate transaction handling. |
| %Details% | object | Transaction details: amount, clerk, currency, |
| ClientIP | string | IP Address of client. |
| CustReceipt | boolean | Customer Receipt. Set to "true" if you would like the gateway to send an email to customer. |
| CustReceiptEmail | string | Email address to receipt to. If left blank, the receipt will be sent to the email address stored in the customer record. |
| CustReceiptName | string | Customer Receipt Template Name. Specify the name of the template to use. (Optional) |
| MerchReceipt | boolean | Send Merchant Receipt. Set to "true" if you would like the gateway to send a receipt to the merchant. |
| MerchReceiptEmail | string | Email address to receipt to. Required if MerchReceipt is set to true |
| MerchReceiptName | string | Merchant Receipt Template Name. Specify the name of the template to use. (Optional) |
| %CustomFields% | array | Array of FieldValue pairs. Additional transaction api fields (ie UMtimeout) can also be passed in via this array. Any field name starting with UM is assumed to be an api field and not a custom field. |
| isRecurring | boolean | Recurring flag Signals to the platform that this transaction is a recurring billing transaction. Use with caution, can cause downgrades if not used properly. Defaults to false which causes the transaction to run as a normal card not present transaction. |
| InventoryLocation | string | ID of warehouse to draw inventory from. If blank, uses setting from source key. If no setting in source key, inventory will not be adjusted. |
| CardCode | string | CVV2/CVC card id code. PCI requirements forbid storing CVV2 value. Customer must be prompted to enter this value each time a transaction is run. This value is not required unless CVV2 validation is desired. |
| %LineItem% | array | Array of line item details |
| Software | string | Free form string that can be used by the developer to record information about their software, version, build number or operating system details. Reported on the transaction detail screen, in custom reports or via api. (optional) |
| XID | string | XID value received from 3rd party Visa VPAS or MC UCAF. Can be sent with transaction, but cannot be stored in method. |
| CAVV | string | CAVV value received from 3rd party Visa VPAS or MC UCAF. Can be sent with transaction, but cannot be stored in method. |
| ECI | integer | ECI value. Can be sent with transaction, but cannot be stored in method. |
Change Log
| Version | Description |
|---|---|
| 1.7 | Added Custkey type string. Added CAVV and 3DSecure method fields. |
FieldValue
Generalized Field-Value Pair
This object is used by several methods that do not have a fixed list of parameters, like runTransaction. See the documentation of the specific method for the valid field names. (Methods using this object are listed below.)
Places Used
Properties
Dim Fields(0 To 9) As usaepay.FieldValue
Dim i As Integer
For i = 0 To 9
Fields(i) = New usaepay.FieldValue
Next i
Fields(0).Field = "UMname"
Fields(0).Value = "Tester Jones"
Fields(1).Field = "UMdescription"
Fields(1).Value = "Visual Basic For Dummies"
Fields(2).Field = "UMamount"
Fields(2).Value = "1.00"
Fields(3).Field = "UMinvoice"
Fields(3).Value = "12345"
Fields(4).Field = "UMcard"
Fields(4).Value = "4444555566667779"
Fields(5).Field = "UMexpir"
Fields(5).Value = "1212"
Fields(6).Field = "UMstreet"
Fields(6).Value = "1234 Main Street"
Fields(7).Field = "UMzip"
Fields(7).Value = "90210"
Fields(8).Field = "UMcvv2"
Fields(8).Value = "999"
usaepay.FieldValue[] tran = new usaepay.FieldValue[9];
for (int i = 0; i < 9; i++)
{
tran[i] = new usaepay.FieldValue();
}
tran[0].Field = "UMname"; tran[0].Value = "Tester Jones";
tran[1].Field = "UMdescription"; tran[1].Value = "runTransactionAPI sale";
tran[2].Field = "UMamount"; tran[2].Value = "1.00";
tran[3].Field = "UMinvoice"; tran[3].Value = "12345";
tran[4].Field = "UMcard"; tran[4].Value = "4444555566667779";
tran[5].Field = "UMexpir"; tran[5].Value = "1212";
tran[6].Field = "UMstreet"; tran[6].Value = "123 Main Street";
tran[7].Field = "UMzip"; tran[7].Value = "90046";
tran[8].Field = "UMcvv2"; tran[8].Value = "999";
| Name | Type | Description |
|---|---|---|
| Field | string | Name of element. |
| Value | string | Value of element. |
LineItem
Contains elements needed for line item data.
Merchants can pass information about the individual line items that make up an order. This data is visible on the transaction details page. Up to 100 lines may be stored per transaction.
All fields must be passed, but may be left blank if not applicable.
Properties
Example Object
Dim line as usaepay.LineItem = new usaepay.Lineitem
line.SKU = "123456"
line.ProductRefNum = "90476"
line.ProductName = "QuickBook"
line.Description = "test"
line.UnitPrice = "100"
line.Qty = "5"
usaepay.LineItem line = new usaepay.Lineitem();
line.SKU = "123456";
line.ProductRefNum = "90476";
line.ProductName = "QuickBook";
line.Description = "test";
line.UnitPrice = "100";
line.Qty = "5";
| Name | Type | Description |
|---|---|---|
| ProductRefNum | string | Unique ID of the product assigned by the gateway (Optional) |
| ProductKey | string | Unique ID of the product assigned by the gateway |
| SKU | string | A stock-keeping unit is a unique identifier for each distinct product and service that can be purchased |
| ProductName | string | Name of the product |
| Description | string | Description of product or purchase |
| UnitPrice | string | Individual price of the unit |
| Qty | string | Total number of items |
| Taxable | boolean | Taxable good flag |
| CommodityCode | string | Numeric code used to classify the good or service. See the UNSPSC for codes. (Level 3) |
| UnitOfMeasure | string | Unit that quantity is measuring. Defaults to "EA". See list of valid Unit of Measure Codes (Level 3) |
| DiscountAmount | string | Amount line item was discounted (Level 3) |
| DiscountRate | string | The rate used to calculate discount (Level 3) |
| TaxAmount | string | Tax charged for this line item (Level 3) |
| TaxRate | string | The tax rate used for this line item (Level 3) |
The properties noted as "Level 3" are only necessary if merchant is processing level 3 data for business or corporate purchasing cards.
Change History
| Version | Change |
|---|---|
| 1.7 | Added ProductKey type string |
Lodging Details
Contains elements needed for lodging details for a transaction.
Merchants in the Hotel/Lodging industry may need to pass through specific details about a transactions. Below are the fields for each.
Properties
| Name | Type | Description |
|---|---|---|
| Folio | string | Guest account reference number |
| RoomRate | string | Rate of room |
| Nights | string | How many nights the reservation is for |
| CheckInDate | string | Date guest will check in. |
| CheckOutDate | string | Date guest will check out. |
| ExtraChargeReasons | string | Comment field denoting why guest was charged extra. |
| RoomNumber | string | Guests room number |
| CustomerCode | string | Reference number for the guest |
| LengthOfStay | string | How long the guest will be staying |
| RoomTaxRate | string | Tax percentage for the room type booked. |
| NonRoomCharges | string | Any charges made outside of the booking costs. (Room Service, etc.) |
| RoomTaxAmount | string | Tax amount in dollars for the room. |
| PreferredCustomer | string | Denotes if this guest is a preferred customer. |
| ChargeType | string | Denotes how guest paid for the room. |
| DepartureTime | string | Time and date guest departed. |
| ArrivalTime | string | Time and date the guest arrived |
Change History
| Version | Change |
|---|---|
| 1.7 | Added Object. |
PaymentMethod
Describes a customer payment method.
This object describes a customer payment method. A payment method can be a CreditCard, ACH (Electronic Check), StoredValue (gift certificate, store credit, auto-reloading prepaid card, etc), and Invoice. The payment type is specified by setting MethodType to 'CreditCard', 'ACH', 'StoredValue' or 'Invoice'. If MethodType is left blank and credit card information is provided, the type will default to 'CreditCard'. If MethodType is left blank and electronic check information is provided, the type will default to 'ACH'.
The StoredValue method can be as simple as a store credit or as complex as linking to a physical pre-paid card or gift card with a magnetic strip. For a store credit or simple balance on account, the only required field is Balance. To use the StoredValue payment method, the merchant account must have stored value transactions enabled.
The Invoice method allows a merchant to collect transactions that will be invoice at a later date. Balance is increased by the system when an Invoice transaction is received. MaxBalance specifies that maximum balance that a customer can incur before Invoice transactions are declined. Setting MaxBalance to 0 will cause the customer to have no limit. To process Invoice transactions, the merchant account must have Invoice processing enabled.
Places Used
Properties
Example Object
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"
usaepay.PaymentMethod payMethod = new usaepay.PaymentMethod();
payMethod.CardExpiration = "1212";
payMethod.CardNumber = "4000100011112224";
payMethod.AvsStreet = "123 Main st.";
payMethod.AvsZip = "90046";
payMethod.MethodName = "My Visa";
| Name | Type | Description |
|---|---|---|
| MethodType | string | Type of payment method (CreditCard, ACH, StoredValue or Invoice) |
| MethodID | string | ID of payment method. This property is ignored when adding a new payment method but required if updating an existing method. |
| MethodName | string | Label for payment method. For example "Work Visa" or "Personal Checking." |
| SecondarySort | integer | If set to value greater than 0, use this method as backup in case default fails. Secondary methods will be run in ascending order. |
| Created | string | Date and time the method was created. |
| Modified | string | Date and time the method was last modified. |
| Expires | string | Date on which payment method will expire. Do not leave blank. Format: YYYY-MM-DD |
| CardHolder | string | Name of the card holder on credit/debit card. |
| CardNumber | string | Credit card number (required for credit cards). If data is coming from a swiper, base64_encode the entire raw block read from the swiper device and put %%enc://%% at the beginning. Example: %%enc://%%AAbbCdEEaa... |
| CardExpiration | string | Credit card expiration date in YYYY-MM format. It will also accept MMYY format. (required for credit cards) |
| AvsStreet | string | Street address for AVS (address verification system). (Optional but recommended for credit cards) |
| AvsZip | string | Zip code for AVS. (Optional but recommended for credit cards) |
| CardCode | string | CVV2/CID card identification code. This code is not stored and is only used when verifying a new payment method before it is added. (Optional for credit cards) |
| CardType | string | Type of credit card (Visa, Mastercard, etc). This is a read only parameter and will be ignored if set. |
| XID | string | XID value received from 3rd party Visa VPAS or MC UCAF. Can be sent with transaction, but cannot be stored in method. |
| CAVV | string | CAVV value received from 3rd party Visa VPAS or MC UCAF. Can be sent with transaction, but cannot be stored in method. |
| ECI | integer | ECI value. Can be sent with transaction, but cannot be stored in method. |
| Account | string | ACH Bank Account Number (required for checks) |
| AccountType | string | ACH Type of Bank Account (Checking or Savings, defaults to checking) |
| Routing | string | ACH Bank Routing Number (required for checks) |
| DriversLicense | string | Drivers license number used for check guarantee (optional) |
| DriversLicenseState | string | Drivers license state (optional) |
| RecordType | string | ACH transaction type (optional, should be left blank unless instructed differently by check processor) |
| MaxBalance | double | The maximum balance that may be charged on Invoice before transactions are declined |
| Balance | double | The funds left on the account. Transactions against this payment method may not exceed this balance |
| AutoReload | boolean | Set true if StoredValue card should automatically be reloaded |
| ReloadSchedule | string | Automatic reload schedule |
| ReloadThreshold | double | Balance that will trigger an automatic reload |
| ReloadAmount | double | Amount to automatically reload |
| ReloadMethodID | string | Payment method to use for reloading card |
Change Log
| Version | Description |
|---|---|
| 1.7 | Added CAVV and 3DSecure method fields. Added CardHolder field. |
| 1.4 | Add MethodType, Balance, MaxBalance, AutoReload, ReloadSchedule, ReloadThreshold, ReloadAmount, ReloadMethodID |
| 1.3 | Dropped CreditCardData and CheckData. Added Account, AccountType, DriversLicense, DriversLicenseState, RecordType, Routing, AvsStreet, AvsZip, CardCode, CardExpiration, CardNumber and CardType |
| 1.2 | Added the Created and Modified Parameters |
| 1.1 | Soap 1.1 Release |
PriceTier
Object describing a product price tier.
This object represents a variable pricing tier. There are two types of price tiers: general pricing and customer specific pricing. Both types implement qty thresholds. For example, buy 1 for $9.99 or buy 10 for $8.99 each. For general price tiers the 'CustomerTier' parameter should be omitted or left blank. An example price tier for a product with a base price of 199.99 might look like:
| Qty | Price |
|---|---|
| 10 | 189.99 |
| 50 | 169.99 |
| 100 | 149.99 |
If a customer purchased up to 9 qty of this item, the price would be $199.99 each. If they purchased from 11 to 49 the price would be $189.99 each. From 50 to 99 would be $169.99 each. 100 and above would be $149.99 each.
A customer price tier allows customer specific pricing to be set. This is done by creating price tiers with the 'CustomerTier' parameter set. The value of 'CustomerTier' is flexible and can be set to any string up to 32 characters. A customer will receive this pricing if they have a matching PriceTier parameter set on the CustomerObject. Multiple customers can be assigned to the PriceTier. An example customer price tier table for a product with a base price of $199.99:
| CustomerTier | Qty | Price |
|---|---|---|
| Distributor | 1 | 129.99 |
| Distributor | 50 | 109.99 |
| Distributor | 100 | 99.99 |
| Employee | 1 | 99.99 |
Places Used
Properties
| Name | Type | Description |
|---|---|---|
| Qty | string | Qty threshold for price |
| Price | string | Product Price |
| CustomerTier | string | Customer based price tier identifier |
Change Log
| Version | Description |
|---|---|
| 1.4 | Object added in 1.4 release |
Product
Object describing a product.
This object contains all of the data needed for adding, updating, and deleting a product on the gateway.
Places Used
Properties
| Name | Type | Description |
|---|---|---|
| ProductRefNum | string | Gateway assigned ID of product |
| ProductKey | string | Unique ID of the product assigned by the gateway |
| ProductID | string | Merchant assigned product ID |
| Category | string | Product category |
| SKU | string | Stock-Keeping Unit |
| UPC | string | Universal Product Code |
| Enabled | boolean | Enables the ability to store products |
| Name | string | Name of the product |
| Description | string | Product description |
| Model | string | Model of the product |
| Weight | string | Weight of the product |
| ShipWeight | string | Shipping weight of the product |
| Price | double | Price of the product |
| WholesalePrice | double | Wholesale price of the product |
| ListPrice | double | List price of the product |
| %PriceTier% | object | Qty and Customer based variable pricing tiers |
| TaxClass | string | Product's Tax Class |
| DateAvailable | string | Date the product is available for sale |
| Manufacturer | string | Maker of the product |
| PhysicalGood | boolean | Tangible/Shippable good. |
| MinQuantity | integer | Minimum quantity allowed |
| ImageURL | string | URL address of the product image |
| URL | string | URL of the product |
| %ProductInventory% | object | Product inventory levels |
| Modified | string | Date/time the product was last changed |
| Created | string | Date/time the product was created |
Change Log
| Version | Description |
|---|---|
| 1.7 | Added ProductKey type string |
ProductCategory
Object describing a product category.
This object represents a product category which is a container for products. Currently product categories can not be nested.
Places Used
- addProductCategory
- deleteProductCategory
- getProductCategory
- getProductCategories
- updateProductCategory
Properties
| Name | Type | Description |
|---|---|---|
| ProductCategoryRefNum | string | Gateway assign unique reference number |
| ProductCategoryKey | string | Gateway assign unique reference number |
| Name | string | Name of product category |
| Created | string | Timestamp for when the category was created |
| Modified | string | Timestamp for when the category was last modified |
Change Log
| Version | Description |
|---|---|
| 1.7 | ProductCategoryKey added. |
| 1.3 | Object added in 1.3 release |
ProductInventory
Object describing a product inventory at a given location.
This object represents the current inventory counts for a given location.
Places Used
Properties
| Name | Type | Description |
|---|---|---|
| InventoryLocationKey | string | Gateway assign unique reference number |
| InventoryLocation | string | Location of Inventory (Warehouse or location name) |
| QtyOnHand | string | Count of available units in stock |
| QtyOnOrder | string | Count of units on order (scheduled to be available on DateAvailable) |
| DateAvailable | string | Date that QtyOnOrder is scheduled to arrive |
Change Log
| Version | Description |
|---|---|
| 1.3 | Object added in 1.3 release |
ProductSearchResult
Contains results of a products search. It describes the result of the search, including the total number of products matched, the number being returned, and an array of Product Objects.
Places Used
Properties
| Name | Type | Description |
|---|---|---|
| ProductsMatched | integer | Total number of transactions matched |
| ProductsReturned | integer | Number of transactions returned in this result set |
| StartIndex | integer | The starting index used (defaults to 0) |
| Limit | integer | The max number transactions to return in each result set. |
| %Product% | array | An array Products for the matched criteria |
Receipt
Object describing a receipt template.
This object contains all of the data needed for adding or updating a receipt template on the gateway.
Places Used
Properties
Dim receipt As usaepay.Receipt = New usaepay.Receipt
receipt.Name = "test receipt_VB"
receipt.Target = "email"
receipt.Subject = "test receipt"
receipt.FromEmail = "devsupport@usaepay.com"
receipt.ContentType = "text"
usaepay.Receipt receipt = new usaepay.Receipt();
receipt.Name = "test receipt";
receipt.Target = "email";
receipt.Subject = "test receipt";
receipt.FromEmail = "devsupport@usaepay.com";
receipt.ContentType = "text";
string message = "Yippy Skippy";
byte[] toencodeAsBytes = System.Text.ASCIIEncoding.ASCII.GetBytes(message);
string returnValue = System.Convert.ToBase64String(toencodeAsBytes);
receipt.TemplateText = returnValue;
| Type | Name | Description |
|---|---|---|
| ReceiptRefNum | string | Gateway assigned ID of Receipt. (Ignored when adding a receipt) |
| Name | string | Name of receipt (used to identify receipt) |
| Target | string | Type of receipt output (Email or Print) |
| Subject | string | Subject line of email (Only applicable if "Target" is "Email") |
| FromEmail | string | From email address (Only applicable if "Target" is "Email") |
| ContentType | string | Content types supported by receipt (HTML, Text or Both) |
| TemplateHTML | string | HTML version of template (Base-64 Encoded) |
| TemplateText | string | Text version of template (Base-64 Encoded) |
Change History
| Version | Change |
|---|---|
| 1.7 | Changed ReceiptRefNum to type string |
| 1.3 | Object added in 1.3 release |
RecurringBilling
This object stores information relating to specific recurring billing cycles.
It includes the frequency, amount, start and end dates of the recurring billing schedule.
Places Used
Properties
Example Object
Dim recurring As usaepay.RecurringBilling = New usaepay.RecurringBilling
recurring.Amount = 10.0
recurring.Enabled = True
recurring.Next = "2010-09-01"
recurring.NumLeft = "5"
recurring.Schedule = "monthly"
tran.RecurringBilling = recurring
tran.RecurringBilling = new usaepay.RecurringBilling();
tran.RecurringBilling.Amount = 10.00;
tran.RecurringBilling.Schedule = "bi-monthly";
tran.RecurringBilling.Next = "2010-09-01";
tran.RecurringBilling.NumLeft = "5";
tran.RecurringBilling.Enabled = true;
| Name | Type | Description |
|---|---|---|
| Schedule | string | Frequency of recurring billing schedule. Possible values include: disabled, daily, weekly, bi-weekly (every two weeks), monthly, bi-monthly (every two months), quarterly, bi-annually (every six months), annually. |
| Next | string | Date this customer will be billed next. Must be formatted Year-Month-Day (ie 2011-07-04) |
| Expire | string | Date this billing entry will be disabled. |
| NumLeft | integer | Number of transactions remaining in recurring billing cycle. (Overrides the Expire parameter) |
| Amount | double | Amount to be billed in each transaction. |
| Enabled | boolean | Notes whether customer is currently enabled for recurring billing. |
SearchParam
Used to create a unique search parameter.
This object is used to create a search parameter for methods such as searchTransactions and searchCustomers.
It consists of three properties: the name of the field you are searching on, the type of comparison to make, and the value. Since each method uses a unique set of search parameters, check the documentation of each method for a list of valid field names. A complete list of all methods using this object can be found below.
Places Used
Properties
Example Object
Dim search(0) As usaepay.SearchParam
search(0) = New usaepay.SearchParam()
search(0).Field = "Created"
search(0).Type = "Contains"
search(0).Value = "2010-09-09"
usaepay.SearchParam[] search = new usaepay.SearchParam[2];
search[0] = new usaepay.SearchParam();
search[1] = new usaepay.SearchParam();
search[0].Field = "Amount";
search[0].Type = "eq";
search[0].Value = "12.00";
search[1].Field = "Created";
search[1].Type = "gt";
search[1].Value = "2010-08-08";
| Name | Type | Description |
|---|---|---|
| Field | string | Name of field you are searching. |
| Type | string | Search condition. Possible Values are: - dneq -Does not Equal - eq -Equals - gt -Greater Than - lt -Less Than - gte -Greater Than or Equal To - lte -Less Than or Equal To - sw -Starts with - ew -Ends with - contains -contains - dncontain -Does not Contain - in -In List - notin -Not in List |
| Value | string | Value to search on |
SyncLog
A change log entry
This object describes a change that has occurred on the gateway.
Places Used
Properties
Example Object
try
{
usaepay.SyncLog[] log = client.getSyncLog(token, ObjectName, FromPosition);
MessageBox.Show(string.Concat(log.Length));
}
| Name | Type | Description |
|---|---|---|
| SyncPosition | integer | Sequential id of sync log entry |
| ObjectName | string | Object type that was changed (products, products_categories, customers, etc) |
| RefNum | string | Reference number for object that was changed (ProductRefNum, CustRefNum, etc) |
| ChangeDate | string | The date/time that the changed occurred on the gateway (all times in PST) |
| Action | string | The type of change that occurred (insert,update or delete) |
SystemInfo
Contains API version, environment, data-center, time.
This object contains the API version, environment (production/sandbox/staging), data-center location, and a timestamp.
Places Used
Properties
| Name | Type | Description |
|---|---|---|
| ApiVersion | string | Version of the API |
| Environment | string | Production, Sandbox, or Staging |
| Datacenter | string | Location of the data-center |
| Time | string | Timestamp |
TransactionDetail
Contains transaction specific data.
This object is used with several transaction methods and contains important transaction specific data such as invoice number, originating terminal, total amount of transaction, portions of total alloted for tip, tax and shipping, and currency code.
Places Used
Properties
Example object
Dim details As usaepay.TransactionDetail = New usaepay.TransactionDetail
details.Amount = "34.50"
details.AmountSpecified = True
details.Description = "Example QuickSale"
details.Invoice = "123456"
usaepay.TransactionDetail details = new usaepay.TransactionDetail();
details.Amount = 34.50;
details.AmountSpecified = true;
details.Description = "Example QuickSale";
details.Invoice = "123456";
| Name | Type | Description |
|---|---|---|
| Invoice | string | Transaction invoice number. Will be truncated to 10 characters. If this field is not provided, the system will submit the RefNum in its place. |
| PONum | string | Purchase Order Number for commercial card transactions - 25 characters. (Required for Level 2 & 3) |
| OrderID | string | Transaction order ID. This field should be used to assign a unique order id to the transaction. The order ID can support 64 characters. |
| SessionID | string | Optional Session ID used for customer analytics and fraud prevention. Must be get generated using the getSession method. See the profiling guide for more information |
| Clerk | string | Sales Clerk. Optional value indicating the clerk/person processing transaction, for reporting purposes. |
| Terminal | string | Terminal Name. Optional value indicating the terminal used to process transaction, for reporting purposes. |
| Table | string | Restaurant Table Number. Optional value indicating the restaurant table, for reporting purposes |
| LaneID | string | POS identification number set by merchant. |
| Description | string | Transaction description. |
| Comments | string | Comments. Free form text. |
| AllowPartialAuth | boolean | Allow a partial authorization if full amount is not available (Defaults to false) |
| Amount | double | Total billing amount. (Subtotal+Tax+Tip+Shipping-Discount=Amount.) |
| Currency | string | Currency Code. 3 digit currency code of total amount. |
| Tax | double | Portion of total amount that is tax. (Required for Level 2 & 3) |
| Tip | double | Portion of total amount that is tip. |
| NonTax | boolean | Determines whether a transaction is non-taxable. |
| Shipping | double | Portion of total amount that is shipping charges. (Required for Level 3) |
| ShipFromZip | double | Zipcode that the order is shipping from. (Required for Level 3) |
| Discount | double | Amount of discount. |
| Duty | double | Amount of duty charged. (Required for Level 3) |
| Subtotal | double | The amount of the transaction before tax, tip, shipping and discount have been applied. |
| CashBack | string | Denotes the amount of cashback customer requested. |
| DigitalGoods | string | Denotes the products were virtual or physical |
Change Log
| Version | Change |
|---|---|
| 1.7 | Added CashBack type string, DigitalGoods type string, LaneID type string |
TransactionObject
Contains all transaction data.
This object contains all of the data on a transaction. Some fields are masked for security reasons and some fields are specific to credit card or electronic check transactions.
Some information stored in this object is important for security reasons such as the username of the person who processed the transaction, the IP address of the server from which it was submitted and the source key that the transaction was processed under.
Places Used
Properties
Example Object
Dim response As usaepay.TransactionObject
response = client.getTransaction(token, refnum)
MsgBox("Transaction Type: " & response.TransactionType)
usaepay.TransactionObject tran = new usaepay.TransactionObject();
try
{
tran = client.getTransaction(token, refnum);
MessageBox.Show(string.Concat("Transaction RefNum: ",
tran.Response.RefNum));
}
| Name | Type | Description |
|---|---|---|
| Status | string | Status of specified transaction. |
| %TransactionResponse% | object | Returns a TransactionResponse object containing the results of the transaction and all relevant data. |
| TransactionType | string | Type of transaction. (Sale, Credit, Void, AuthOnly, etc.) |
| %CheckTrace% | object | Tracking data for check transactions. Includes tracking number, effective posting date, date processed, date settled, date returned and bank notes. |
| DateTime | string | Date/time transaction was originally submitted. |
| AccountHolder | string | Name of the account holder. |
| %Details% | object | Transaction details: amount, clerk, currency, etc. |
| %CreditCardData% | object | CreditCardData. Required for credit card transactions. |
| %CheckData% | object | CheckData. Required for electronic check processing. |
| User | string | The username of the person who processed this transaction. |
| Source | string | The name of the source key that this transaction was processed under. |
| ServerIP | string | IP Address of the server that submitted the transaction to the gateway. |
| ClientIP | string | IP Address of client (if passed on from the server). |
| CustomerID | string | Customer ID |
| %BillingAddress% | object | Billing Address |
| %ShippingAddress% | object | Shipping Address |
| %CustomFields% | array | Array of FieldValue pairs. Additional transaction api fields (ie UMtimeout) can also be passed in via this array. Any field name starting with UM is assumed to be an api field and not a custom field. |
| %LineItem% | array | Array of line item details |
| %LodgingDetails% | object | Object which contains lodging details. |
Change Log
| Version | Description |
|---|---|
| 1.7 | Added LodgingDetails property. |
| 1.2 | Added CustomFields property. |
| 1.1 | Soap 1.1 Release (no changes) |
| 1.0 | Response property added |
TransactionRequestObject
Used to run a new transaction.
This object contains the data needed to run a new transaction, including sale, credit, void and authonly.
Places Used
Properties
Example object
Dim tran As usaepay.TransactionRequestObject = New usaepay.TransactionRequestObject
tran.CreditCardData = New usaepay.CreditCardData
tran.CreditCardData.CardNumber = "4444555566667779"
tran.CreditCardData.CardExpiration = "0913"
tran.CreditCardData.CardCode = "999"
tran.Details = New usaepay.TransactionDetail
tran.Details.Amount = 9.02
tran.Details.AmountSpecified = True
tran.Details.Invoice = "434534"
tran.Details.Description = "Example transaction"
tran.Command = "sale"
usaepay.TransactionRequestObject tran = new usaepay.TransactionRequestObject();
tran.Command = "cc:sale";
tran.Details = new usaepay.TransactionDetail();
tran.Details.Amount = 1.00;
tran.Details.AmountSpecified = true;
tran.Details.Invoice = "1234";
tran.Details.Description = "Example Transaction";
tran.CreditCardData = new usaepay.CreditCardData();
tran.CreditCardData.CardNumber = "4444555566667779";
tran.CreditCardData.CardExpiration = "0909";
| Name | Type | Description |
|---|---|---|
| Command | string | Processing Command. Possible values are: sale, credit, void, creditvoid, authonly, capture, postauth, check and checkcredit. Default is sale. |
| IgnoreDuplicate | boolean | Do not check for duplicate transaction. Set to "true" if you would like to override the duplicate transaction handling. |
| AuthCode | string | Original Authorization Code. Authorization Code obtained "offline" (ie telephone authorization). Only required for PostAuth. |
| RefNum | string | Original Transaction Reference Number. The RefNum received when a transaction was authorized via either the "sale" or "authonly" commands. Required for void and capture commands. Can also use TransKey here. |
| AccountHolder | string | Name of the account holder. |
| %Details% | object | Transaction details: amount, clerk, currency, etc. |
| %CreditCardData% | object | CreditCardData. Required for credit card transactions. |
| %CheckData% | object | CheckData. Required for electronic check processing. |
| ClientIP | string | IP Address of client. |
| CustomerID | string | Customer ID. |
| %BillingAddress% | object | Billing Address |
| %ShippingAddress% | object | Shipping Address |
| CustReceipt | boolean | True/False. True will cause a customer receipt to be sent. |
| CustReceiptName | string | Name of the receipt template to use. Defaults to the standard customer receipt. |
| %RecurringBilling% | object | RecurringBilling. Object describing if recurring billing cycle should be created if initial transaction is approved. |
| %LineItem% | array | Array of line item details |
| %LodgingDetails% | object | Object which contains lodging details. |
| %CustomFields% | array | Array of FieldValue pairs. Additional transaction api fields (ie UMtimeout) can also be passed in via this array. Any field name starting with UM is assumed to be an api field and not a custom field. |
| IfAuthExpired | string | Controls what will happen if the authorization has expired. Possible values are: - Error will block the capture request - ReAuth will attempt to reauthorize the funds - Capture will ignore the authorization date and proceed with capture. If left blank, Capture will be assumed. The amount of time between an authorization expires is controlled by the Expire Auths After setting. |
| AuthExpireDays | string | Sets number of days before an authorization expires. |
| ReleaseFunds | boolean | Set to true to release funds. Only used for voidTransaction. |
| IsRecurring | boolean | Flags a credit card transaction as a recurring payment when sent to the platforms for processing. This is not related to the RecurringBilling object above and it does not tie into the gateway's recurring billing system. Rather, this flag should be used by developers who are initiating the recurring transactions from within their own system and need to indicate that it is recurring. |
| Software | string | Free form string that can be used by the developer to record information about their software, version, build number or operating system details. Reported on the transaction detail screen, in custom reports or via api. |
| SaveCard | boolean | Set to "True" to tokenize card. |
Change Log
| Version | Change |
|---|---|
| 1.7 | Added SaveCard type Boolean, LodgingDetails type LodgingDetails, AuthExpireDays type string, EntryMode type string, ReleaseFunds type boolean, and TransKey type string. |
TransactionResponse
Contains details on the result of a processed transaction.
This object contains the results which are displayed upon successful completion of a given transaction. Includes transaction result (approved, declined, error) and authorization codes and details.
Places Used
- runTransaction
- runTransactionAPI
- runSale
- runQuickSale
- runQuickCredit
- runCredit
- postAuth
- captureTransaction
- overrideTransaction
- voidTransaction
- getTransactionStatus
- runCustomerTransaction
Properties
Example Object
usaepay.TransactionResponse response = new usaepay.TransactionResponse();
try
{
response = client.runTransaction(token, tran);
if (response.ResultCode == "A")
{
MessageBox.Show(string.Concat("Transaction Approved, RefNum: ",
response.RefNum));
}
else
{
MessageBox.Show(string.Concat("Transaction Failed: ",
response.Error));
}
usaepay.TransactionResponse response = new usaepay.TransactionResponse();
try
{
response = client.runTransaction(token, tran);
if (response.ResultCode == "A")
{
MessageBox.Show(string.Concat("Transaction Approved, RefNum: ",
response.RefNum));
}
else
{
MessageBox.Show(string.Concat("Transaction Failed: ",
response.Error));
}
}
<Response xsi:type="ns1:TransactionResponse">
<AcsUrl xsi:nil="true"/>
<AuthCode xsi:type="xsd:string">021730</AuthCode>
<AvsResult xsi:type="xsd:string">Address: Match & 5 Digit Zip: Match</AvsResult>
<AvsResultCode xsi:type="xsd:string">YYY</AvsResultCode>
<BatchRefNum xsi:type="xsd:string">445979</BatchRefNum>
<BatchNum xsi:type="xsd:string">979</BatchNum>
<CardCodeResult xsi:type="xsd:string">Not Processed</CardCodeResult>
<CardCodeResultCode xsi:type="xsd:string">P</CardCodeResultCode>
<ConversionRate xsi:type="xsd:double">0</ConversionRate>
<ConvertedAmount xsi:type="xsd:double">0</ConvertedAmount>
<ConvertedAmountCurrency xsi:type="xsd:string">0</ConvertedAmountCurrency>
<CustNum xsi:type="xsd:string">0</CustNum>
<Error xsi:type="xsd:string">Approved</Error>
<ErrorCode xsi:type="xsd:integer">0</ErrorCode>
<isDuplicate xsi:type="xsd:boolean">false</isDuplicate>
<Payload xsi:nil="true"/>
<RefNum xsi:type="xsd:string">1175354</RefNum>
<RefNum xsi:type="xsd:sting">1nfmkr4rsmtxhm5</TransKey>
<Result xsi:type="xsd:string">Approved</Result>
<ResultCode xsi:type="xsd:string">A</ResultCode>
<Status xsi:type="xsd:string">Pending</Status>
<StatusCode xsi:type="xsd:string">P</StatusCode>
<VpasResultCode xsi:nil="true"/>
</Response>
| Name | Type | Description |
|---|---|---|
| TransKey | string | Transaction Reference Number This is the preferred Transaction Identifier (ALWAYS System Scoped) |
| RefNum | string | Transaction Reference Number (sometimes Merchant Scoped) |
| BatchRefNum | string | Batch Reference Number assigned by Gateway. |
| BatchKey | string | Batch Reference Number assigned by Gateway. |
| BatchNum | string | Batch Sequence Number |
| Result | string | Transaction Result (Approved, Declined, Error, etc) |
| ResultCode | string | Single character result code (A, D, or E) |
| AuthCode | string | Authorization Code |
| AuthAmount | double | Amount that was authorized. Could be less that Amount requested if AllowPartialAuth was true |
| RemainingBalance | double | Returns the balance remaining on some prepaid and stored value cards |
| AvsResultCode | string | AVS Result Code (1-3 characters) |
| AvsResult | string | Text Description of AvsResultCode |
| CardCodeResultCode | string | Card Code (CVV2) Verification Result Code (1 character) |
| CardCodeResult | string | Text Description of Card Code Result |
| CardLevelResultCode | string | List of codes can be found here. |
| CardLevelResult | string | Text Description of Card Level Result |
| %CreditCardToken% | object | This object describes a tokenized credit card. |
| ErrorCode | integer | Error Code (if transaction resulted in error) |
| CustNum | string | System assigned CustNum of stored customer record if one was used or created |
| CustKey | string | Customer Number (System assigned) |
| Error | string | Text Description of Error Code |
| AcsUrl | string | ACS Url for Verified by Visa or Mastercard Secure Code. |
| Payload | string | Payload for Verified by Visa or Mastercard Secure Code. |
| VpasResultCode | string | Vpas Result Code. |
| isDuplicate | boolean | If true, a duplicate transaction was detected and the response data returned is from original transaction. |
| ConvertedAmount | double | Transaction amount converted to new currency. |
| ConvertedAmountCurrency | string | Currency code for new currency. |
| ConversionRate | double | Rate used to convert transaction amount. |
| Status | string | Description of transaction status |
| StatusCode | string | Single character code for transaction status |
| ProfilerScore | string | Score generated by fraud profiler. |
| ProfilerResponse | string | Fraud profiler result: pass, warn, review. Based on score thresholds |
| ProfilerReason | string | Comma separated list of reason codes that contributed to the score. |
Change Log
| Version | Change |
|---|---|
| 1.7 | Added TransKey, CustKey, and Batch Key. Changed BatchNum to type string, BatchRefNum to type string, CustNum to type string. |
| 1.5 | Added ProfilerScore, ProfilerResponse and ProfilerReason parameters |
| 1.4 | Added AuthAmount and RemainingBalance parameters |
| 1.2 | Added BatchRefNum parameter |
| 1.1 | Soap 1.1 Release (no changes) |
| 1.0 | Added Status and Status Code property |
TransactionSearchResult
Contains results of a transaction search.
This object is returned by the searchTransactions method. It describes the result of the search, including the total number of transactions matched, the number being returned, and an array of TransactionObjects
Places Used
Properties
Example Object
Dim tran As usaepay.TransactionSearchResult
tran = New usaepay.TransactionSearchResult
tran = client.getCustomerHistory(token, CustNum)
usaepay.TransactionSearchResult result = new usaepay.TransactionSearchResult();
try
{
result = client.searchTransactions(token, search, matchAll, "0", "10", "created");
MessageBox.Show(string.Concat(result.TransactionsMatched));
}
| Name | Type | Description |
|---|---|---|
| TransactionsMatched | integer | Total number of transactions matched |
| TransactionsReturned | integer | Number of transactions returned in this result set |
| ErrorsCount | integer | Total number of errors matched |
| DeclinesCount | integer | Total number of declines matched |
| SalesCount | integer | Total number of Sales matched |
| CreditsCount | integer | Total number of Credits matched |
| AuthOnlyCount | integer | Total number of AuthOnlys matched |
| VoidsCount | integer | Total number of Voids matched |
| SalesAmount | float | Total dollar amount of Sales matched |
| CreditsAmount | float | Total dollar amount of Credits matched |
| AuthOnlyAmount | float | Total dollar amount of AuthOnlys matched |
| VoidsAmount | float | Total dollar amount of Voids matched |
| ErrorsAmount | float | Total dollar amount of errors matched |
| DeclinesAmount | float | Total dollar amount of Declines matched |
| StartIndex | integer | The starting index used (defaults to 0) |
| Limit | integer | The max number transactions to return in each result set. |
| %TransactionObject% | object | An array TransactionObjects for the matched transactions |
TransactionSession
Transaction session data
This object contains the session data needed for transaction fraud profiling.
Places Used
Properties
| Name | Type | Description |
|---|---|---|
| OrgID | string | Organization ID |
| SessionID | string | Unique session identifier |
Boarding API v1.5
The USAePay Reseller API provides a standardized web services interface that allows resellers to leverage some of the reseller console functionality within their applications. It supports basic operations such adding new merchants to the gateway and retrieving usage reports. Since the API uses web standards, it is directly supported by many programming languages such as Dot Net and PHP.
Versioning
SOAP uses WSDL files to describe the methods and objects that are made available by a webservice. With each new version of the USAePay SOAP API a new WSDL file is released. Once a version of the API is released, it's corresponding WSDL file will not change. This allows developers to continue to use an older version of the API indefinitely without the risk of future releases breaking existing code. There is no need to upgrade to the latest version unless new functionality is desired. There is also no restriction on the number of WSDL files used by an application. Existing code can continue to use the old WSDL while newly added code can use a second WSDL link.
To obtain a wsdl for the Reseller API, please contact the Integration Support department.
Current Version: 1.5
Prior to version 1.3, the reseller api was combined with the general merchant SOAP API.
Getting Started
The following guides give specific setup instructions/background information on using Soap with some of the more common programming languages. If you are using a language not listed below, please feel free to contact us for assistance. The Soap interface can be used with any programming language that is able to communicate with an HTTPS connection.
- PHP 5 (Built-in SoapClient)
- PHP 5 (Pear Library)
- Visual Basic (.Net)
- Visual Basic 2010 (.Net 4.0)
- C# (.Net)
- Java (JAX-WS, Apache CFX)
PHP Boarding Guide
This guide provides information on using PHP with the USAePay SOAP API. The SOAP API provides an advanced interface to USAePay that allows merchants and resellers to access a wide range of functionality.
Choosing a SOAP Library
When using PHP there are several SOAP libraries available that can be used to make the integration with USAePay easier. While using a library is not required, it typically makes the development process much quicker. We've listed the two libraries that we recommend and actively support. There are several other libraries that should work well but we have not had the time to throughly test all of them.
PHP SoapClient extension
PHP 5 and above comes with a Soap extension included. USAePay recommends that all developers use this class if possible. This guide includes examples for the PHP 5 SoapClient and assumes that you have it installed correctly. To verify that you have the soap client installed run a script with:
<?php phpinfo() ?>
The output should include "Soap Client: enabled" If you do not have it installed and are using a Linux server, you will need to install the php-soap package. For example, on Red Hat EL or CentOS:
yum install php-soap
If you compile your own PHP server, include --enable-soap in the ./configure command.
If you do not have the ability to install software or recompile php, use the PEAR Soap library instead (see below).
PEAR::Soap
The official Pear repository includes a fairly full-featured Soap library written in PHP. Since it is written in PHP, it does not require any special privileges on the server. See PEAR::Soap for more information.
The information in this guide is for the PHP SoapClient extension. For information on using the PEAR::Soap library with USAePay, please see the PEAR Soap Guide.
Using SoapClient
Step 1: Instantiating $client
The first step is to instantiate the SoapClient object. In the soap example provided on this site, we use $client for this object.
<?php
//for live server use 'www' for test server use 'sandbox'
$wsdl='https://sandbox.usaepay.com/soap/resellerapi/1412E031/usaepay.wsdl';
// instantiate SoapClient object as $client
$client = new SoapClient($wsdl);
?>
If this fails with the error:
Fatal error: Cannot instantiate non-existent class: soapclient
then you do not have the SoapClient extension installed. See the directions above for more info on installing the extension.
If this fails with the error:
Unable to retrieve WSDL https://sandbox.usaepay.com/soap/resellerapi/xxxxxxxxx/usaepay.wsdl
then remove usaepay.wsdl from the link leaving only https://sandbox.usaepay.com/soap/resellerapi/1412E031/xxxxxxxx/` and try again.
Step 2: Building Security $token
Building Security $token Example
<?php
$sourcekey = 'R:b***********************************1';
$pin = '1234';
// generate random seed value
$seed=mktime() . rand();
// make hash value using sha1 function
$clear= $sourcekey . $seed . $pin;
$hash=sha1($clear);
// assembly ueSecurityToken as an array
$token=array(
'SourceKey'=>$sourcekey,
'PinHash'=>array(
'Type'=>'sha1',
'Seed'=>$seed,
'HashValue'=>$hash
),
'ClientIP'=>$_SERVER['REMOTE_ADDR'],
);
?>
The ueSecurityToken object is used to securely identify the reseller to the gateway. To build a token, you will need the reseller's Source Key and Pin. The source key is created by the reseller in the Reseller Console under the Settings - Keys Management screen. Many of the methods in the SOAP API require the use of a PIN, and it is recommended that you always use a PIN. The reseller assigns the PIN when creating the source key.
Additional Help
For questions, please email devsupport@usaepay.com
PHP 5 (Pear) Boarding Guide
This guide provides information on using the PEAR::Soap library with the USAePay SOAP API. The SOAP API provides an advanced interface to USAePay that allows merchants and resellers to access a wide range of functionality.
The official Pear repository includes a fairly full-featured Soap library written in PHP. Since it is written in PHP, it does not require any special privileges to install on your web server. See PEAR::Soap for more information.
Using PEAR::Soap
Step 1: Including the Soap library
Including the SOAP library Example
<?php
require_once 'SOAP/Base.php';
require_once 'SOAP/Client.php';
?>
If you have installed the PEAR::Soap library in the standard location, you should be able to use the code below. Otherwise, make sure to either add the library to your include path or provide the full path to the library files.
Step 2: Instantiating $client
Instantiating $client Example
<?php
//for live server use 'www' for test server use 'sandbox'
$wsdl='https://www.usaepay.com/soap/resellerapi/1412E031/usaepay.wsdl';
// instantiate SOAP_Client object as $client
$client = new SOAP_Client($wsdl);
?>
The first step is to instantiate the SOAP_Client object. In the soap example provided on this site, we use $client for this object.
Step 3: Building Security $token
Building Security $token Example
<?php
$sourcekey = 'R:b****************************************1 ';
$pin = '1234';
// generate random seed value
$seed=mktime() . rand();
// make hash value using sha1 function
$clear= $sourcekey . $seed . $pin;
$hash=sha1($clear);
// assembly ueSecurityToken as an array
$token=array(
'SourceKey'=>$sourcekey,
'PinHash'=>array(
'Type'=>'sha1',
'Seed'=>$seed,
'HashValue'=>$hash
),
'ClientIP'=>$_SERVER['REMOTE_ADDR'];
);
?>
The ueSecurityToken object is used to securely identify the reseller to the gateway. To build a token, you will need the reseller's Source Key and Pin. The source key is created by the reseller in the Reseller Console under the Settings - Keys Management screen. Many of the methods in the SOAP API require the use of a PIN and it is recommended that you always use a PIN. The reseller assigns the PIN when creating the source key.
Examples
The majority of examples listed in the documentation as PHP5 will work with either the built-in Soap client, or the Pear Library. In cases where different syntax is required for the Pear library, a separate example is required.
Visual Basic Boarding Guide
Adding a Web Reference
Step 1: Generate a WSDL
For testing on sandbox you can use:
https://sandbox.usaepay.com/soap/gate/15E7FB61/usaepay.wsdl
but it is recommend that you generate your own WSDL link in the Developer's Center.
Step 2: Add WSDL to the Project in Visual Studio:
In the Solution Explorer, select the project that will be using the web service. Right-click on the project and choose Add Web Reference.
Populate the URL field with your USAePay generated WSDL link. Click Go.
Step 3: Change Web Reference name to "usaepay":
A security warning will appear, click Yes and change the Web Reference name to
usaepay
and then click Add Reference to confirm.
Once complete, you have now added a web reference called reseller to your project.
Using the Web Reference
To use the USAePay web reference, you must generate a token which authenticates your application to the gateway. This requires generating an MD5 hash value. The following steps walk through the process of creating this token. Once the token is created, running specific methods is fairly easy. For examples of a specific methods, please refer to the examples provide on each method page.
Step 1: Including Required Imports
Required Imports Example
Imports System
Imports System.Web
Imports System.IO
Imports System.Security.Cryptography
Imports System.Text
The generation of MD5 hash requires some .NET libraries be imported into your code. Typically these import statements will go at the top of the your code.
Step 2: Instantiating the Client
Instantiating $client Example
Dim client As New reseller.resapiService 'reseller is the name of your Web Reference
The next step is to instantiate the client object. In the soap examples provided on this site, we use the variable client for this object.
Step 3: Set a Proxy Server (if needed)
Setting a Proxy Server Example
Dim proxycreds As New System.Net.NetworkCredential("user", "password", "Domain")
Dim proxy As New System.Net.WebProxy("127.0.0.1", 80)
proxy.Credentials = proxycreds
client.Proxy = proxy
If your network requires you to use a proxy server, the next step is to reference the proxy server. If you do not have a proxy server, skip this step.
Step 4a: Building Security Token
Building Security $token Example
Dim token As New reseller.ueSecurityToken
token.SourceKey = "P11PON_ENTER_SOURCE_KEY_HERE_KSQr1VT81"
token.ClientIP = "127.0.0.1"
token.PinHash = New reseller.ueHash
token.PinHash.Seed = "5678" 'Hard coded seed for easy troubleshooting
token.PinHash.Type = "md5" 'Type of encryption
Dim prehashvalue As String
prehashvalue = token.SourceKey & token.PinHash.Seed & "1234" 'Put together the pieces
token.PinHash.HashValue = Me.GenerateHash(prehashvalue) 'Pass the prehashvalue to a GenerateHash function
The ueSecurityToken object is used to securely identify the reseller to the gateway. To build a token, you will need the reseller's Source Key and Pin. The source key is created by the reseller in the Reseller Console under the Settings - Keys Management screen. Many of the methods in the SOAP API require the use of a PIN, and it is recommended that you always use a PIN. The reseller assigns the PIN when creating the source key.
Step 4b: Generating a Hash
Generate Hash Example
Private Function GenerateHash(ByVal SourceText As String) As String
'Instantiate an MD5 Provider object
Dim md5 As New MD5CryptoServiceProvider
'Compute the hash value from the source
Dim ByteHash() As Byte = md5.ComputeHash(Encoding.Default.GetBytes(SourceText))
'Instantiate a StringBuilder object
Dim sb As New StringBuilder
'Repack binary hash as hex
For c As Integer = 0 To ByteHash.Length - 1
sb.AppendFormat("{0:x2}", ByteHash(c))
Next c
'Return the hex hash
Return sb.ToString
End Function
The above code expects a GenerateHash method to be present in your class. Copy and paste the function below into your class.
Handling Events
Example Code
Private WithEvents client As reseller.usaepayService
Private Sub handleStatusUpdate(ByVal sender, ByVal ev As reseller.addMerchantApplicationCompletedEventArgs) Handles client.addMerchantApplicationCompleted
MsgBox("Application added!")
End Sub
The visual studio webservice implementation allows you to subscribe to a "completed" event that will be raised when a soap call completes. The following code demonstrates how to subscribe to the addMerchantApplicationCompleted event:
Visual Basic 2010 Boarding Guide
Adding a Web Reference
Step 1: Generate a WSDL
For testing on sandbox you can use
https://sandbox.usaepay.com/soap/resellerapi/1412E031/usaepay.wsdll
but it is recommend that you generate your own wsdl link in the Developer Portal.
Step 2: Add WSDL to the Project in Visual Studio:
In the Solution Explorer, select the project that will be using the USAePay service. Right-click on the project and choose Add Service Reference and a dialog box will open.
Populate the URL field with your USAePay generated WSDL link. Click Go.
Step 3: Change Service Reference name to "reseller":
Change the namespace to:
reseller
Then click OK to confirm
Once complete, you have now added a service reference called reseller to your project.
Using the Web Service Reference
To use the USAePay web reference, you must generate a "token" which authenticates your application to the gateway. This requires generating an MD5 hash value. The following steps walk through the process of creating this token. Once the token is created, running specific methods is fairly easy. For examples of specific methods, please refer to the examples provided on each method's page.
Step 1: Including Required Imports
Required Imports Example
Imports System
Imports System.Web
Imports System.IO
Imports System.Security.Cryptography
Imports System.Text
The generation of an MD5 hash value requires that you import some .NET libraries into your code. Typically these import statements will go at the top of the your code.
Step 2: Instantiating the Client
Instantiating $client Example
Dim client As New reseller.ueSoapServerPortTypeClient 'reseller' is the name of your Web Reference
The next step is to instantiate the client object. In the soap examples provided on this site, we use the variable "client" for this object.
Step 3: Setting a Proxy Server (if needed)
Setting a Proxy Server Example
Dim proxycreds As New System.Net.NetworkCredential("user", "password", "Domain")
Dim proxy As New System.Net.WebProxy("127.0.0.1", 80)
proxy.Credentials = proxycreds
client.Proxy = proxy
If your network requires you to use a proxy server, the next step is to reference the proxy server. If you do not have a proxy server, skip this step.
Step 4a: Building Security Token
Building Security $token Example
Dim token As New reseller.ueSecurityToken
token.SourceKey = "P11PON_ENTER_SOURCE_KEY_HERE_KSQr1VT81"
token.ClientIP = "127.0.0.1"
token.PinHash = New reseller.ueHash
token.PinHash.Seed = "5678" 'Hard coded seed for easy troubleshooting
token.PinHash.Type = "md5" 'Type of encryption
Dim prehashvalue As String
prehashvalue = token.SourceKey & token.PinHash.Seed & "1234" 'Put together the pieces
token.PinHash.HashValue = Me.GenerateHash(prehashvalue) 'Pass the prehashvalue to a GenerateHash function
The ueSecurityToken object is used to securely identify the reseller to the gateway. To build a token, you will need the reseller's Source Key and Pin. The source key is created by the reseller in the Reseller Console under the Settings - Keys Management screen. Many of the methods in the SOAP API require the use of a PIN, and it is recommended that you always use a PIN. The reseller assigns the PIN when creating the source key.
Step 4b: Generating a Hash
Generate Hash Example
Private Function GenerateHash(ByVal SourceText As String) As String
'Instantiate an MD5 Provider object
Dim md5 As New MD5CryptoServiceProvider
'Compute the hash value from the source
Dim ByteHash() As Byte = md5.ComputeHash(Encoding.Default.GetBytes(SourceText))
'Instantiate a StringBuilder object
Dim sb As New StringBuilder
'Repack binary hash as hex
For c As Integer = 0 To ByteHash.Length - 1
sb.AppendFormat("{0:x2}", ByteHash(c))
Next c
'Return the hex hash
Return sb.ToString
End Function
The above code expects a "GenerateHash" method to be present in your class. Copy and paste the function below into your class.
Handling Events
Example Code
Private WithEvents client As reseller.usaepayService
Private Sub handleStatusUpdate(ByVal sender, ByVal ev As usaepay.addMerchantApplicationEventArgs) Handles client.addMerchantApplicationCompleted
MsgBox("Application added!")
End Sub
The visual studio webservice implementation allows you to subscribe to a "completed" event that will be raised when a soap call completes. The following code demonstrates how to subscribe to the addMerchantApplicationCompleted event:
C# Boarding Guide
Adding a Web Reference
Step 1: Generate a WSDL
For testing on sandbox you can use:
https://sandbox.usaepay.com/soap/resellerapi/1412E031/usaepay.wsdl
but it is recommend that you generate your own wsdl link in the Developer Portal
Step 2: Add WSDL to the Project in Visual Studio:
In the Solution Explorer, select the project that will be using the web service. Right-click on the project and choose Add Web Reference and a dialog box will open.
Populate the URL field with your USAePay generated WSDL link. Click Go.
A security warning will appear, click Yes and change the Web Reference name to:
reseller
Then click Add Reference to confirm.
Once complete, you have now added a web reference called reseller to your project.
Using the Web Reference
To use the USAePay web reference, you must generate a "token" which authenticates your application to the gateway. This requires generating an MD5 hash value. The following steps walk through the process of creating this token. Once the token is created, running specific methods is fairly easy. For examples of a specific methods, please refer to the examples provide on each method page.
Step 1: Including Required Headers
Required Headers Example
using System;
using System.Web;
using System.Security.Cryptography;
using System.Text;
The generation of MD5 hash requires some .NET libraries be imported into your code. Typically these using statements will go at the top of the your code.
Step 2: Instantiating the client
Instantiating $client Example
reseller.usaepayService client = new usaepayService(); //reseller is the name of your Web Reference
The next step is to instantiate the client object. In the soap examples provided on this site, we use the variable 'client' for this object.
Step 3: Set a Proxy Server (if needed)
Setting a Proxy Server Example
System.Net.NetworkCredential proxycreds = new System.Net.NetworkCredential("user", "password");
System.Net.WebProxy proxy = new System.Net.WebProxy("127.0.0.1", 80); //address of proxy server
proxy.Credentials = proxycreds;
client.Proxy = proxy;
If your network requires you to use a proxy server, the next step is to reference the proxy server. If you do not have a proxy server, skip this step.
Step 4a: Building Security Token
Building Security $token Example
reseller.ueSecurityToken token = new reseller.ueSecurityToken();
token.SourceKey = "P11PON_ENTER_SOURCE_KEY_HERE_KSQr1VT81";
token.ClientIP = "11.22.33.44"; // IP address of end user (if applicable)
string pin = "1234"; // pin assigned to source
reseller.ueHash hash = new reseller.ueHash();
hash.Type = "md5"; // Type of encryption
hash.Seed = Guid.NewGuid().ToString(); // unique encryption seed
string prehashvalue = string.Concat(token.SourceKey, hash.Seed, pin); // combine data into single string
hash.HashValue = GenerateHash(prehashvalue); // generate hash
token.PinHash = hash; // add hash value to token
The ueSecurityToken object is used to securely identify the reseller to the gateway. To build a token, you will need the reseller's Source Key and Pin. The source key is created by the reseller in the Reseller Console under the Settings - Keys Management screen. Many of the methods in the SOAP API require the use of a PIN, and it is recommended that you always use a PIN. The reseller assigns the PIN when creating the source key.
Step 4b: Generating a Hash
Generate Hash Example
private static string GenerateHash(string input)
{
// Create a new instance of the MD5CryptoServiceProvider object.
MD5 md5Hasher = MD5.Create();
// Convert the input string to a byte array and compute the hash.
byte[] data = md5Hasher.ComputeHash(Encoding.Default.GetBytes(input));
// Create a new Stringbuilder to collect the bytes
// and create a string.
StringBuilder sBuilder = new StringBuilder();
// Loop through each byte of the hashed data
// and format each one as a hexadecimal string.
for (int i = 0; i < data.Length; i++)
{
sBuilder.Append(data[i].ToString("x2"));
}
// Return the hexadecimal string.
return sBuilder.ToString();
}
The above code expects a "GenerateHash" method to be present in your class. Copy and paste the function below into your class.
Step 5: Calling Soap Method
Call Method Example Code
string merchantID = "133534";
reseller.Merchant merchant = new reseller.Merchant();
try
{
merchant = reclient.getMerchant(retoken, merchantID);
MessageBox.Show(string.Concat(merchant.MerchantName));
}
catch (Exception err) {
MessageBox.Show(err.Message);
}
Now that you have a security token created you can make calls to the soap methods listed in the api. For example, to close the currently open credit credit card batch:
JavaJAX-WS Boarding Guide
The following guide demonstrates how to use the USAePayResApi-jaxws.jar package with either Sun's Jax-WS 2.1 or Apache Foundation's CXF libary. This package contains a helper class for easily generating security tokens, classes for all USAePay objects and a client service class for calling web service methods. The package requires Jax-WS (see Dependencies).
Downloads
| File | Version | Release Date | Description |
|---|---|---|---|
| usaepayresapi-jaxws-1.4.0.zip | 1.4.0 | 10/07/10 | Library .jar and example .java |
| usaepayresapi-jaxws-1.4.0.zip | 1.4.0 | 10/07/10 | USAePayResAPI-jaxws-1.4.jar only |
Dependencies (Using Apache CXF)
- USAePayResAPI-jaxws-1.4.jar
- apache-cxf-2.2.9/lib/commons-logging-1.1.1.jar
- apache-cxf-2.2.9/lib/cxf-2.2.9.jar
- apache-cxf-2.2.9/lib/geronimo-activation_1.1_spec-1.0.2.jar
- apache-cxf-2.2.9/lib/geronimo-annotation_1.0_spec-1.1.1.jar
- apache-cxf-2.2.9/lib/geronimo-javamail_1.4_spec-1.6.jar
- apache-cxf-2.2.9/lib/geronimo-jaxws_2.1_spec-1.0.jar
- apache-cxf-2.2.9/lib/geronimo-servlet_2.5_spec-1.2.jar
- apache-cxf-2.2.9/lib/geronimo-stax-api_1.0_spec-1.0.1.jar
- apache-cxf-2.2.9/lib/geronimo-ws-metadata_2.0_spec-1.1.2.jar
- apache-cxf-2.2.9/lib/jaxb-api-2.1.jar
- apache-cxf-2.2.9/lib/jaxb-impl-2.1.12.jar
- apache-cxf-2.2.9/lib/jetty-6.1.19.jar
- apache-cxf-2.2.9/lib/jetty-util-6.1.19.jar
- apache-cxf-2.2.9/lib/neethi-2.0.4.jar
- apache-cxf-2.2.9/lib/saaj-api-1.3.jar
- apache-cxf-2.2.9/lib/saaj-impl-1.3.2.jar
- apache-cxf-2.2.9/lib/wsdl4j-1.6.2.jar
- apache-cxf-2.2.9/lib/wstx-asl-3.2.8.jar
- apache-cxf-2.2.9/lib/xml-resolver-1.2.jar
- apache-cxf-2.2.9/lib/XmlSchema-1.4.5.jar
Dependencies (Using Sun's Jax-WS 2.1)
- USAePay-jaxws-1.2.0.jar
- jaxb/activation.jar
- jaxb/api/jaxb-api.jar
- jaxb/jaxb-impl.jar
- jaxb/jaxb-xjc.jar
- jaxb/api/jsr173_api.jar
- jaxws21/FastInfoset.jar
- jaxws21/http.jar
- jaxws21/api/jaxws-api.jar
- jaxws21/jaxws-rt.jar
- jaxws21/jaxws-tools.jar
- jaxws21/api/jsr181-api.jar
- jaxws21/api/jsr250-api.jar
- jaxws21/mimepull.jar
- jaxws21/api/saaj-api.jar
- jaxws21/saaj-impl.jar
- jaxws21/sjsxp.jar
- jaxws21/stax-ex.jar
- jaxws21/streambuffer.jar
Using Library
Step 1: Import Classes
Import Classes Example
import com.usaepay.resapi.jaxws.*;
In classes that are going to use the USAePay methods or object, you need to import the appropriate classes from com.usaepay.resapi.jaxws package. The following will import all usaepay objects at once:
Step 2a: Instantiating the Client
Instantiating $client Example
// Instantiate client for production
UeSoapServerPortType client = usaepay.getClient();
All calls to the USAePay web service are handled by a client object of type UeSoapServerPortType. There are two ways to instantiate the client object. To instantiate a client for use with the main production servers use this example.
Step 2b: Specify Server
Specify Server Example
// Instantiate client for sandbox
UeSoapServerPortType client = usaepay.getClient("sandbox.usaepay.com");
Alternately, you can specify a server hostname, which will allow you to setup a connection to the sandbox server for testing or a backup datacenter (see the high availability programming guide).
Step 3: Building Security Token
Building Security $token Example
// Create security token
String SourceKey="YourKeyGoesHere";
String Pin ="YourPinGoesHere";
String ClientIP="10.10.10.10";
UeSecurityToken restoken = usaepay.getToken(SourceKey, Pin, ClientIP);
A restoken object (of type UeSecurityToken) is required by all methods in the USAePay Reseller API. It is used to identify and authenticate the reseller.
Step 4: Calling a SOAP Method
Call Method Example Code
// Set the merchant ref num (merchid)
BigInteger merchrefnum = new BigInteger("118227");
// Create response object
Merchant merch;
// Retrieve Merchant
merch = client.getMerchant(restoken, merchrefnum);
// Display response
System.out.println("Merchant: " + merch.getMerchantName());
Web service methods are called using the client object. This is an example for calling the getMerchant method. For further examples see the api documentation.
Boarding Methods
Merchant Application Methods
addMerchantApplication
Example Request
<?php
try {
$App=new stdClass();
$App->ResellerEmail='applications@reseller.com';
$App->ContactInfo = new stdClass();
$App->MerchantName = "Acme Bagel Company";
$App->ContactInfo->Contact = "John Doe";
$App->ContactInfo->Street ='4929 Wilshire Blvd';
$App->ContactInfo->Street2 ='Suite 800';
$App->ContactInfo->City ='Los Angeles';
$App->ContactInfo->State ='CA';
$App->ContactInfo->Zip ='90010';
$App->ContactInfo->Country ='US';
$App->ContactInfo->Email = 'john@acme';
$App->ContactInfo->Fax ='012134567890';
$App->ContactInfo->Phone ='687668678677';
$App->ContactInfo->MobilePhone='798787978788';
$App->ContactInfo->AltEmail='mary@acmebagels.com';
$App->ContactInfo->URL = 'http://acme bagels.com';
$App->BillingInfo = new stdClass();
$App->BillingInfo->BankName = 'Bank of America';
$App->BillingInfo->RoutingNumber = '12342313312';
$App->BillingInfo->AccountNumber = '57655765754';
$App->BillingInfo->GatewayPackage = 'Platinum Package';
$App->CreditCardPlatform = 'FDMS';
$App->CreditCardIndustry = 'Retail';
$App->CreditCardPlatformSetup = array();
$App->CreditCardPlatformSetup[] = array('Field'=>'MerchantNum', 'Value'=>'4454900399430020');
$App->CreditCardPlatformSetup[] = array('Field'=>'MerchantID', 'Value'=>'382772891');
$App->CreditCardPlatformSetup[] = array('Field'=>'TerminalID', 'Value'=>'112198000');
$App->eCheckPlatform = 'Vericheck';
$App->eCheckPlatformSetup = array();
$App->eCheckPlatformSetup[] = array('Field'=>'DefaultSEC', 'Value'=>'TEL');
$App->eCheckPlatformSetup[] = array('Field'=>'TaxID', 'Value'=>'123456789');
$App->eCheckPlatformSetup[] = array('Field'=>'PIN', 'Value'=>'231');
$App->eCheckPlatformSetup[] = array('Field'=>'MID', 'Value'=>'11231');
$App->eCheckPlatformSetup[] = array('Field'=>'AcceptedSecCodes', 'Value'=>'TEL,PPD,CCD');
$App->SourceKeyName = 'My Shopping Cart';
$App->SourceKeyPin = '1351';
$App->EmailSourceKeyTo = 'demo@acmebagels.com';
$App->UserName = 'acmebagels';
$App->EmailInstructionsTo = 'demo@acmebagels.com';
$App->ApplicationNotes = 'An example note for merchant application';
$ApplicationID=$client->addMerchantApplication($restoken, $App);
}
catch (SoapFault $e) {
echo $client->__getLastRequest();
echo $client->__getLastResponse();
die("addMerchantApplication failed: " .$e->getMessage());
}
?>
reseller.MerchantApplication merchant = new reseller.MerchantApplication();
merchant.ResellerEmail = "irina@usaepay.com";
merchant.MerchantName = "Acme Bagel Company";
merchant.ContactInfo = new reseller.ContactInfo();
merchant.ContactInfo.Contact = "Tester Jones";
merchant.ContactInfo.Street = "123 main st.";
merchant.ContactInfo.Street2 = "suit 100";
merchant.ContactInfo.City = "Los Angeles";
merchant.ContactInfo.State = "CA";
merchant.ContactInfo.Zip = "90038";
merchant.ContactInfo.Country = "USA";
merchant.ContactInfo.Email = "irina@usaepay.com";
merchant.ContactInfo.Fax = "800-888-9999";
merchant.ContactInfo.Phone = "800-888-9999";
merchant.ContactInfo.MobilePhone = "800-999-8888";
merchant.ContactInfo.AltEmail = "irina@usaepay.com";
merchant.ContactInfo.URL = "http://test.com";
merchant.BillingInfo = new reseller.BillingInfo();
merchant.BillingInfo.BankName = "Bank of America";
merchant.BillingInfo.RoutingNumber = "123456789";
merchant.BillingInfo.AccountNumber = "123456789";
merchant.BillingInfo.GatewayPackage = "Platinum Package";
merchant.CreditCardPlatform = "FDMS";
merchant.CreditCardIndustry = "Retail (Swipe)";
reseller.FieldValue[] platform = new reseller.FieldValue[3];
for (int i = 0; i < 3; i++){
platform[i] = new reseller.FieldValue();
}
platform[0].Field = "MerchantNum"; platform[0].Value = "4454900399430020";
platform[1].Field = "MerchantID"; platform[1].Value = "382772891";
platform[2].Field = "TerminalID"; platform[2].Value = "382772891";
merchant.CreditCardPlatformSetup = platform;
merchant.eCheckPlatform = "Vericheck";
reseller.FieldValue[] checkplatform = new reseller.FieldValue[5];
for (int i = 0; i< 5; i++){
checkplatform[i] = new reseller.FieldValue();
}
checkplatform[0].Field = "DefaultSEC"; checkplatform[0].Value = "TEL";
checkplatform[1].Field = "TaxID"; checkplatform[1].Value = "123456789";
checkplatform[2].Field = "PIN"; checkplatform[2].Value = "231";
checkplatform[3].Field = "MID"; checkplatform[3].Value = "11231";
checkplatform[4].Field = "AcceptedSecCodes"; checkplatform[4].Value = "TEL,PPD,CCD";
merchant.eCheckPlatformSetup = checkplatform;
merchant.SourceKeyName = "My Shopping Cart";
merchant.SourceKeyPin = "1351";
merchant.EmailInstructionsTo = "test@test.com";
merchant.UserName = "testmerchant";
merchant.EmailSourceKeyTo = "test@test.com";
merchant.ApplicationNotes = "an example";
string refNum;
try
{
refNum = reclient.addMerchantApplication(retoken,merchant);
MessageBox.Show(string.Concat(refNum));
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
MerchantApplication merchantapp = new MerchantApplication();
merchantapp.setApplicationNotes("Application notes");
BillingInfo billing = new BillingInfo();
billing.setBankName("Example Bank");
billing.setRoutingNumber("123456789");
billing.setAccountNumber("910293112");
billing.setGatewayPackage("Silver Package");
merchantapp.setBillingInfo(billing);
merchantapp.setCallInPassword("1234");
ContactInfo contactinfo = new ContactInfo();
contactinfo.setContact("John Doe");
contactinfo.setStreet("4929 Wilshire Blvd");
contactinfo.setStreet2("Suite 899");
contactinfo.setCity("Los Angeles");
contactinfo.setState("CA");
contactinfo.setZip("90010");
contactinfo.setCountry("US");
contactinfo.setEmail("merchant@tmcode.com");
contactinfo.setAltEmail("merchant@tmcode.com");
contactinfo.setPhone("222-333-4446");
contactinfo.setMobilePhone("222-333-4445");
contactinfo.setFax("222-333-4444");
contactinfo.setURL("http://www.acme.org");
merchantapp.setContactInfo(contactinfo);
merchantapp.setCreditCardIndustry("eCommerce");
merchantapp.setCreditCardPlatform("FDMS");
FieldValueArray platformdata = new FieldValueArray();
platformdata.add(new FieldValue("MerchantNum","2334566356345"));
platformdata.add(new FieldValue("MerchantID","1231230"));
platformdata.add(new FieldValue("TerminalID","1231239"));
merchantapp.setCreditCardPlatformSetup(platformdata);
merchantapp.setECheckPlatform("Vericheck");
FieldValueArray checkplatform = new FieldValueArray();
checkplatform.add(new FieldValue("DefaultSEC","TEL"));
checkplatform.add(new FieldValue("TaxID","123456789"));
checkplatform.add(new FieldValue("PIN","231"));
checkplatform.add(new FieldValue("MID","11231"));
checkplatform.add(new FieldValue("AcceptedSecCodes","TEL,PPD,CCD"));
merchantapp.setECheckPlatformSetup(checkplatform);
merchantapp.setEmailInstructionsTo("merchant@tmcode.com");
merchantapp.setEmailSourceKeyTo("merchant@tmcode.com");
merchantapp.setMerchantName("Example Company");
merchantapp.setResellerEmail("reselller@tmcode.com");
merchantapp.setSourceKeyName("ShoppingCart");
merchantapp.setSourceKeyPin("1234");
merchantapp.setUserName("jdoe23");
BigInteger apprefnum;
apprefnum = client.addMerchantApplication(restoken, merchantapp);
Reseller Only Method
This method adds a new merchant application to the system. If successful, the application ID will be returned. The application ID can be used to check on the status of the merchant application.
Please note that this function does not create a merchant account. The application will be reviewed and activated by the gateway staff. Once activated, a merchant ID will be assigned and all supported merchant related methods may be used.
Related Methods
Syntax
integer addMerchantApplication ( ueSecurityToken Token, MerchantApplication Application )
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Reseller security token: used to identify reseller and validate request. |
| %MerchantApplication% | object | MerchantApplication object containing merchant information. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| ApplicationID | integer | Returns merchant application ID if successful, if request fails, an exception will be thrown. |
Exceptions
| Code | Message | Advice |
|---|---|---|
| 19000 | Unable to save application. | A temporary error occurred while saving the application. Try again or contact support |
| 19001 | The field 'fieldname' is required. | A required field was not populated. See the error message for the name of the missing field. |
| 19014 | Email address 'fieldname' not valid | The email address fields was not a valid email address. It did not pass the formatting check. Check formatting. |
| 19015 | Email address 'fieldname' not valid | One of the email addresses entered was invalid. It did not pass the DNS or mail server delivery checks. Double check the address. |
| 19016 | Requested credit card platform not supported | The CreditCardPlatform was not found in the list of supported platforms |
| 19017 | Requested credit card industry not supported | The CreditCardIndustry was not a supported industry. |
| 19019 | Requested check platform not supported | The eCheckPlatform was not found in the list of supported platforms. |
| 19020 | Billing package not found. | Specified billing package was not found. Double check the list of valid billing package names. |
Change Log
| Version | Change |
|---|---|
| 1.1 | Method added prior to soap-1.1 |
getMerchantApplication
Example Request
<?php
try {
$ApplicationID = 2;
$Application=$client->getMerchantApplication($restoken, $ApplicationID);
print_r($Application);
}
catch (SoapFault $e) {
echo $client->__getLastRequest();
echo $client->__getLastResponse();
die("getMerchantApplication failed: " .$e->getMessage());
}
?>
string appID = "10943080";
reseller.MerchantApplication result = new reseller.MerchantApplication();
try
{
result = reclient.getMerchantApplication(retoken, appID);
MessageBox.Show(string.Concat(result.ContactInfo.Contact));
}
catch (Exception err) {
MessageBox.Show(err.Message);
}
BigInteger apprefnum = new BigInteger("865");
MerchantApplication merchapp;
merchapp = client.getMerchantApplication(restoken, apprefnum);
Reseller Only Method
This method pulls the application for a pending merchant. Requires the gateway assigned ApplicationID. Returns a MerchantApplication object containing application information.
Related Methods
Syntax
MerchantApplication getMerchantApplication ( ueSecurityToken Token, integer ApplicationID )
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Reseller security token, used to identify reseller and validate request. |
| ApplicationID | integer | Application ID number assigned by the gateway |
Response Parameters
| Name | Type | Description |
|---|---|---|
| %MerchantApplication% | object | Returns merchant application object |
getMerchantApplicationStatus
Example Request
<?php
try {
$ApplicationID=2;
$Status=$resclient->getMerchantApplicationStatus($restoken, $ApplicationID);
}
catch (SoapFault $e) {
echo $client->__getLastRequest();
echo $client->__getLastResponse();
die("getMerchantApplicationStatus failed: " .$e->getMessage());
}
?>
BigInteger apprefnum = new BigInteger("865");
String appstatus;
appstatus = client.getMerchantApplicationStatus(restoken, apprefnum);
Reseller Only Method
This method returns the status of a merchant application (added either via the reseller console or the addMerchantApplication method). The application ID that was obtained when adding the merchant application must be passed.
Possible values for status include: * Pending - Application pending review * Under Review - Application is in the process of being reviewed * Waiting For Documents - Additional documents needed * Call Support - Application on hold, call for details * Declined - Application was declined * Approved - Merchant activated * Canceled - Application canceled
Related Methods
Syntax
string getMerchantApplicationStatus ( ueSecurityToken Token, integer ApplicationID )
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Reseller security token, used to identify reseller and validate request. |
| ApplicationID | integer | The merchant application number assigned by the gateway. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| getMerchantApplicationStatusReturn | string | Returns merchant application status. Possible results include: pending, under review, waiting for documents, on hold, declined, activated, canceled. |
Merchant Methods
getMerchant
Example Request
<?php
try {
$MerchRefNum=2;
$Merchant=$client->getMerchant($restoken, $MerchRefNum);
print_r($Merchant);
}
catch (SoapFault $e) {
echo $client->__getLastRequest();
echo $client->__getLastResponse();
die("getMerchant failed: " .$e->getMessage());
}
?>
string merchantID = "133534";
reseller.Merchant merchant = new reseller.Merchant();
try
{
merchant = reclient.getMerchant(retoken, merchantID);
MessageBox.Show(string.Concat(merchant.MerchantName));
}
catch (Exception err) {
MessageBox.Show(err.Message);
}
BigInteger merchrefnum = new BigInteger("118227");
Merchant merchant;
merchant = client.getMerchant(restoken, merchrefnum);
Reseller only method
This method pulls the account information for an active merchant. Requires the gateway assigned MerchantID. Returns a Merchant object containing merchant's contact, billing and platform information. The account number and the routing number for the billing information is masked.
Related Methods
Syntax
Merchant getMerchant ( ueSecurityToken Token, integer MerchantID )
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Reseller security token, used to identify reseller and validate request. |
| MerchRefNum | integer | Merchant ID number assigned by the gateway to an active merchant |
Response Parameters
| Name | Type | Description |
|---|---|---|
| %Merchant% | object | Returns merchant object |
updateMerchant
Example Request
<?php
try {
$objMerchant=new MerchantObject();
$MerchRefNum='2';
print_r($objMerchant);
$res=$client->updateMerchant($restoken,$MerchRefNum,$objMerchant);
print_r($res);
}
catch (SoapFault $e) {
echo $client->__getLastRequest();
echo $client->__getLastResponse();
die("updateMerchant failed: " .$e->getMessage());
}
?>
string merchantID = "133534";
reseller.Merchant merchant = new reseller.Merchant();
merchant.MerchantName = "Another company";
Boolean response;
try
{
response = reclient.updateMerchant(retoken, merchantID, merchant);
MessageBox.Show(string.Concat(response));
}
catch (Exception err) {
MessageBox.Show(err.Message);
}
BigInteger merchrefum = new BigInteger("117821");
Merchant merchchange = new Merchant();
merchchange.setMerchantName("New Company Name");
ContactInfo contactinfo = new ContactInfo();
contactinfo.setContact("John Doe");
contactinfo.setStreet("1234 Main");
contactinfo.setStreet2("Suite 800");
contactinfo.setCity("Los Angeles");
contactinfo.setState("CA");
contactinfo.setZip("11221");
contactinfo.setCountry("US");
contactinfo.setEmail("tim@tmcode.com");
contactinfo.setPhone("223-222-1121");
contactinfo.setFax("590-223-9902");
merchchange.setContactInfo(contactinfo);
client.updateMerchant(restoken, merchrefum, merchchange);
Reseller only method
Allows a reseller to update the information on file for a merchant account.
The following fields may be updated via this method:
- Contact
- Company
- Street
- Street 2
- City
- State
- Zip
- Country
- Fax
- Phone Number
Related Methods
- addMerchantApplication
- getMerchantApplicationStatus
- getMerchant
- deleteMerchant
- searchMerchants
- getMerchantSummary
Syntax
boolean updateMerchant ( ueSecurityToken Token, integer MerchRefNum, Merchant Merchant )
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Reseller security token, used to identify reseller and validate request. |
| MerchRefNum | integer | Merchant ID number assigned by the gateway to an active merchant. |
| %Merchant% | object | Merchant account information including: ID, Company, Contact, Address, Email, Phone, and Fax. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| updateMerchantReturn | boolean | Returns confirmation of update only if successful. If update fails, an exception will be thrown. |
deleteMerchant
Example Request
<?php
try {
$MerchRefNum=2;
$Reason='Testing Soap API';
$client->deleteMerchant($restoken,$MerchRefNum,$Reason);
}
catch (SoapFault $e) {
echo $client->__getLastRequest();
echo $client->__getLastResponse();
}
?>
BigInteger merchrefnum = new BigInteger("118227");
boolean res = client.deleteMerchant(restoken, merchrefnum, "Merchant is no longer active");
Reseller Only Method
This method will flag a merchant for deletion. Once the deletion request is verified and approved by the gateway, the merchant account will be closed and the merchant will no longer be able to process transactions or log in to the Merchant Console.
The reason argument should include any details, such as contact request details, reason for deletion, etc. that may speed up the deletion request verification process.
Related Methods
- addMerchantApplication
- getMerchantApplicationStatus
- getMerchant
- updateMerchant
- searchMerchants
- getMerchantSummary
Syntax
boolean deleteMerchant ( ueSecurityToken Token, integer MerchRefNum, string Reason )
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Reseller security token, used to identify reseller and validate request. |
| MerchRefNum | integer | Merchant ID number assigned by the gateway to an active merchant |
| Reason | string | Any information relevant to the delete merchant account request. You may wish to include the following: contact request details, reason for deletion request, any other relevant information. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| deleteMerchantReturn | boolean | Returns confirmation of your request only if successful. If request fails, an exception will be thrown. |
Exceptions
| Code | Message | Advice |
|---|---|---|
| 19003 | Requested merchant not found. | The MerchRefNum did not match a merchant account associated with your reseller account. Double check MerchRefNum. |
| 19005 | Requested merchant was deleted and is no longer active. | The merchant account was already deleted. Double check the MerchRefNum and make sure the delete call is only running once. |
Merchant Search Methods
searchMerchants
Example Request
<?php
try {
$search=array(
array('Field'=>'State', 'Type'=>'eq','Value'=>'CA'),
array('Field'=>'Contact', 'Type'=>'eq', 'Value'=>'John Doe'),
array('Field'=>'Company', 'Type'=>'eq', 'Value'=>'DidorightInc.')
);
$start=0;
$limit=100;
$matchall=true;
$sortby='merchid';
$res=$client->searchMerchants($restoken,$search,$matchall,$start,$limit, $sortby);
}
catch (SoapFault $e) {
echo $client->__getLastRequest();
echo $client->__getLastResponse();
die("searchMerchants failed: " .$e->getMessage());
}
?>
SearchParamArray params = new SearchParamArray();
params.add(new SearchParam("State", "eq", "CA"));
MerchantSearchResult result;
result = client.searchMerchants(restoken, params, true, BigInteger.ZERO, new BigInteger("100"), "MerchRefNum");
System.out.println("Found Merchant: " + result.getMerchants().getMerchants().get(1).getMerchantName());
Reseller only method.
This method allows resellers to search their database for active merchants based on specific criteria.
The following fields may be searched via this method:
- MerchRefNum
- Contact
- Company
- Street
- Street 2
- City
- State
- Zip
- Fax
- Phone Number
If MatchAll is set to "true," then only results matching ALL of your search criteria will be returned. If your search does not yield the desired results, eliminate some of you search terms or set MatchAll to "false."
Related Methods
Syntax
MerchantSearchResult searchMerchants ( ueSecurityToken Token, SearchParam Search, boolean MatchAll, integer Start, integer Limit, string Sort)
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Reseller security token, used to identify reseller and validate request. |
| %SearchParam% | array | Array of search parameters. |
| MatchAll | boolean | If set to "true," only results matching all search criteria will be returned, if set to "false," results matching any of the search criteria will be returned. |
| Start | integer | Record number to start returning from (ie if 1,000 were found and you only want to receive the last 200 you would set Start=800 and Limit=200) |
| Limit | integer | Maximum number of records to return in result set. |
| Sort | string | Comma separated list of fields to sort by. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| %MerchantSearchResult% | Returns results of active merchant search based on search parameters set. |
Change History
| Version | Change |
|---|---|
| 1.2 | Added Sort Parameter |
| 1.1 | Soap 1.1 Release |
searchMerchantsCount
Example Request
<?php
try {
$search=array(
array('Field'=>'State', 'Type'=>'eq','Value'=>'CA'),
array('Field'=>'Contact', 'Type'=>'eq', 'Value'=>'John Doe'),
array('Field'=>'Company', 'Type'=>'eq', 'Value'=>'DidorightInc.')
);
$start=0;
$limit=100;
$matchall=true;
$sortby='merchid';
$res=$client->searchMerchantsCount($restoken,$search,$matchall,$start,$limit, $sortby);
print_r($res);
}
catch (SoapFault $e) {
echo $client->__getLastRequest();
echo $client->__getLastResponse();
die("searchMerchants failed: " .$e->getMessage());
}
?>
SearchParamArray params = new SearchParamArray();
params.add(new SearchParam("State", "eq", "CA"));
MerchantSearchResult result;
result = client.searchMerchantsCount(restoken, params, true, BigInteger.ZERO, new BigInteger("100"), "MerchRefNum");
Reseller only method
Identical to the searchMerchants method except only the merchants counts are returned. Like searchMerchants, this method returns MerchantSearchResult. The only difference is that MerchantSearchResult.Merchants is left empty. This method provides a quicker way to determine the size of the result set before starting to retrieve the full search results.
Related Methods
Syntax
MerchantSearchResult searchMerchantsCount ( ueSecurityToken Token, SearchParam Search, boolean MatchAll, integer Start, integer Limit, string Sort)
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Reseller security token, used to identify reseller and validate request. |
| %SearchParam% | array | Array of search parameters. |
| MatchAll | boolean | If set to "true," only results matching all search criteria will be returned, if set to "false," results matching any of the search criteria will be returned. |
| Start | integer | Record number to start returning from (ie if 1,000 were found and you only want to receive the last 200 you would set Start=800 and Limit=200) |
| Limit | integer | Maximum number of records to return in result set. |
| Sort | string | Comma separated list of fields to sort by. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| %MerchantSearchResult% | Returns results of active merchant search based on search parameters set. |
Change History
| Version | Change |
|---|---|
| 1.2 | Method added in soap 1.2 release |
searchMerchantsCustom
Reseller only method
Use this method if you only need to view a few select fields of the merchants you are searching for. Since it will only return the fields you specify, it is more efficient than the searchMerchants method.
Related Methods
The following fields may be used to search the database for transactions:
- Merchant ID
- Contact
- Company
- Street
- Street2
- City
- State
- Zip
- Fax
- Phone
Syntax
string searchMerchants ( ueSecurityToken Token, SearchParam Search, boolean MatchAll, integer Start, integer Limit, string FieldList, string Format, string Sort)
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Reseller security token, used to identify reseller and validate request. |
| %SearchParam% | array | Array of search parameters. |
| MatchAll | boolean | If set to "true," only results matching all search criteria will be returned, if set to "false," results matching any of the search criteria will be returned. |
| Start | integer | Record number to start returning from (ie if 1,000 were found and you only want to receive the last 200 you would set Start=800 and Limit=200) |
| Limit | integer | Maximum number of records to return in result set. |
| Sort | string | Comma separated list of fields to sort by. |
| FieldList | list | List of fields to return in search. |
| Format | string | Specify format of return data. Possible formats include: csv, tab, xml. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| searchMerchantsCustomReturn | string | Base64 encode result set. Returns all of the fields from any merchants matching your search parameters. |
Change History
| Version | Change |
|---|---|
| 1.2 | Method added in soap 1.2 release |
searchMerchantApplications
Example Request
<?php
try {
$search=array(
array('Field'=>'State', 'Type'=>'eq','Value'=>'CA'),
array('Field'=>'Contact', 'Type'=>'eq', 'Value'=>'John Doe'),
array('Field'=>'Company', 'Type'=>'eq', 'Value'=>'DidorightInc.')
);
$start=0;
$limit=100;
$matchall=true;
$sortby='merchid';
$res=$client->searchMerchantApplications($restoken,$search,$matchall,$start,$limit, $sortby);
}
catch (SoapFault $e) {
echo $client->__getLastRequest();
echo $client->__getLastResponse();
die("searchMerchantApplications failed: " .$e->getMessage());
}
?>
SearchParamArray params = new SearchParamArray();
params.add(new SearchParam("State", "eq", "CA"));
MerchantApplicationSearchResult result;
result = client.searchMerchantApplications(restoken, params, true, BigInteger.ZERO, new BigInteger("100"), "MerchRefNum");
System.out.println("Found Merchant: " + result.getApplications().getMerchantApplications().get(1).getMerchantName());
Reseller only method
This method allows resellers to search their database for merchant applications based on specific criteria.
The following fields may be searched via this method:
- AppRefNum
- Contact
- Company
- Street
- Street 2
- City
- State
- Zip
- Fax
- Phone Number
If MatchAll is set to "true," then only results matching ALL of your search criteria will be returned. If your search does not yield the desired results, eliminate some of you search terms or set MatchAll to "false."
Related Methods
- addMerchantApplication
- getMerchantApplicationStatus
- getMerchant
- updateMerchant
- deleteMerchant
- getMerchantSummary
Syntax
MerchantApplicationSearchResult searchMerchantApplications ( ueSecurityToken Token, SearchParam Search, boolean MatchAll, integer Start, integer Limit, string Sort)
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Reseller security token, used to identify reseller and validate request. |
| %SearchParam% | array | Array of search parameters. |
| MatchAll | boolean | If set to "true," only results matching all search criteria will be returned, if set to "false," results matching any of the search criteria will be returned. |
| Start | integer | Record number to start returning from (ie if 1,000 were found and you only want to receive the last 200 you would set Start=800 and Limit=200) |
| Limit | integer | Maximum number of records to return in result set. |
| Sort | string | Comma separated list of fields to sort by. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| %MerchantApplicationSearchResult% | object | Returns results of merchant application search based on search parameters set. |
Change History
| Version | Change |
|---|---|
| 1.4 | Added method |
searchMerchantApplicationsCount
Reseller only method.
Identical to the searchMerchantApplications method except only the application counts are returned. Like searchMerchantApplications, this method returns MerchantApplicationSearchResult. The only difference is that MerchantApplicationSearchResult.Applications is left empty. This method provides a quicker way to determine the size of the result set before starting to retrieve the full search results.
Related Methods
- addMerchantApplication
- getMerchantApplicationStatus
- getMerchant
- updateMerchant
- deleteMerchant
- getMerchantSummary
- searchMerchantApplications
- searchMerchantApplicationsCustom
Syntax
MerchantApplicationSearchResult searchMerchantApplicationsCount ( ueSecurityToken Token, SearchParam Search, boolean MatchAll, integer Start, integer Limit, string Sort)
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Reseller security token, used to identify reseller and validate request. |
| %SearchParam% | array | Array of search parameters. |
| MatchAll | boolean | If set to "true," only results matching all search criteria will be returned, if set to "false," results matching any of the search criteria will be returned. |
| Start | integer | Record number to start returning from (ie if 1,000 were found and you only want to receive the last 200 you would set Start=800 and Limit=200) |
| Limit | integer | Maximum number of records to return in result set. |
| Sort | string | Comma separated list of fields to sort by. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| MerchantApplicationSearchResult | object | Returns results of merchant application search based on search parameters set. |
searchMerchantApplicationsCustom
Reseller only method.
Use this method if you only need to view a few select fields of the applications you are searching for. Since it will only return the fields you specify, it is more efficient than the searchMerchantApplications method.
Related Methods
- addMerchantApplication
- getMerchantApplicationStatus
- getMerchant
- updateMerchant
- deleteMerchant
- getMerchantSummary
- searchMerchantApplications
- searchMerchantApplicationsCount
Syntax
string searchMerchantApplicationsCustom ( ueSecurityToken Token, SearchParam Search, boolean MatchAll, integer Start, integer Limit, string FieldList, string Format, string Sort)
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Reseller security token, used to identify reseller and validate request. |
| %SearchParam% | array | Array of search parameters. |
| MatchAll | boolean | If set to "true," only results matching all search criteria will be returned, if set to "false," results matching any of the search criteria will be returned. |
| Start | integer | Record number to start returning from (ie if 1,000 were found and you only want to receive the last 200 you would set Start=800 and Limit=200) |
| Limit | integer | Maximum number of records to return in result set. |
| Sort | string | Comma separated list of fields to sort by. |
| FieldList | list | List of fields to return in search. |
| Format | string | Specify format of return data. Possible formats include: csv, tab, xml. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| searchMerchantApplicationsCustomReturn | string | Base64 encode result set. Returns all of the fields from any transactions matching your search parameters. |
Change History
| Version | Change |
|---|---|
| 1.4 | Added method |
getMerchantSummary
Example Request
<?php
try {
$MerchantID=2;
$StartDate='2007-01-01';
$EndDate='2007-01-31';
$res=$client->getMerchantSummary($restoken, $MerchantID, $StartDate, $EndDate);
$this->assertEquals($res->MerchantID, $MerchantID);
$this->assertTrue($res->SalesCount>1);
}
catch (SoapFault $e) {
echo $client->__getLastRequest();
echo $client->__getLastResponse();
die("getMerchant failed: " .$e->getMessage());
}
?>
Dim MerchRefNum = 123456
Dim StartDate = "2011-05-01"
Dim EndDate = "2011-05-31"
Dim Summary As resellerapi.MerchantSummary
Try
Summary = client.getMerchantSummary(token, MerchRefNum, StartDate, EndDate)
MsgBox("Sales Count: " & Summary.SalesCount)
Catch ex As Exception
MsgBox("Exception: " & ex.Message)
End Try
BigInteger merchrefnum = new BigInteger("118227");
MerchantSummary summary;
summary = client.getMerchantSummary(restoken, merchrefnum, "2010-01-01", "2010-10-01");
<?xml version="1.0" encoding="UTF-8"?>`
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:ueresapi"
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:getMerchantSummary>
<Token xsi:type="ns1:ueSecurityToken">
<ClientIP xsi:type="xsd:string">192.168.0.1</ClientIP>
<PinHash xsi:type="ns1:ueHash">
<HashValue xsi:type="xsd:string">5cc04de62c82f2dad5ee51394b3a5bb012d231a3</HashValue>
<Seed xsi:type="xsd:string">12819820871527226844</Seed>
<Type xsi:type="xsd:string">sha1</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">R:OYZG7PKcLqZ6XYaOOGy255w0K6YWc7</SourceKey>
</Token>
<MerchRefNum xsi:type="xsd:integer">117806</MerchRefNum>
<Start xsi:type="xsd:string">2010-08-06</Start>
<End xsi:type="xsd:string">2010-08-17</End>
</ns1:getMerchantSummary>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example Response
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:ueresapi"
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:getMerchantSummaryResponse>
<getMerchantSummaryReturn xsi:type="ns1:MerchantSummary">
<CheckRefundsAmount xsi:type="xsd:double">235.9</CheckRefundsAmount>
<CheckRefundsCount xsi:type="xsd:integer">80</CheckRefundsCount>
<CheckSalesAmount xsi:type="xsd:double">91077.89</CheckSalesAmount>
<CheckSalesCount xsi:type="xsd:integer">896</CheckSalesCount>
<ReturnedCheckRefundAmount xsi:type="xsd:double">23</ReturnedCheckRefundAmount>
<ReturnedCheckRefundCount xsi:type="xsd:integer">4</ReturnedCheckRefundCount>
<ReturnedCheckSaleAmount xsi:type="xsd:double">46.01</ReturnedCheckSaleAmount>
<ReturnedCheckSaleCount xsi:type="xsd:integer">3</ReturnedCheckSaleCount>
<CheckChargebacksAmount xsi:type="xsd:double">117.78</CheckChargebacksAmount>
<CheckChargebacksCount xsi:type="xsd:integer">17</CheckChargebacksCount>
<SettledCheckRefundAmount xsi:type="xsd:double">7880.99</SettledCheckRefundAmount>
<SettledCheckRefundCount xsi:type="xsd:integer">19</SettledCheckRefundCount>
<SettledCheckSaleAmount xsi:type="xsd:double">5101.02</SettledCheckSaleAmount>
<SettledCheckSaleCount xsi:type="xsd:integer">21</SettledCheckSaleCount>
<CheckDepositCount xsi:type="xsd:integer">135</CheckDepositCount>
<LargeCheckRefundsAmount xsi:type="xsd:double">3.12</LargeCheckRefundsAmount>
<LargeCheckRefundsCount xsi:type="xsd:integer">4</LargeCheckRefundsCount>
<LargeCheckSalesAmount xsi:type="xsd:double">14.88</LargeCheckSalesAmount>
<LargeCheckSalesCount xsi:type="xsd:integer">3</LargeCheckSalesCount>
<CreditsAmount xsi:type="xsd:double">0</CreditsAmount>
<CreditsCount xsi:type="xsd:integer">0</CreditsCount>
<DeclinesAmount xsi:type="xsd:double">0</DeclinesAmount>
<DeclinesCount xsi:type="xsd:integer">0</DeclinesCount>
<MerchRefNum xsi:type="xsd:integer">117806</MerchRefNum>
<MerchantName xsi:type="xsd:string">Example Merchant</MerchantName>
<SalesAmount xsi:type="xsd:double">0</SalesAmount>
<SalesCount xsi:type="xsd:integer">0</SalesCount>
<VoidsAmount xsi:type="xsd:double">0</VoidsAmount>
<VoidsCount xsi:type="xsd:integer">0</VoidsCount>
</getMerchantSummaryReturn>
</ns1:getMerchantSummaryResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Reseller only method
This method allows you to view a summary of a specific merchant's activity during a specified time period. The start and end dates that you set for the search are inclusive.
Use the MerchantID (unique merchant identification assigned by the gateway) to fine the merchant whose activity you would like to view.
Activity included in the search results include details about the number of sales, credits, voids, declines, errors, checks and check refunds.
Related Methods
- addMerchantApplication
- getMerchantApplicationStatus
- getMerchant
- updateMerchant
- deleteMerchant
- searchMerchants
Syntax
MerchantSummary getMerchantSummary ( ueSecurityToken Token, integer MerchantID, string Start, string End )
Request Parameters
| Name | Type | Description |
|---|---|---|
| %ueSecurityToken% | object | Reseller security token, used to identify reseller and validate request. |
| MerchantID | integer | Merchant ID number assigned by the gateway to an active merchant. |
| Start | string | Date for start of summary. |
| End | string | Date for end of summary. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| %MerchantSummary% | object | Returns summary of merchant activity for specified time period. |
Boarding Objects
BillingInfo
Contains billing information for a merchant or merchant application.
Contains the billing information for either an active merchant or a merchant application. It is submitted when adding a new merchant applications as part of the MerchantApplication object.
Places Used
Properties
| Name | Type | Description |
|---|---|---|
| BankName | String | Name of merchant's bank (business checking, not merchant bank) |
| RoutingNumber | String | Routing number for merchant's checking account |
| AccountNumber | String | Account number for merchant's checking account |
| GatewayPackage | String | Name of the gateway package. Affects the merchant's monthly gateway fee and what features are enabled for them. Typical options are "Silver Package", "Gold Package (Cust DB)", "Gold Package (Fraud Center)" and "Platinum Package" unless reseller has configured custom packages. |
ContactInfo
Contains contact information for a merchant application.
Contacts the contact information for a merchant application. This is a parameter in the MerchantApplication object.
Places Used
Properties
| Name | Type | Description |
|---|---|---|
| Contact | string | First and last name of primary contact for merchant |
| Street | string | |
| Street2 | string | |
| City | string | |
| State | string | |
| Zip | string | |
| Country | string | |
| string | Email address for primary contact | |
| AltEmail | string | Alternate email for merchant |
| URL | string | Merchant's website (optional) |
| Fax | string | Fax number (optional) |
| Phone | string | Primary phone number for contact |
| MobilePhone | string | Mobile phone or alternate phone number for primary contact |
Merchant
Contains contact information for an active merchant.
This object contains information for an active merchant. This should not be confused with the MerchantApplication which contains the data on a new merchant application.
Places Used
Properties
| Name | Type | Description |
|---|---|---|
| MerchRefNum | integer | gateway assigned Merchant ID |
| Activated | string | Date the merchant was created |
| ResellerEmail | string | Email address for reseller. |
| MerchantName | string | Company name of merchant, used to identify merchant |
| %ContactInfo% | object | Address and contact information for merchant |
| CallInPassword | string | Optional call in password for merchant. If a merchant has a call in password, they must provide this password to customer support staff before support will be given. If no call in password is set, support staff will verify merchant account info to clear the merchant |
| %BillingInfo% | object | Billing information and gateway package |
| CreditCardPlatform | string | Name of the credit card processor to set the merchant up on. Possible values are: FDMS, Tsys, Paymentech, Global, Planet Payment, MeS and Heartland. Leave blank if no credit card processing is requested. |
| CreditCardPlatformSetup | FieldValue | Array of processor specific setup information |
| eCheckPlatform | string | Name of the electronic check processor to set the merchant up on. |
| eCheckPlatformSetup | FieldValue | Array of processor specific setup information |
MerchantApplication
Contains information for a merchant application.
New merchants are added to the gateway by submitting a merchant application. The application is reviewed for accuracy and if all information is correct, will be converted into an active merchant account. Applications are typically activated within 1-2 hours during business hours and within 12 hours during non-business hours.
This object contains all of the information necessary for submitting a new merchant application. All fields must be passed. You only need to populate platform fields required by the platform specified. If a required field is left blank, a soapfault will be thrown, non-required fields must be passed, but may be left blank.
Places Used
Properties
Example Object
<?php
$App=new stdClass();
$App->ResellerEmail='applications@reseller.com';
$App->ContactInfo = new stdClass();
$App->MerchantName = "Acme Bagel Company";
$App->ContactInfo->Contact = "John Doe";
$App->ContactInfo->Street ='4929 Wilshire Blvd';
$App->ContactInfo->Street2 ='Suite 800';
$App->ContactInfo->City ='Los Angeles';
$App->ContactInfo->State ='CA';
$App->ContactInfo->Zip ='90010';
$App->ContactInfo->Country ='US';
$App->ContactInfo->Email = 'john@acme.com';
$App->ContactInfo->Fax ='012134567890';
$App->ContactInfo->Phone ='687668678677';
$App->ContactInfo->MobilePhone='798787978788';
$App->ContactInfo->AltEmail='mary@tmcode.com';
$App->ContactInfo->URL = 'http://acme bagels.com';
$App->BillingInfo = new stdClass();
$App->BillingInfo->BankName = 'Bank of America';
$App->BillingInfo->RoutingNumber = '12342313312';
$App->BillingInfo->AccountNumber = '57655765754';
$App->BillingInfo->GatewayPackage = 'Platinum Package';
$App->CreditCardPlatform = 'FDMS';
$App->CreditCardIndustry = 'Retail (Swipe)';
$App->CreditCardPlatformSetup = array();
$App->CreditCardPlatformSetup[] = array('Field'=>'MerchantNum', 'Value'=>'4454900399430020');
$App->CreditCardPlatformSetup[] = array('Field'=>'MerchantID', 'Value'=>'382772891');
$App->CreditCardPlatformSetup[] = array('Field'=>'TerminalID', 'Value'=>'112198000');
$App->eCheckPlatform = 'Vericheck';
$App->eCheckPlatformSetup = array();
$App->eCheckPlatformSetup[] = array('Field'=>'DefaultSEC', 'Value'=>'TEL');
$App->eCheckPlatformSetup[] = array('Field'=>'TaxID', 'Value'=>'123456789');
$App->eCheckPlatformSetup[] = array('Field'=>'PIN', 'Value'=>'231');
$App->eCheckPlatformSetup[] = array('Field'=>'MID', 'Value'=>'11231');
$App->eCheckPlatformSetup[] = array('Field'=>'AcceptedSecCodes', 'Value'=>'TEL,PPD,CCD');
$App->SourceKeyName = 'My Shopping Cart';
$App->SourceKeyPin = '1351';
$App->EmailSourceKeyTo = 'demo@acmebagels.com';
$App->UserName = 'acmebagels';
$App->EmailInstructionsTo = 'demo@acmebagels.com';
$App->ApplicationNotes = 'An example note for merchant application';
?>
MerchantApplication merchantapp = new MerchantApplication();
merchantapp.setApplicationNotes("Application notes");
BillingInfo billing = new BillingInfo();
billing.setBankName("Example Bank");
billing.setRoutingNumber("123456789");
billing.setAccountNumber("910293112");
billing.setGatewayPackage("Silver Package");
merchantapp.setBillingInfo(billing);
merchantapp.setCallInPassword("1234");
ContactInfo contactinfo = new ContactInfo();
contactinfo.setContact("John Doe");
contactinfo.setStreet("4929 Wilshire Blvd");
contactinfo.setStreet2("Suite 899");
contactinfo.setCity("Los Angeles");
contactinfo.setState("CA");
contactinfo.setZip("90010");
contactinfo.setCountry("US");
contactinfo.setEmail("merchant@tmcode.com");
contactinfo.setAltEmail("merchant@tmcode.com");
contactinfo.setPhone("222-333-4446");
contactinfo.setMobilePhone("222-333-4445");
contactinfo.setFax("222-333-4444");
contactinfo.setURL("http://www.acme.org");
merchantapp.setContactInfo(contactinfo);
merchantapp.setCreditCardIndustry("eCommerce");
merchantapp.setCreditCardPlatform("FDMS");
FieldValueArray platformdata = new FieldValueArray();
platformdata.add(new FieldValue("MerchantNum","2334566356345"));
platformdata.add(new FieldValue("MerchantID","1231230"));
platformdata.add(new FieldValue("TerminalID","1231239"));
merchantapp.setCreditCardPlatformSetup(platformdata);
merchantapp.setECheckPlatform("Vericheck");
FieldValueArray checkplatform = new FieldValueArray();
checkplatform.add(new FieldValue("DefaultSEC","TEL"));
checkplatform.add(new FieldValue("TaxID","123456789"));
checkplatform.add(new FieldValue("PIN","231"));
checkplatform.add(new FieldValue("MID","11231"));
checkplatform.add(new FieldValue("AcceptedSecCodes","TEL,PPD,CCD"));
merchantapp.setECheckPlatformSetup(checkplatform);
merchantapp.setEmailInstructionsTo("merchant@tmcode.com");
merchantapp.setEmailSourceKeyTo("merchant@tmcode.com");
merchantapp.setMerchantName("Example Company");
merchantapp.setResellerEmail("reselller@tmcode.com");
merchantapp.setSourceKeyName("ShoppingCart");
merchantapp.setSourceKeyPin("1234");
merchantapp.setUserName("jdoe23");
| Name | Type | Description |
|---|---|---|
| ResellerEmail | string | Email address for reseller. |
| MerchantName | string | Company name of merchant, used to identify merchant |
| %ContactInfo% | object | Address and contact information for merchant |
| CallInPassword | string | Optional call in password for merchant. If a merchant has a call in password, they must provide this password to customer support staff before support will be given. If no call in password is set, support staff will verify merchant account info to clear the merchant |
| %BillingInfo% | BillingInfo | Billing information and gateway package |
| SourceKeyName | string | Name of SourceKey to create when merchant is activated. Leave blank if no source key is requested |
| SourceKeyPin | string | Pin to assign to new SourceKey |
| EmailSourceKeyTo | string | Email address to send the new sourcekey to. The email will contain the sourcekey but not the pin |
| UserName | string | Username of merchant user that will be created when the application is activated. A password will be randomly assigned by the system. Merchant must change the password the first time they log in |
| EmailInstructionsTo | string | Email address to send the merchant console instructions to. The email will include the merchants username and password |
| CreditCardPlatform | string | Name of the credit card processor to set the merchant up on. Possible values are: FDMS, FDMS North, Tsys, Paymentech, Global, MeS, Rapid Connect, EPX and Heartland. Leave blank if no credit card processing is requested. |
| CreditCardIndustry | string | Merchant Industry type: "eCommerce", "Mail Order", "Retail (Swipe)", "Hotel", "Restaurant", "Utility/Bill Pay", "Utility/Bill Pay (Card Present)" |
| CreditCardPlatformSetup | FieldValue | Array of processor specific setup information (see below) |
| eCheckPlatform | string | Name of the electronic check processor to set the merchant up on. Possible values are: Vericheck, Checkgateway, Payliance, and Paya. Leave blank if no check processing is requested. |
| eCheckPlatformSetup | FieldValue | Array of processor specific setup information (contact integration support for list of fields) |
| ApplicationNotes | string | Notes or instructions for gateway staff activating merchant account, ie "Hold application until 3/4/10" |
| MerchRefNum | integer | Contains the Merchant ID Number once the application has been activated |
| ApplicationID | integer | The gateway assigned Application ID |
| Status | string | Contains the status of the application |
Credit Card Platform Setup
The fields required vary depending on the platform being used. The following fields apply to all platforms:
| Name | Type | Description |
|---|---|---|
| CreditPolicy | string | This sets the level of restrictions placed on a merchants ability to issue credits (refunds) to a credit cards. Possible values (listed from least to most restrictive): "No Restrictions", "Minimal Restrictions", "Require Prior Sale", "Connected Refunds Only", "Block All Credits" |
| AutoBatchClosure | string | The desired schedule for automatically closing the merchants open batch. If omitted, the setting from the selected Package will be used. Can either be every x hours: '6 hours', '12 hours', '24 hours', '36 hours', '48 hours', '72 hours' or it can be a specific time of day: '3:45pm'. Multiple closures can be specified in a comma separated list: '6:30am,7:39pm,11:55pm' |
| ConsoleVersion | integer | Set the desired console version |
FDMS Nashville
| Name | Example | Notes |
|---|---|---|
| MerchantNum | 4120949485344948 | |
| MerchantID | 0000000 | |
| TerminalID | 0000000 |
FDMS North
| Name | Example | Notes |
|---|---|---|
| MerchantID | 123456789012 | |
| TerminalID | alphanumeric | 1234567 |
| MCC | 1234 | Merchant category code (4 digits) |
| TaxID | 000000000 | |
| Level3 | Y | Y/N - Denotes if level 3 processing should be enabled. Y to enable and N to disable. Defaults to disabled. |
| DefaultCommodityCode | 00 | Only required of Level 3 processing is enabled. |
First Data Rapid Connect
| Name | Type | Example | Description |
|---|---|---|---|
| MerchantNum | integer | 4120949485344948 | |
| MerchantID | string | RCTST0000008056 | |
| TerminalID | integer | 1234567 | |
| MCC | integer | 1234 | Merchant category code (4 digits) |
| GroupID | integer | 10001 | |
| TaxID | integer | 0000 | |
| SettlementID | integer | 987654321012 | Settlement terminal id |
| Level3 | boolean | Y | Denotes if level 3 processing should be enabled. Y to enable and N to disable. Defaults to disabled. |
| DefaultCommodityCode | integer | 00 | Only required of Level 3 processing is enabled. |
| PinDebitSupport | boolean | Set to 'True' to enable debit processing |
Tsys
| Name | Example | Notes |
|---|---|---|
| AcquirerBIN | 123456 | |
| MerchantNum | 891234567890 | |
| AgentBank | 000000 | |
| AgentChain | 000000 | |
| StoreNumber | 0001 | |
| TerminalNumber | 0001 | |
| MCC | 1234 | Merchant category code (4 digits) |
| VNumber | 1234567 | Only needed for Tsys |
| MerchantName | ACME BAGELS | Merchant name as it will appear on cardholder statement |
| MerchantState | CA | |
| MerchantZip | 90010 | |
| ServicePhoneNumber | 3239312233 | Customer Service number for merchant |
| AmexLevel2 | Y | Merchant is enrolled to process level 2 corporate purchasing cards (Y/N) |
| PinDebitSupport | boolean | Set to 'True' to enable debit processing |
| DebitNetworks | V,P,T | Comma separated list of one character debit network codes |
| Level3 | boolean | Y |
MeS and Heartland
| Name | Example | Notes |
|---|---|---|
| AcquirerBIN | 123456 | |
| MerchantNum | 891234567890 | |
| AgentBank | 000000 | |
| AgentChain | 000000 | |
| StoreNumber | 0001 | |
| TerminalNumber | 0001 | |
| MCC | 1234 | Merchant category code (4 digits) |
| VNumber | 1234567 | Only needed for Tsys |
| MerchantName | ACME BAGELS | Merchant name as it will appear on cardholder statement |
| MerchantState | CA | |
| MerchantZip | 90010 | |
| ServicePhoneNumber | 3239312233 | Customer Service number for merchant |
| AmexLevel2 | Y | Merchant is enrolled to process level 2 corporate purchasing cards (Y/N) |
| PinDebitSupport | boolean | Set to 'True' to enable debit processing |
Paymentech
| Name | Example | Notes |
|---|---|---|
| ClientNumber | 1234 | |
| MerchantID | 012345678901 | |
| TerminalNumber | 001 |
Global
| Name | Example | Notes |
|---|---|---|
| BankID | 123456 | |
| MerchantID | 4567890123456 |
EPX
| Name | Type | Example | Description |
|---|---|---|---|
| CustNum | string | 5001 | Max length of 16 numeric digits - This will usually be 4 digits |
| MerchNum | string | 3130030000000 | Max length of 16 numeric digits |
| TerminalNum | string | 1 | Max length of 16 numeric digits |
| DbaNum | string | 1 | Max length of 16 numeric digits |
| Mac | string | 1 | Max length of 80 numeric digits (optional) |
| PinDebitSupport | boolean | Set to 'True' to enable debit processing |
Vantiv
| Name | Type | Description |
|---|---|---|
| BankID | integer | 123456 |
| MerchantID | integer | 567890123456 |
| TerminalID | integer | 001 |
| DebitTerminalID | integer | 000 |
| PinDebitSupport | boolean | Set to 'True' to enable debit processing |
Check Platform Setup
The fields required vary depending on the platform being used. The following fields apply to all platforms:
Vericheck
| Name | Type | Description |
|---|---|---|
| DefaultSEC | string | Default Check Format. Click here for more info on check formats. |
| TaxID | string | |
| PIN | string | |
| MID | string |
Checkgateway
| Name | Type | Description |
|---|---|---|
| DefaultSEC | string | Default Check Format. Click here for more info on check formats. |
| Username | string | Required |
Paya
| Name | Type | Description |
|---|---|---|
| DefaultSEC | string | Default Check Format. Click here for more info on check formats. |
| TerminalID_WEB | string | |
| TerminalID_POP | string | |
| TerminalID_TEL | string | |
| TerminalID_PPD | string | |
| TerminalID_CCD | string | |
| TerminalID_C21 | string |
Payliance
| Name | Type | Description |
|---|---|---|
| DefaultSEC | string | Default Check Format. Click here for more info on check formats. |
| MerchantID | string | Required |
| Password | string | Required |
| Location | string | Required |
CrossCheck
| Parameter | Type | Description |
|---|---|---|
| Username | string | Required |
| Password | string | Required |
ACH Solutions
| Parameter | Type | Description |
|---|---|---|
| Username | string | Required |
| Password | string | Required |
| DefaultSEC | string | Default Check Format. Click here for more info on check formats. |
Reliafund
| Parameter | Type | Description |
|---|---|---|
| Username | string | Required |
| Password | string | Required |
| DefaultSEC | string | Default Check Format. Click here for more info on check formats. |
Actum
| Parameter | Type | Description |
|---|---|---|
| TELParentID | string | |
| TELSubID | string | |
| TELUsername | string | |
| TELPassword | string | |
| TELSystemPassword | string | |
| PPDParentID | string | |
| PPDSubID | string | |
| PPDUsername | string | |
| PPDPassword | string | |
| PPDSystemPassword | string | |
| CCDParentID | string | |
| CCDSubID | string | |
| CCDUsername | string | |
| CCDPassword | string | |
| CCDSystemPassword | string | |
| WEBParentID | string | |
| WEBSubID | string | |
| WEBUsername | string | |
| WEBPassword | string | |
| WEBSystemPassword | string | |
| DefaultSEC | string | Default Check Format. Click here for more info on check formats. |
MerchantApplicationSearchResult
Contains the results of a merchant search.
This object is returned by the searchMerchantApplications method. It describes the result of the search, including the total number of merchants matched, the number being returned, and an array of MerchantObjects.
Places Used
Properties
| Name | Type | Description |
|---|---|---|
| Limit | integer | The maximum number of merchants to be returned. |
| %Applications% | object | An array of Merchant application objects that match the search criteria. |
| ApplicationsMatched | integer | Number of merchants applications matched by search criteria. |
| ApplicationsReturned | integer | Number of merchants applications contained in this search result. |
| StartIndex | integer | The index where this result set begins (default is 0). |
MerchantSearchResult
Contains the results of a merchant search.
This object is returned by the searchMerchants method. It describes the result of the search, including the total number of merchants matched, the number being returned, and an array of MerchantObjects.
Places Used
Properties
| Name | Type | Description |
|---|---|---|
| MerchantsMatched | integer | Number of merchants matched by search criteria. |
| MerchantsReturned | integer | Number of merchants contained in this search result. |
| StartIndex | integer | The index where this result set begins (default is 0). |
| Limit | integer | The maximum number of merchants to be returned. |
| %Merchant% | object | An array of MerchantObjects matched by search criteria. |
MerchantSummary
Summary of merchant activity over a given time period.
Time period to be analyzed must be specified in the initial search using the getMerchantSummary method. All information returned applies only to the specified time period and is not a definitive total of all of the merchant's transaction information. The summary data is not real time and can lag up to 2 hours.
Places Used
Properties
| Name | Type | Description |
|---|---|---|
| MerchantID | integer | Merchant ID (assigned by the gateway). |
| MerchantName | string | Name of the merchant whose activity you are searching. |
| SalesCount | integer | Total number of sales processed by the merchant. |
| SalesAmount | double | Total dollar amount of sales processed. |
| CreditsCount | integer | Total number of credits processed by the merchant. |
| CreditsAmount | double | Total dollar amount of credits processed. |
| VoidsCount | integer | Total number of voids processed by the merchant. |
| VoidsAmount | double | Total dollar amount of voids processed. |
| DeclinesCount | integer | Total number of declines processed by the merchant. |
| DeclinesAmount | double | Total dollar amount of declines processed |
| CheckSalesCount | integer | Total number of check sales processed (by date entered) |
| CheckSalesAmount | double | Total dollar amount of check sales processed (by date entered) |
| CheckRefundsCount | integer | Total number of check refunds processed (by date entered) |
| CheckRefundsAmount | double | Total dollar amount of check refunds processed (by date entered) |
| ReturnedCheckSaleCount | integer | Total number of check sales returned (by date returned) |
| ReturnedCheckSaleAmount | double | Total dollar amount of check sales returned (by date returned) |
| ReturnedCheckRefundCount | integer | Total number of check refunds returned (by date returned) |
| ReturnedCheckRefundAmount | double | Total dollar amount of check refunds returned (by date returned) |
| CheckChargebacksCount | integer | Total number of check sales returned as chargebacks (by date returned) |
| CheckChargebacksAmount | double | Total dollar amount of check sales returned as chargebacks (by date returned) |
| SettledCheckSaleCount | integer | Total number of check sales settled (by date settled) |
| SettledCheckSaleAmount | double | Total dollar amount of check sales settled (by date settled) |
| SettledCheckRefundCount | integer | Total number of check refunds settled (by date settled) |
| SettledCheckRefundAmount | double | Total dollar amount of check refunds settled (by date settled) |
| LargeCheckSalesCount | integer | Total number of large check sales processed (by date entered). Large checks are any ach transaction that exceeds a merchants defined threshold (typically $5,000) |
| LargeCheckSalesAmount | double | Total dollar amount of large check sales processed (by date entered) |
| LargeCheckRefundsCount | integer | Total number of large check refunds processed (by date entered) |
| LargeCheckRefundsAmount | double | Total dollar amount of Large check refunds processed (by date entered) |
| CheckDepositCount | integer | Total number of ach batches deposited to merchant (not support for all ach platforms) |
| Name | Type | Description |
|---|---|---|
| Type | string | Hashing Function Used: Currently only "md5" and "sha1" are supported. |
| Seed | string | The data used to seed the hash: This value must be unique and cannot be reused. The system will reject the request if a Seed is reused. The reason for this is to minimize the damage if a HashValue is stolen. An intruder may manage to obtain a SourceKey and a HashValue, but will not be able to use the source key since the HashValue is based on a seed that cannot be reused. |
| HashValue | string | Hash string: The resulting hash. The hash is calculated by concatenating the SourceKey, the Seed and the Pin value. Do not place any characters in between these values. Once the values have been concatenated, calculate the hash string using the algorithm specified by Type. |
| Name | Type | Description |
|---|---|---|
| SourceKey | string | SourceKey obtained in merchant console. |
| PinHash | ueHash | Hash object for the PIN (only necessary if this source key has a pin assigned) |
| ClientIP | string | The IP Address of the end client |
| Name | Type | Description |
|---|---|---|
| CreditCardPlatform | string | Name of Card Processing Platform, "Disabled" if no credit card support |
| Industry | string | Account Industry (eCommerce, Mail Order, Retail, Restaurant, Hotel) |
| CheckPlatform | string | Name of Check Processor, "Disabled" if no support for checks. |
| CardholderAuthentication | string | Integrated cardholder authentication (Verified by Visa or MC 3D Secure) |
| DebitCardSupport | boolean | True if merchant has support for processing pin based debit cards |
| DirectPayPlatform | string | Name of the direct payment platform if supported |
| CurrencyObject | object | Array of currencies supported by merchant. Empty if using a non-multicurrency enabled credit card processor. |
| Name | Type | Description |
|---|---|---|
| ResellerEmail | string | Email address for reseller. |
| MerchantName | string | Company name of merchant, used to identify merchant |
| ContactInfo | object | Address and contact information for merchant |
| CallInPassword | string | Optional call in password for merchant. If a merchant has a call in password, they must provide this password to customer support staff before support will be given. If no call in password is set, support staff will verify merchant account info to clear the merchant |
| BillingInfo | object | Billing information and gateway package |
| CreditCardPlatform | string | Name of the credit card processor to set the merchant up on. Possible values are: FDMS, Tsys, Paymentech, Global, Planet Payment, MeS and Heartland. Leave blank if no credit card processing is requested. |
| CreditCardIndustry | string | Merchant Industry type: "eCommerce", "Mail Order", "Retail (Swipe)", "Hotel", "Restaurant", "Utility/Bill Pay", "Utility/Bill Pay (Card Present)" |
| MerchRefNum | integer | Contains the Merchant ID Number once the application has been activated |
| AppRefNum | integer | Contains the Merchant Application ID Number once the application has been submitted. |
| Status | string | Contains the status of the application |
| Name | Type | Description |
|---|---|---|
| BatchKey | string | Batch reference number (assigned by the gateway). |
| BatchRefNum | string | A unique batch reference number assigned by the gateway. |
| Sequence | integer | Batch sequence number |
| Status | string | Status of this batch (ie: open, closing, closed) |
| Opened | string | Date/time the batch was opened (first transaction was run) |
| Closed | string | Date/time the batch was closed (if it has been closed) |
| Scheduled | string | Date/time the batch is scheduled to close |
| TransactionCount | integer | Number of transactions in the batch |
| SalesCount | integer | Number of sales in the batch |
| CreditsCount | integer | Number of credits in the batch |
| VoidsCount | integer | Number of voids in the batch |
| SalesAmount | double | Dollar amount of the sales |
| CreditsAmount | double | Dollar amount of the credits |
| NetAmount | double | Dollar amount of the sales-credits |
| VoidsAmount | double | Dollar amount of the voids |
| Name | Type | Description |
|---|---|---|
| BatchKey | string | Batch reference number (assigned by the gateway). |
| BatchRefNum | string | A unique batch reference number assigned by the gateway. |
| Sequence | integer | Batch sequence number |
| Status | string | Status of this batch (ie: open, closing, closed) |
| Opened | string | Date/time the batch was opened (first transaction was run) |
| Closed | string | Date/time the batch was closed (if it has been closed) |
| Scheduled | string | Date/time the batch is scheduled to close |
| TransactionCount | integer | Number of transactions in the batch |
| SalesCount | integer | Number of sales in the batch |
| CreditsCount | integer | Number of credits in the batch |
| VoidsCount | integer | Number of voids in the batch |
| SalesAmount | double | Dollar amount of the sales |
| CreditsAmount | double | Dollar amount of the credits |
| NetAmount | double | Dollar amount of the sales-credits |
| VoidsAmount | double | Dollar amount of the voids |
| Name | Type | Description |
|---|---|---|
| UploadRefNum | string | Upload reference number (assigned by the gateway). |
| Status | String | Current status of the upload batch. |
| Started | String | Date and time the batch upload was initiated. |
| Finished | String | Date and time the batch upload was completed. |
| Transactions | Integer | Total number of transactions in the upload batch. |
| Remaining | Integer | Number transactions remaining to be run. |
| Approved | Integer | Number of transactions that have been approved. |
| Declined | Integer | Number of transactions that have been declined. |
| Errors | Integer | Number of transactions that resulted in errors. |
| Name | Type | Description |
|---|---|---|
| FirstName | String | Customer's First Name |
| LastName | String | Customer's Last Name |
| Company | String | Company or Organization Name |
| Street | String | Street Address Line 1 |
| Street2 | String | Street Address Line 2 |
| City | String | City |
| State | String | State or Province |
| Zip | String | Zip or Postal Code |
| Country | String | Country |
| Phone | String | Telephone Number |
| Fax | String | Fax Number |
| String | Email Address |
| Name | Type | Description |
|---|---|---|
| BankName | String | Name of merchant's bank (business checking, not merchant bank) |
| RoutingNumber | String | Routing number for merchant's checking account |
| AccountNumber | String | Account number for merchant's checking account |
| GatewayPackage | String | Name of the gateway package. Affects the merchant's monthly gateway fee and what features are enabled for them. Typical options are "Silver Package", "Gold Package (Cust DB)", "Gold Package (Fraud Center)" and "Platinum Package" unless reseller has configured custom packages. |
| Name | Type | Description |
|---|---|---|
| CheckNumber | Integer | Check number of check being used for transaction. |
| Routing | String | Nine digit bank routing number. |
| Account | String | Bank account number. |
| AccountType | String | Checking or Savings - if left blank, default is Checking. |
| DriversLicense | String | Driver's license of checking account holder. |
| DriversLicenseState | String | Driver's license state of issue. |
| RecordType | String | Record type of electronic check transaction. Not supported by all check processors. List of Check Record Types |
| MICR | String | MICR Data for Check 21 (optional, depending on processor) |
| AuxOnUS | String | MICR Data for Check 21 (optional, depending on processor) |
| EpcCode | String | MICR Data for Check 21 (optional, depending on processor) |
| FrontImage | String | Scan of front of check, base64 encoded (optional) |
| BackImage | String | Scan of back of check, base64 (optional) |
| SSN | String | Customer Social Security Number |
| Name | Type | Description |
|---|---|---|
| Status | string | Text description of the status code. |
| StatusCode | string | A single letter code indicating the status of a transaction. |
| TrackingNum | string | Reference number assigned by check processor. |
| Effective | string | Date check was originally posted. |
| Processed | string | Date check was received by processor. |
| Settled | string | Date check was originally settled. |
| Returned | string | Date check was returned. |
| ReturnCode | string | |
| Reason | string | |
| BankNote | string | Note from checking account holder's bank. Typically this note will explain the reason for a returned check, but it may also indicate future changes to routing/account number even if the electronic check transaction was approved. For example, if the customer's bank has been bought by another bank, the original routing number will only remain valid for about a year. During this period, the bank will send back a note indicating the new routing number. |
| Name | Type | Description |
|---|---|---|
| Contact | string | First and last name of primary contact for merchant |
| Street | string | |
| Street2 | string | |
| City | string | |
| State | string | |
| Zip | string | |
| Country | string | |
| string | Email address for primary contact | |
| AltEmail | string | Alternate email for merchant |
| URL | string | Merchant's website (optional) |
| Fax | string | Fax number (optional) |
| Phone | string | Primary phone number for contact |
| MobilePhone | string | Mobile phone or alternate phone number for primary contact |
| Name | Type | Description |
|---|---|---|
| CardType | string | Card Type - describes card issuer (Visa, MC, Amex, Discover). Read only property (ignored if sent as a parameter to transaction methods). |
| CardNumber | string | Card Number |
| CardExpiration | string | Expiration Date - Should be set to 4 digit MMYY. |
| CardCode | string | CVV2/CID card code value from back of card. Set to -2 if the code is not legible, -9 if the code is not on the card. |
| AvsStreet | string | Billing address associated with card, used by AVS. |
| AvsZip | string | Billing zipcode associated with card, used by AVS. |
| CardPresent | boolean | Indicates if the card is present during the transaction (ie: the card was swiped at a POS terminal). Used to indicate retail. |
| MagStripe | string | Track 1 and/or Track 2 data for swiped transactions. For unencrypted swipers send the raw data. For encrypted swipers please look at end to end encryption |
| DataSource | string | Entry mode of transaction. (Contactless, Card Not Present- Manually Keyed, Card Swiped, Chip Read) |
| DUKPT | string | DUKPT encrypted pin block. Only required for pin debit transactions. The first 16 characters are the encrypted pin block, followed by the 6 character long Key Set Identifier (KSID). The remaining characters are the Pin Pad serial number and transaction counter. |
| Signature | string | Signature capture image. Base64 encoded. |
| TermType | string | Terminal type (POS, StandAlone, Unattended, or Unknown). May be left blank if unknown. |
| MagSupport | string | Indicates whether software has support for mag swipe (Yes, No, Unknown). |
| XID | string | XID value received from 3rd party Visa VPAS or MC UCAF. |
| CAVV | string | CAVV value received from 3rd party Visa VPAS or MC UCAF. |
| ECI | integer | ECI value. |
| InternalCardAuth | boolean | Use gateway based authentication for Visa VPAS or MC UCAF. |
| Pares | string | Pares returned by client after successful |
| Name | Type | Description |
|---|---|---|
| CardRef | string | Unique token representing card |
| CardExpiration | string | Expiration Date of credit card |
| CardNumber | string | Masked card number |
| CardType | string | Type of card |
| Name | Type | Description |
|---|---|---|
| FromCurrency | string | Code of currency that transaction amount is being converted from. |
| FromAmount | double | Amount being converted. This amount is shown in the original currency, before the conversion takes place (FromCurrency). |
| Currency | string | Code of currency that transaction amount is being converted to. |
| Rate | double | Conversion rate used. |
| Amount | double | Amount converted to new currency. This amount is shown in the new currency that the amount has been converted to (Currency). |
| Name | Type | Description |
|---|---|---|
| NumericCode | integer | 3 digit numeric currency code to be used when processing transactions in the corresponding currency. |
| TextCode | string | 3 character currency code (ie: USD or EUR). |
| Currency | string | Full name of currency (ie: US Dollars or Euros). |
| Rate | double | Currency's current conversion rate. This is the conversion rate to the merchant's specified settling currency. |
| DecimalPlaces | integer | Number of positions to the right of the decimal (or whole units separator). Used for rounding (ie for USD 12.88, DecimalPlaces=2, for Japanese Yen 512 DecimalPlaces=0). |
| Name | Type | Description |
|---|---|---|
| CustNum | string | Customer Number (System assigned) |
| CustKey | string | Customer Number (System assigned) |
| CustomerID | string | Customer ID (Merchant assigned) |
| BillingAddress | object | Billing Address |
| PaymentMethod | array | Array of PaymentMethod objects. Multiple credit cards or ACH accounts may be stored for each customer. |
| CustomData | string | Custom data is a raw text field, please serialize and encode (ie: base64) your data so that complex types are stored and retrieved correctly. |
| CustomFields | array | Array of field values containing the merchant defined customer fields. These fields are defined in the merchant console. |
| URL | string | URL for customers website |
| Created | string | Date/Time customer was created (Read Only) |
| Modified | string | Date/Time customer was last changed (Read Only) |
| Enabled | boolean | Notes whether or not a customer has been enabled for a recurring billing cycle. The customer billing does not need to be enabled to run one time transactions via the runCustomerTransaction method. |
| Schedule | string | Recurring billing schedule, if any. Possible values include: daily, weekly, bi-weekly (every two weeks), monthly, bi-monthly (every two months), quarterly, bi-annually (every six months), annually, first of month, last day of month. |
| NumLeft | string | Number of transactions remaining in customer's recurring billing cycle. "-1" indicates unlimited transactions. |
| Next | string | Date of customer's next scheduled transaction. |
| Amount | double | Total Amount to be billed in recurring billing cycle. |
| Tax | double | Portion of Amount that is Tax |
| Currency | string | Numeric currency code for Amount. (Only needed if multicurrency merchant account) |
| Description | string | Description of transaction. |
| OrderID | string | Transaction Order ID |
| User | string | Merchant username assigned to billing. |
| Source | string | Name of source key assigned to billing. |
| SendReceipt | boolean | Send client a receipt. |
| ReceiptNote | string | Note to send on receipt. |
| Failures | integer | Number of failures since last approval. |
| PriceTier | string | Name of customer price tier |
| TaxClass | string | Tax Class (Group) |
| LookupCode | string | Lookup code from customer/member id card. Either barcode or Magnetic stripe. Can be assigned by merchants. Defaults to system assigned if left blank. |
| Name | Type | Description |
|---|---|---|
| CustomersMatched | integer | Total number of customers matched by search criteria. |
| CustomersReturned | integer | Total number of customers contained in search result. |
| StartIndex | integer | The index where this result set begins (default is 0). |
| Limit | integer | The maximum number of customers to be returned in the search. |
| CustomerObject | array | An array of CustomerObjects matched by search criteria. |
| Name | Type | Description |
|---|---|---|
| Command | string | Processing command to run. Possible values: Sale, AuthOnly, Credit, Check and CheckCredit. If a blank is passed, the default value is Sale for credit card or Check for checks |
| IgnoreDuplicate | boolean | Do not check for duplicate transaction. Set to "true" if you would like to override the duplicate transaction handling. |
| Details | object | Transaction details: amount, clerk, currency, |
| ClientIP | string | IP Address of client. |
| CustReceipt | boolean | Customer Receipt. Set to "true" if you would like the gateway to send an email to customer. |
| CustReceiptEmail | string | Email address to receipt to. If left blank, the receipt will be sent to the email address stored in the customer record. |
| CustReceiptName | string | Customer Receipt Template Name. Specify the name of the template to use. (Optional) |
| MerchReceipt | boolean | Send Merchant Receipt. Set to "true" if you would like the gateway to send a receipt to the merchant. |
| MerchReceiptEmail | string | Email address to receipt to. Required if MerchReceipt is set to true |
| MerchReceiptName | string | Merchant Receipt Template Name. Specify the name of the template to use. (Optional) |
| CustomFields | array | Array of FieldValue pairs. Additional transaction api fields (ie UMtimeout) can also be passed in via this array. Any field name starting with UM is assumed to be an api field and not a custom field. |
| isRecurring | boolean | Recurring flag Signals to the platform that this transaction is a recurring billing transaction. Use with caution, can cause downgrades if not used properly. Defaults to false which causes the transaction to run as a normal card not present transaction. |
| InventoryLocation | string | ID of warehouse to draw inventory from. If blank, uses setting from source key. If no setting in source key, inventory will not be adjusted. |
| CardCode | string | CVV2/CVC card id code. PCI requirements forbid storing CVV2 value. Customer must be prompted to enter this value each time a transaction is run. This value is not required unless CVV2 validation is desired. |
| LineItem | array | Array of line item details |
| Software | string | Free form string that can be used by the developer to record information about their software, version, build number or operating system details. Reported on the transaction detail screen, in custom reports or via api. (optional) |
| XID | string | XID value received from 3rd party Visa VPAS or MC UCAF. Can be sent with transaction, but cannot be stored in method. |
| CAVV | string | CAVV value received from 3rd party Visa VPAS or MC UCAF. Can be sent with transaction, but cannot be stored in method. |
| ECI | integer | ECI value. Can be sent with transaction, but cannot be stored in method. |
| Name | Type | Description |
|---|---|---|
| Field | string | Name of element. |
| Value | string | Value of element. |
| Name | Type | Description |
|---|---|---|
| Invoice | string | Transaction invoice number. Will be truncated to 10 characters. If this field is not provided, the system will submit the RefNum in its place. |
| PONum | string | Purchase Order Number for commercial card transactions - 25 characters. (Required for Level 2 & 3) |
| OrderID | string | Transaction order ID. This field should be used to assign a unique order id to the transaction. The order ID can support 64 characters. |
| SessionID | string | Optional Session ID used for customer analytics and fraud prevention. Must be get generated using the getSession method. See the profiling guide for more information |
| Clerk | string | Sales Clerk. Optional value indicating the clerk/person processing transaction, for reporting purposes. |
| Terminal | string | Terminal Name. Optional value indicating the terminal used to process transaction, for reporting purposes. |
| Table | string | Restaurant Table Number. Optional value indicating the restaurant table, for reporting purposes |
| LaneID | string | POS identification number set by merchant. |
| Description | string | Transaction description. |
| Comments | string | Comments. Free form text. |
| AllowPartialAuth | boolean | Allow a partial authorization if full amount is not available (Defaults to false) |
| Amount | double | Total billing amount. (Subtotal+Tax+Tip+Shipping-Discount=Amount.) |
| Currency | string | Currency Code. 3 digit currency code of total amount. |
| Tax | double | Portion of total amount that is tax. (Required for Level 2 & 3) |
| Tip | double | Portion of total amount that is tip. |
| NonTax | boolean | Determines whether a transaction is non-taxable. |
| Shipping | double | Portion of total amount that is shipping charges. (Required for Level 3) |
| ShipFromZip | double | Zipcode that the order is shipping from. (Required for Level 3) |
| Discount | double | Amount of discount. |
| Duty | double | Amount of duty charged. (Required for Level 3) |
| Subtotal | double | The amount of the transaction before tax, tip, shipping and discount have been applied. |
| CashBack | string | Denotes the amount of cashback customer requested. |
| DigitalGoods | string | Denotes the products were virtual or physical |
| Name | Type | Description |
|---|---|---|
| Field | string | Name of element. |
| Value | string | Value of element. |
| Name | Type | Description |
|---|---|---|
| ProductRefNum | string | Unique ID of the product assigned by the gateway (Optional) |
| ProductKey | string | Unique ID of the product assigned by the gateway |
| SKU | string | A stock-keeping unit is a unique identifier for each distinct product and service that can be purchased |
| ProductName | string | Name of the product |
| Description | string | Description of product or purchase |
| UnitPrice | string | Individual price of the unit |
| Qty | string | Total number of items |
| Taxable | boolean | Taxable good flag |
| CommodityCode | string | Numeric code used to classify the good or service. See the UNSPSC for codes. (Level 3) |
| UnitOfMeasure | string | Unit that quantity is measuring. Defaults to "EA". See list of valid Unit of Measure Codes (Level 3) |
| DiscountAmount | string | Amount line item was discounted (Level 3) |
| DiscountRate | string | The rate used to calculate discount (Level 3) |
| TaxAmount | string | Tax charged for this line item (Level 3) |
| TaxRate | string | The tax rate used for this line item (Level 3) |
| Name | Type | Description |
|---|---|---|
| Folio | string | Guest account reference number |
| RoomRate | string | Rate of room |
| Nights | string | How many nights the reservation is for |
| CheckInDate | string | Date guest will check in. |
| CheckOutDate | string | Date guest will check out. |
| ExtraChargeReasons | string | Comment field denoting why guest was charged extra. |
| RoomNumber | string | Guests room number |
| CustomerCode | string | Reference number for the guest |
| LengthOfStay | string | How long the guest will be staying |
| RoomTaxRate | string | Tax percentage for the room type booked. |
| NonRoomCharges | string | Any charges made outside of the booking costs. (Room Service, etc.) |
| RoomTaxAmount | string | Tax amount in dollars for the room. |
| PreferredCustomer | string | Denotes if this guest is a preferred customer. |
| ChargeType | string | Denotes how guest paid for the room. |
| DepartureTime | string | Time and date guest departed. |
| ArrivalTime | string | Time and date the guest arrived |
| Name | Type | Description |
|---|---|---|
| MerchRefNum | integer | gateway assigned Merchant ID |
| Activated | string | Date the merchant was created |
| ResellerEmail | string | Email address for reseller. |
| MerchantName | string | Company name of merchant, used to identify merchant |
| ContactInfo | object | Address and contact information for merchant |
| CallInPassword | string | Optional call in password for merchant. If a merchant has a call in password, they must provide this password to customer support staff before support will be given. If no call in password is set, support staff will verify merchant account info to clear the merchant |
| BillingInfo | object | Billing information and gateway package |
| CreditCardPlatform | string | Name of the credit card processor to set the merchant up on. Possible values are: FDMS, Tsys, Paymentech, Global, Planet Payment, MeS and Heartland. Leave blank if no credit card processing is requested. |
| CreditCardPlatformSetup | FieldValue | Array of processor specific setup information |
| eCheckPlatform | string | Name of the electronic check processor to set the merchant up on. |
| eCheckPlatformSetup | FieldValue | Array of processor specific setup information |
| Name | Type | Description |
|---|---|---|
| ResellerEmail | string | Email address for reseller. |
| MerchantName | string | Company name of merchant, used to identify merchant |
| ContactInfo | object | Address and contact information for merchant |
| CallInPassword | string | Optional call in password for merchant. If a merchant has a call in password, they must provide this password to customer support staff before support will be given. If no call in password is set, support staff will verify merchant account info to clear the merchant |
| BillingInfo | BillingInfo | Billing information and gateway package |
| SourceKeyName | string | Name of SourceKey to create when merchant is activated. Leave blank if no source key is requested |
| SourceKeyPin | string | Pin to assign to new SourceKey |
| EmailSourceKeyTo | string | Email address to send the new sourcekey to. The email will contain the sourcekey but not the pin |
| UserName | string | Username of merchant user that will be created when the application is activated. A password will be randomly assigned by the system. Merchant must change the password the first time they log in |
| EmailInstructionsTo | string | Email address to send the merchant console instructions to. The email will include the merchants username and password |
| CreditCardPlatform | string | Name of the credit card processor to set the merchant up on. Possible values are: FDMS, FDMS North, Tsys, Paymentech, Global, MeS, Rapid Connect, EPX and Heartland. Leave blank if no credit card processing is requested. |
| CreditCardIndustry | string | Merchant Industry type: "eCommerce", "Mail Order", "Retail (Swipe)", "Hotel", "Restaurant", "Utility/Bill Pay", "Utility/Bill Pay (Card Present)" |
| CreditCardPlatformSetup | FieldValue | Array of processor specific setup information (see below) |
| eCheckPlatform | string | Name of the electronic check processor to set the merchant up on. Possible values are: Vericheck, Checkgateway, Payliance, and Paya. Leave blank if no check processing is requested. |
| eCheckPlatformSetup | FieldValue | Array of processor specific setup information (contact integration support for list of fields) |
| ApplicationNotes | string | Notes or instructions for gateway staff activating merchant account, ie "Hold application until 3/4/10" |
| MerchRefNum | integer | Contains the Merchant ID Number once the application has been activated |
| ApplicationID | integer | The gateway assigned Application ID |
| Status | string | Contains the status of the application |
%MerchantApplicationSearchResult%
| Name | Type | Description |
|---|---|---|
| Limit | integer | The maximum number of merchants to be returned. |
| Applications | object | An array of Merchant application objects that match the search criteria. |
| ApplicationsMatched | integer | Number of merchants applications matched by search criteria. |
| ApplicationsReturned | integer | Number of merchants applications contained in this search result. |
| StartIndex | integer | The index where this result set begins (default is 0). |
| Name | Type | Description |
|---|---|---|
| MerchantsMatched | integer | Number of merchants matched by search criteria. |
| MerchantsReturned | integer | Number of merchants contained in this search result. |
| StartIndex | integer | The index where this result set begins (default is 0). |
| Limit | integer | The maximum number of merchants to be returned. |
| Merchant | object | An array of MerchantObjects matched by search criteria. |
| Name | Type | Description |
|---|---|---|
| MerchantID | integer | Merchant ID (assigned by the gateway). |
| MerchantName | string | Name of the merchant whose activity you are searching. |
| SalesCount | integer | Total number of sales processed by the merchant. |
| SalesAmount | double | Total dollar amount of sales processed. |
| CreditsCount | integer | Total number of credits processed by the merchant. |
| CreditsAmount | double | Total dollar amount of credits processed. |
| VoidsCount | integer | Total number of voids processed by the merchant. |
| VoidsAmount | double | Total dollar amount of voids processed. |
| DeclinesCount | integer | Total number of declines processed by the merchant. |
| DeclinesAmount | double | Total dollar amount of declines processed |
| CheckSalesCount | integer | Total number of check sales processed (by date entered) |
| CheckSalesAmount | double | Total dollar amount of check sales processed (by date entered) |
| CheckRefundsCount | integer | Total number of check refunds processed (by date entered) |
| CheckRefundsAmount | double | Total dollar amount of check refunds processed (by date entered) |
| ReturnedCheckSaleCount | integer | Total number of check sales returned (by date returned) |
| ReturnedCheckSaleAmount | double | Total dollar amount of check sales returned (by date returned) |
| ReturnedCheckRefundCount | integer | Total number of check refunds returned (by date returned) |
| ReturnedCheckRefundAmount | double | Total dollar amount of check refunds returned (by date returned) |
| CheckChargebacksCount | integer | Total number of check sales returned as chargebacks (by date returned) |
| CheckChargebacksAmount | double | Total dollar amount of check sales returned as chargebacks (by date returned) |
| SettledCheckSaleCount | integer | Total number of check sales settled (by date settled) |
| SettledCheckSaleAmount | double | Total dollar amount of check sales settled (by date settled) |
| SettledCheckRefundCount | integer | Total number of check refunds settled (by date settled) |
| SettledCheckRefundAmount | double | Total dollar amount of check refunds settled (by date settled) |
| LargeCheckSalesCount | integer | Total number of large check sales processed (by date entered). Large checks are any ach transaction that exceeds a merchants defined threshold (typically $5,000) |
| LargeCheckSalesAmount | double | Total dollar amount of large check sales processed (by date entered) |
| LargeCheckRefundsCount | integer | Total number of large check refunds processed (by date entered) |
| LargeCheckRefundsAmount | double | Total dollar amount of Large check refunds processed (by date entered) |
| CheckDepositCount | integer | Total number of ach batches deposited to merchant (not support for all ach platforms) |
| Name | Type | Description |
|---|---|---|
| MethodType | string | Type of payment method (CreditCard, ACH, StoredValue or Invoice) |
| MethodID | string | ID of payment method. This property is ignored when adding a new payment method but required if updating an existing method. |
| MethodName | string | Label for payment method. For example "Work Visa" or "Personal Checking." |
| SecondarySort | integer | If set to value greater than 0, use this method as backup in case default fails. Secondary methods will be run in ascending order. |
| Created | string | Date and time the method was created. |
| Modified | string | Date and time the method was last modified. |
| Expires | string | Date on which payment method will expire. Do not leave blank. Format: YYYY-MM-DD |
| CardHolder | string | Name of the card holder on credit/debit card. |
| CardNumber | string | Credit card number (required for credit cards). If data is coming from a swiper, base64_encode the entire raw block read from the swiper device and put %%enc://%% at the beginning. Example: %%enc://%%AAbbCdEEaa... |
| CardExpiration | string | Credit card expiration date in YYYY-MM format. It will also accept MMYY format. (required for credit cards) |
| AvsStreet | string | Street address for AVS (address verification system). (Optional but recommended for credit cards) |
| AvsZip | string | Zip code for AVS. (Optional but recommended for credit cards) |
| CardCode | string | CVV2/CID card identification code. This code is not stored and is only used when verifying a new payment method before it is added. (Optional for credit cards) |
| CardType | string | Type of credit card (Visa, Mastercard, etc). This is a read only parameter and will be ignored if set. |
| XID | string | XID value received from 3rd party Visa VPAS or MC UCAF. Can be sent with transaction, but cannot be stored in method. |
| CAVV | string | CAVV value received from 3rd party Visa VPAS or MC UCAF. Can be sent with transaction, but cannot be stored in method. |
| ECI | integer | ECI value. Can be sent with transaction, but cannot be stored in method. |
| Account | string | ACH Bank Account Number (required for checks) |
| AccountType | string | ACH Type of Bank Account (Checking or Savings, defaults to checking) |
| Routing | string | ACH Bank Routing Number (required for checks) |
| DriversLicense | string | Drivers license number used for check guarantee (optional) |
| DriversLicenseState | string | Drivers license state (optional) |
| RecordType | string | ACH transaction type (optional, should be left blank unless instructed differently by check processor) |
| MaxBalance | double | The maximum balance that may be charged on Invoice before transactions are declined |
| Balance | double | The funds left on the account. Transactions against this payment method may not exceed this balance |
| AutoReload | boolean | Set true if StoredValue card should automatically be reloaded |
| ReloadSchedule | string | Automatic reload schedule |
| ReloadThreshold | double | Balance that will trigger an automatic reload |
| ReloadAmount | double | Amount to automatically reload |
| ReloadMethodID | string | Payment method to use for reloading card |
| Name | Type | Description |
|---|---|---|
| Qty | string | Qty threshold for price |
| Price | string | Product Price |
| CustomerTier | string | Customer based price tier identifier |
| Name | Type | Description |
|---|---|---|
| ProductRefNum | string | Gateway assigned ID of product |
| ProductKey | string | Unique ID of the product assigned by the gateway |
| ProductID | string | Merchant assigned product ID |
| Category | string | Product category |
| SKU | string | Stock-Keeping Unit |
| UPC | string | Universal Product Code |
| Enabled | boolean | Enables the ability to store products |
| Name | string | Name of the product |
| Description | string | Product description |
| Model | string | Model of the product |
| Weight | string | Weight of the product |
| ShipWeight | string | Shipping weight of the product |
| Price | double | Price of the product |
| WholesalePrice | double | Wholesale price of the product |
| ListPrice | double | List price of the product |
| PriceTier | object | Qty and Customer based variable pricing tiers |
| TaxClass | string | Product's Tax Class |
| DateAvailable | string | Date the product is available for sale |
| Manufacturer | string | Maker of the product |
| PhysicalGood | boolean | Tangible/Shippable good. |
| MinQuantity | integer | Minimum quantity allowed |
| ImageURL | string | URL address of the product image |
| URL | string | URL of the product |
| ProductInventory | object | Product inventory levels |
| Modified | string | Date/time the product was last changed |
| Created | string | Date/time the product was created |
| Name | Type | Description |
|---|---|---|
| ProductCategoryRefNum | string | Gateway assign unique reference number |
| ProductCategoryKey | string | Gateway assign unique reference number |
| Name | string | Name of product category |
| Created | string | Timestamp for when the category was created |
| Modified | string | Timestamp for when the category was last modified |
| Name | Type | Description |
|---|---|---|
| InventoryLocationKey | string | Gateway assign unique reference number |
| InventoryLocation | string | Location of Inventory (Warehouse or location name) |
| QtyOnHand | string | Count of available units in stock |
| QtyOnOrder | string | Count of units on order (scheduled to be available on DateAvailable) |
| DateAvailable | string | Date that QtyOnOrder is scheduled to arrive |
| Name | Type | Description |
|---|---|---|
| ProductsMatched | integer | Total number of transactions matched |
| ProductsReturned | integer | Number of transactions returned in this result set |
| StartIndex | integer | The starting index used (defaults to 0) |
| Limit | integer | The max number transactions to return in each result set. |
| Product | array | An array Products for the matched criteria |
| Name | Type | Description |
|---|---|---|
| ReceiptRefNum | string | Gateway assigned ID of Receipt. (Ignored when adding a receipt) |
| Name | string | Name of receipt (used to identify receipt) |
| Target | string | Type of receipt output (Email or Print) |
| Subject | string | Subject line of email (Only applicable if "Target" is "Email") |
| FromEmail | string | From email address (Only applicable if "Target" is "Email") |
| ContentType | string | Content types supported by receipt (HTML, Text or Both) |
| TemplateHTML | string | HTML version of template (Base-64 Encoded) |
| TemplateText | string | Text version of template (Base-64 Encoded) |
| Name | Type | Description |
|---|---|---|
| Schedule | string | Frequency of recurring billing schedule. Possible values include: disabled, daily, weekly, bi-weekly (every two weeks), monthly, bi-monthly (every two months), quarterly, bi-annually (every six months), annually. |
| Next | string | Date this customer will be billed next. Must be formatted Year-Month-Day (ie 2011-07-04) |
| Expire | string | Date this billing entry will be disabled. |
| NumLeft | integer | Number of transactions remaining in recurring billing cycle. (Overrides the Expire parameter) |
| Amount | double | Amount to be billed in each transaction. |
| Enabled | boolean | Notes whether customer is currently enabled for recurring billing. |
| Name | Type | Description |
|---|---|---|
| Field | string | Name of field you are searching. |
| Type | string | Search condition. Possible Values are: - dneq -Does not Equal - eq -Equals - gt -Greater Than - lt -Less Than - gte -Greater Than or Equal To - lte -Less Than or Equal To - sw -Starts with - ew -Ends with - contains -contains - dncontain -Does not Contain - in -In List - notin -Not in List |
| Value | string | Value to search on |
| Name | Type | Description |
|---|---|---|
| SyncPosition | integer | Sequential id of sync log entry |
| ObjectName | string | Object type that was changed (products, products_categories, customers, etc) |
| RefNum | string | Reference number for object that was changed (ProductRefNum, CustRefNum, etc) |
| ChangeDate | string | The date/time that the changed occurred on the gateway (all times in PST) |
| Action | string | The type of change that occurred (insert,update or delete) |
| Name | Type | Description |
|---|---|---|
| ApiVersion | string | Version of the API |
| Environment | string | Production, Sandbox, or Staging |
| Datacenter | string | Location of the data-center |
| Time | string | Timestamp |
| Name | Type | Description |
|---|---|---|
| FirstName | String | Customer's First Name |
| LastName | String | Customer's Last Name |
| Company | String | Company or Organization Name |
| Street | String | Street Address Line 1 |
| Street2 | String | Street Address Line 2 |
| City | String | City |
| State | String | State or Province |
| Zip | String | Zip or Postal Code |
| Country | String | Country |
| Phone | String | Telephone Number |
| Fax | String | Fax Number |
| String | Email Address |
| Name | Type | Description |
|---|---|---|
| Status | string | Status of specified transaction. |
| TransactionResponse | object | Returns a TransactionResponse object containing the results of the transaction and all relevant data. |
| TransactionType | string | Type of transaction. (Sale, Credit, Void, AuthOnly, etc.) |
| CheckTrace | object | Tracking data for check transactions. Includes tracking number, effective posting date, date processed, date settled, date returned and bank notes. |
| DateTime | string | Date/time transaction was originally submitted. |
| AccountHolder | string | Name of the account holder. |
| Details | object | Transaction details: amount, clerk, currency, etc. |
| CreditCardData | object | CreditCardData. Required for credit card transactions. |
| CheckData | object | CheckData. Required for electronic check processing. |
| User | string | The username of the person who processed this transaction. |
| Source | string | The name of the source key that this transaction was processed under. |
| ServerIP | string | IP Address of the server that submitted the transaction to the gateway. |
| ClientIP | string | IP Address of client (if passed on from the server). |
| CustomerID | string | Customer ID |
| BillingAddress | object | Billing Address |
| ShippingAddress | object | Shipping Address |
| CustomFields | array | Array of FieldValue pairs. Additional transaction api fields (ie UMtimeout) can also be passed in via this array. Any field name starting with UM is assumed to be an api field and not a custom field. |
| LineItem | array | Array of line item details |
| LodgingDetails | object | Object which contains lodging details. |
| Name | Type | Description |
|---|---|---|
| Command | string | Processing Command. Possible values are: sale, credit, void, creditvoid, authonly, capture, postauth, check and checkcredit. Default is sale. |
| IgnoreDuplicate | boolean | Do not check for duplicate transaction. Set to "true" if you would like to override the duplicate transaction handling. |
| AuthCode | string | Original Authorization Code. Authorization Code obtained "offline" (ie telephone authorization). Only required for PostAuth. |
| RefNum | string | Original Transaction Reference Number. The RefNum received when a transaction was authorized via either the "sale" or "authonly" commands. Required for void and capture commands. Can also use TransKey here. |
| AccountHolder | string | Name of the account holder. |
| Details | object | Transaction details: amount, clerk, currency, etc. |
| CreditCardData | object | CreditCardData. Required for credit card transactions. |
| CheckData | object | CheckData. Required for electronic check processing. |
| ClientIP | string | IP Address of client. |
| CustomerID | string | Customer ID. |
| BillingAddress | object | Billing Address |
| ShippingAddress | object | Shipping Address |
| CustReceipt | boolean | True/False. True will cause a customer receipt to be sent. |
| CustReceiptName | string | Name of the receipt template to use. Defaults to the standard customer receipt. |
| RecurringBilling | object | RecurringBilling. Object describing if recurring billing cycle should be created if initial transaction is approved. |
| LineItem | array | Array of line item details |
| LodgingDetails | object | Object which contains lodging details. |
| CustomFields | array | Array of FieldValue pairs. Additional transaction api fields (ie UMtimeout) can also be passed in via this array. Any field name starting with UM is assumed to be an api field and not a custom field. |
| IfAuthExpired | string | Controls what will happen if the authorization has expired. Possible values are: - Error will block the capture request - ReAuth will attempt to reauthorize the funds - Capture will ignore the authorization date and proceed with capture. If left blank, Capture will be assumed. The amount of time between an authorization expires is controlled by the Expire Auths After setting. |
| AuthExpireDays | string | Sets number of days before an authorization expires. |
| ReleaseFunds | boolean | Set to true to release funds. Only used for voidTransaction. |
| IsRecurring | boolean | Flags a credit card transaction as a recurring payment when sent to the platforms for processing. This is not related to the RecurringBilling object above and it does not tie into the gateway's recurring billing system. Rather, this flag should be used by developers who are initiating the recurring transactions from within their own system and need to indicate that it is recurring. |
| Software | string | Free form string that can be used by the developer to record information about their software, version, build number or operating system details. Reported on the transaction detail screen, in custom reports or via api. |
| SaveCard | boolean | Set to "True" to tokenize card. |
| Name | Type | Description |
|---|---|---|
| TransKey | string | Transaction Reference Number This is the preferred Transaction Identifier (ALWAYS System Scoped) |
| RefNum | string | Transaction Reference Number (sometimes Merchant Scoped) |
| BatchRefNum | string | Batch Reference Number assigned by Gateway. |
| BatchKey | string | Batch Reference Number assigned by Gateway. |
| BatchNum | string | Batch Sequence Number |
| Result | string | Transaction Result (Approved, Declined, Error, etc) |
| ResultCode | string | Single character result code (A, D, or E) |
| AuthCode | string | Authorization Code |
| AuthAmount | double | Amount that was authorized. Could be less that Amount requested if AllowPartialAuth was true |
| RemainingBalance | double | Returns the balance remaining on some prepaid and stored value cards |
| AvsResultCode | string | AVS Result Code (1-3 characters) |
| AvsResult | string | Text Description of AvsResultCode |
| CardCodeResultCode | string | Card Code (CVV2) Verification Result Code (1 character) |
| CardCodeResult | string | Text Description of Card Code Result |
| CardLevelResultCode | string | List of codes can be found here. |
| CardLevelResult | string | Text Description of Card Level Result |
| CreditCardToken | object | This object describes a tokenized credit card. |
| ErrorCode | integer | Error Code (if transaction resulted in error) |
| CustNum | string | System assigned CustNum of stored customer record if one was used or created |
| CustKey | string | Customer Number (System assigned) |
| Error | string | Text Description of Error Code |
| AcsUrl | string | ACS Url for Verified by Visa or Mastercard Secure Code. |
| Payload | string | Payload for Verified by Visa or Mastercard Secure Code. |
| VpasResultCode | string | Vpas Result Code. |
| isDuplicate | boolean | If true, a duplicate transaction was detected and the response data returned is from original transaction. |
| ConvertedAmount | double | Transaction amount converted to new currency. |
| ConvertedAmountCurrency | string | Currency code for new currency. |
| ConversionRate | double | Rate used to convert transaction amount. |
| Status | string | Description of transaction status |
| StatusCode | string | Single character code for transaction status |
| ProfilerScore | string | Score generated by fraud profiler. |
| ProfilerResponse | string | Fraud profiler result: pass, warn, review. Based on score thresholds |
| ProfilerReason | string | Comma separated list of reason codes that contributed to the score. |
| Name | Type | Description |
|---|---|---|
| TransactionsMatched | integer | Total number of transactions matched |
| TransactionsReturned | integer | Number of transactions returned in this result set |
| ErrorsCount | integer | Total number of errors matched |
| DeclinesCount | integer | Total number of declines matched |
| SalesCount | integer | Total number of Sales matched |
| CreditsCount | integer | Total number of Credits matched |
| AuthOnlyCount | integer | Total number of AuthOnlys matched |
| VoidsCount | integer | Total number of Voids matched |
| SalesAmount | float | Total dollar amount of Sales matched |
| CreditsAmount | float | Total dollar amount of Credits matched |
| AuthOnlyAmount | float | Total dollar amount of AuthOnlys matched |
| VoidsAmount | float | Total dollar amount of Voids matched |
| ErrorsAmount | float | Total dollar amount of errors matched |
| DeclinesAmount | float | Total dollar amount of Declines matched |
| StartIndex | integer | The starting index used (defaults to 0) |
| Limit | integer | The max number transactions to return in each result set. |
| TransactionObject | object | An array TransactionObjects for the matched transactions |
| Name | Type | Description |
|---|---|---|
| OrgID | string | Organization ID |
| SessionID | string | Unique session identifier |