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"